{ "openapi": "3.1.0", "info": { "title": "XOS Public API", "version": "1.0.0-draft.2", "summary": "One API for Atlas, Gateway, Compass, SDKs and third parties.", "description": "Versioned REST API for XOS 4.0 (Section 10.1, ADR 0003). Cursor pagination with `limit` and `cursor`; sparse fieldsets with `fields`; filters with `filter[field][op]=value`; `Idempotency-Key` on every POST; `ETag` and `If-Match` on updates; RFC 9457 problem details; refusals as 422 with `refusal` set to NO_ANSWER, UNRATIFIED or REFUSE. Money is integer minor units with a currency; null is unpriced, never zero. Restricted fields the caller may not read stay present as `{ \"masked\": true, \"reason\": \"...\" }`. The active organization is bound to the credential.", "license": { "name": "AGPL-3.0-only", "identifier": "AGPL-3.0-only" } }, "servers": [ { "url": "/api/v1", "description": "This deployment." }, { "url": "https://api.ghxstship.tech/v1", "description": "GHXSTSHIP hosted production." } ], "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": [] }], "tags": [ { "name": "Home", "description": "Org dashboard, my work, gate readiness and alerts (Section 4.2)." }, { "name": "Projects", "description": "Projects, scope tree, jurisdiction and gate evidence (Section 4.2)." }, { "name": "Activity", "description": "The user-facing activity feed, separate from the audit ledger (Section 4.2)." }, { "name": "Schedule", "description": "Timeline records, baselines, dependencies, calendars and actuals (Section 4.2)." }, { "name": "Work", "description": "The record spine for all 26 kinds, and work orders with bids (Sections 3.10 and 4.2)." }, { "name": "Show", "description": "Run of show, cues, day sheets and call sheets (Section 4.2)." }, { "name": "Knowledge", "description": "SOPs with acknowledgment, documents with versions and controlled vocabulary (Section 4.2)." }, { "name": "Places", "description": "Venues, spaces, zones, capability documents, site plans and reconciliation (Section 4.2)." }, { "name": "Logistics", "description": "Shipments, dock slots, gate queue, staging and release (Section 4.2)." }, { "name": "Advancing", "description": "Advance packets, sections, recipients, submissions and riders (Section 4.2)." }, { "name": "Hospitality", "description": "Lodging, catering, travel and amenity fulfillment and BEOs (Section 4.2)." }, { "name": "Assets", "description": "Assets at class, unit and lot grain, custody, maintenance and damage (Section 4.2)." }, { "name": "Opportunities", "description": "Opportunities, applications, selection, offers, onboarding, engagements, ratings and pools (Sections 4.2 and 4.4)." }, { "name": "People", "description": "Role assignments, requisitions, offers and agreements (Section 4.2)." }, { "name": "Crew", "description": "Shifts, swaps, time, timesheets, rate cards, pay rates and payroll export (Section 4.2)." }, { "name": "Credentials", "description": "Credential categories, issuance, the Access Grid and scans (Section 4.2)." }, { "name": "Finance", "description": "Budgets, expenses, change orders, ledger, periods and the Universal Posting Line (Sections 3.11 and 4.2)." }, { "name": "Procurement", "description": "RFQs, purchase orders, receipts, three-way match and catalog bindings (Section 4.2)." }, { "name": "Vendors", "description": "Vendors, classes, prequalification, insurance, scorecards and sponsor entitlements (Section 4.2)." }, { "name": "Safety", "description": "Inspections, the permit engine, incidents with dispatch, emergency codes and radio (Section 4.2)." }, { "name": "Canon", "description": "Read-only canon from `xpms`, cached by canon generation, and tenant extension proposals (Sections 4.2 and 7.2)." }, { "name": "Reports", "description": "Report builder, dashboards, scheduled delivery and the built-in analytics reports (Sections 4.2 and 4.6.4)." }, { "name": "Settings", "description": "Organization, access, security, white label, integrations, billing, data and privacy (Sections 4.2 and 8)." }, { "name": "Gateway", "description": "External-party resources: marketplace, saved searches, profile shares, availability, messages, tax and payout details (Section 4.4)." }, { "name": "Identity", "description": "People, organizations, memberships, assignments, representation and profiles (Section 4.8)." }, { "name": "Platform", "description": "Custom objects, imports and exports, approvals, comments, notifications, saved views, trash and templates (Sections 4.6 and 4.10)." }, { "name": "Workforce", "description": "Groups, chat, the directory, the feed, polls, surveys, recognition, events, forms, training, the handbook, the help desk and site operations (Section 4.9)." } ], "components": { "securitySchemes": { "bearerJwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Short-lived Supabase session JWT for Atlas, Gateway and Compass. The active organization is the one chosen in the context switcher." }, "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "xos_live API key", "description": "Org-scoped API key for servers, sent as `Authorization: Bearer xos_live_...`. Keys are hashed, capability-scoped and expiring." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 authorization code flow with PKCE (S256) for user-delegated apps. Scopes map one to one to capability groups in `packages/schemas/capabilities.yaml`.", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "refreshUrl": "/oauth/token", "scopes": { "home": "Capability group `home`: home.dashboard.read, home.alerts.read.", "inbox": "Capability group `inbox`: inbox.notifications.read, inbox.notifications.write.", "my_work": "Capability group `my_work`: my_work.items.read.", "projects": "Capability group `projects`: projects.project.read, projects.project.create, projects.project.write, projects.project.archive, projects.scope.write, projects.gate.read, projects.gate.evidence.write, projects.gate.transition, projects.members.manage, projects.settings.write, projects.template.write, projects.project.export.", "schedule": "Capability group `schedule`: schedule.timeline.read, schedule.timeline.write, schedule.milestone.write, schedule.baseline.write, schedule.timeline.export.", "work": "Capability group `work`: work.record.read, work.record.write, work.work_order.read, work.work_order.write, work.work_order.award, work.punch_list.write, work.recurring.write, work.record.export.", "show": "Capability group `show`: show.run_of_show.read, show.run_of_show.write, show.cue.call, show.day_sheet.write, show.call_sheet.publish.", "advancing": "Capability group `advancing`: advancing.packet.read, advancing.packet.write, advancing.packet.send, advancing.submission.review, advancing.rider.write, advancing.reconciliation.write.", "places": "Capability group `places`: places.venue.read, places.venue.write, places.space.write, places.capability_document.write, places.site_plan.write.", "logistics": "Capability group `logistics`: logistics.shipment.read, logistics.shipment.write, logistics.dock_slot.write, logistics.yard.write, logistics.release.approve.", "hospitality": "Capability group `hospitality`: hospitality.fulfillment.read, hospitality.fulfillment.write, hospitality.beo.write, hospitality.beo.approve, hospitality.accommodation.write.", "assets": "Capability group `assets`: assets.asset.read, assets.asset.write, assets.custody.write, assets.maintenance.write, assets.damage.write, assets.write_off.approve, assets.asset.export.", "credentials": "Capability group `credentials`: credentials.credential.read, credentials.category.write, credentials.access_grid.write, credentials.credential.issue, credentials.credential.revoke, credentials.scan.write, credentials.scan_log.read.", "safety": "Capability group `safety`: safety.permit.read, safety.permit.write, safety.inspection.read, safety.inspection.write, safety.inspection.sign_off, safety.inspection_template.write, safety.incident.read, safety.incident.write, safety.incident.dispatch, safety.incident.close, safety.emergency_code.write, safety.radio_channel.write.", "people": "Capability group `people`: people.directory.read, people.profile.read, people.profile.write, people.role.write, people.requisition.read, people.requisition.write, people.requisition.approve, people.offer.write, people.offer.approve, people.agreement.write, people.certification.read, people.certification.write, people.certification.verify.", "opportunities": "Capability group `opportunities`: opportunities.posting.read, opportunities.posting.write, opportunities.posting.publish, opportunities.application.read, opportunities.application.review, opportunities.selection.decide, opportunities.offer.send, opportunities.onboarding.write, opportunities.engagement.read, opportunities.engagement.write, opportunities.pool.write, opportunities.rating.write, opportunities.marketplace.manage.", "crew": "Capability group `crew`: crew.schedule.read, crew.shift.read, crew.shift.write, crew.swap.request, crew.swap.approve, crew.time_entry.read, crew.time_entry.write, crew.timesheet.read, crew.timesheet.submit, crew.timesheet.approve, crew.time_off.request, crew.time_off.approve, crew.rate_card.read, crew.rate_card.write, crew.pay_period.manage, crew.payroll.export.", "finance": "Capability group `finance`: finance.budget.read, finance.budget.write, finance.budget.approve, finance.expense.read, finance.expense.write, finance.expense.approve, finance.change_order.read, finance.change_order.write, finance.change_order.price, finance.change_order.approve, finance.po.approve, finance.invoice.read, finance.invoice.write, finance.invoice.approve, finance.payment.read, finance.payment.write, finance.payment.approve, finance.journal.read, finance.journal.write, finance.journal.post, finance.period.manage, finance.period.close, finance.gl.read, finance.cost_center.write, finance.upl.export.", "procurement": "Capability group `procurement`: procurement.rfq.read, procurement.rfq.write, procurement.rfq.issue, procurement.bid.read, procurement.bid.unseal, procurement.bid.award, procurement.po.read, procurement.po.write, procurement.po.send, procurement.receipt.write, procurement.invoice_match.write, procurement.catalog.read, procurement.catalog.write.", "vendors": "Capability group `vendors`: vendors.vendor.read, vendors.vendor.write, vendors.bank_details.write, vendors.class.write, vendors.prequalification.approve, vendors.coi.write, vendors.scorecard.write, vendors.entitlement.write.", "knowledge": "Capability group `knowledge`: knowledge.sop.read, knowledge.sop.write, knowledge.sop.publish, knowledge.sop.acknowledge, knowledge.document.read, knowledge.document.write, knowledge.verbiage.read, knowledge.verbiage.write.", "reports": "Capability group `reports`: reports.report.read, reports.report.write, reports.schedule.write, reports.report.export.", "canon": "Capability group `canon`: canon.taxonomy.read, canon.extension.write.", "activity": "Capability group `activity`: activity.feed.read.", "audit": "Capability group `audit`: audit.log.read, audit.log.export.", "org": "Capability group `org`: org.settings.read, org.profile.write, org.general.write, org.legal_entities.write, org.members.read, org.members.invite, org.members.manage, org.roles.manage, org.teams.manage, org.workspaces.manage, org.departments.write, org.locations.write, org.security.write, org.access_reviews.manage, org.access_grants.manage, org.view_as_role.use, org.white_label.write, org.modules.write, org.templates.write, org.custom_fields.write, org.custom_objects.write, org.views.write, org.numbering.write, org.automations.write, org.approval_policies.write, org.spend_authority.write, org.separation_of_duties.write, org.time_attendance.write, org.scheduling.write, org.payroll.write, org.gateway.write, org.communication.write, org.notifications.write, org.ai.write, org.help.write, org.integrations.manage, org.api_keys.manage, org.webhooks.manage, org.localization.write, org.usage.read, org.partner.manage, org.billing.read, org.billing.manage, org.legal.read, org.legal.accept, org.support_session.grant, org.break_glass.use, org.ownership.transfer, org.organization.archive, org.organization.delete.", "data": "Capability group `data`: data.classification.write, data.export.run, data.export.confidential, data.request.manage, data.retention.write, data.legal_hold.manage, data.export.restricted, data.restricted.read.payroll, data.restricted.read.banking, data.restricted.read.tax, data.restricted.read.government_id, data.restricted.read.medical.", "me": "Capability group `me`: me.profile.write, me.account.write, me.preferences.write, me.notifications.write, me.out_of_office.write, me.work_details.write, me.calendar_feeds.write, me.api_tokens.write." } } } } }, "headers": { "ETag": { "description": "Entity tag of the returned version; send it as `If-Match` to update.", "schema": { "type": "string", "example": "\"W/1a2b3c4d\"" } }, "RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer", "example": 600 } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "example": 598 } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer", "example": 42 } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "responses": { "BadRequest": { "description": "The request is malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "/problems/bad-request", "title": "Bad Request", "status": 400, "detail": "The cursor is not valid for this list." } } } }, "Unauthorized": { "description": "No valid credential was presented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The access token has expired." } } } }, "NotFound": { "description": "The resource does not exist or the caller may not see it. A hidden resource is always 404, never 403.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "/problems/not-found", "title": "Not Found", "status": 404, "detail": "No resource with this identifier is visible to you." } } } }, "Conflict": { "description": "The request conflicts with the current state, such as an Idempotency-Key reused with a different body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "/problems/conflict", "title": "Conflict", "status": 409, "detail": "This Idempotency-Key was used with a different request body." } } } }, "PreconditionFailed": { "description": "The If-Match tag is stale: the resource changed since it was read.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "/problems/precondition-failed", "title": "Precondition Failed", "status": 412, "detail": "The resource changed since you read it. Fetch it again and retry." } } } }, "PreconditionRequired": { "description": "If-Match is required on updates.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "/problems/precondition-required", "title": "Precondition Required", "status": 428, "detail": "Send the ETag you read as If-Match." } } } }, "Unprocessable": { "description": "The request failed validation, or a rule refused it. A refusal carries `refusal` (NO_ANSWER, UNRATIFIED or REFUSE) and a `reason`; a separation of duties refusal names the rule.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RefusalProblem" }, { "$ref": "#/components/schemas/ValidationProblem" } ] }, "examples": { "refusal": { "summary": "Separation of duties refusal", "value": { "type": "/problems/refused", "title": "Refused", "status": 422, "detail": "The request was refused by a rule.", "refusal": "REFUSE", "reason": "The creator of a purchase order cannot approve it.", "rule": "sod.po.creator_cannot_approve" } }, "validation": { "summary": "Validation failure", "value": { "type": "/problems/validation", "title": "Unprocessable Content", "status": 422, "detail": "One field is invalid.", "errors": [{ "pointer": "/title", "detail": "Required." }] } } } } } }, "TooManyRequests": { "description": "Rate limit exceeded. Retry after the number of seconds in `Retry-After`.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "/problems/rate-limited", "title": "Too Many Requests", "status": 429, "detail": "Retry in 30 seconds." } } } } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "URI reference that identifies the problem type.", "example": "/problems/not-found" }, "title": { "type": "string", "description": "Short summary of the problem type.", "example": "Not Found" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code.", "example": 404 }, "detail": { "type": "string", "description": "Explanation specific to this occurrence.", "example": "No project with this identifier is visible to you." }, "instance": { "type": "string", "description": "URI reference that identifies this occurrence.", "example": "/api/v1/projects/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["type", "title", "status"], "description": "RFC 9457 problem details, served as application/problem+json." }, "RefusalProblem": { "type": "object", "properties": { "type": { "type": "string", "description": "URI reference that identifies the problem type.", "example": "/problems/not-found" }, "title": { "type": "string", "description": "Short summary of the problem type.", "example": "Not Found" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code.", "example": 404 }, "detail": { "type": "string", "description": "Explanation specific to this occurrence.", "example": "No project with this identifier is visible to you." }, "instance": { "type": "string", "description": "URI reference that identifies this occurrence.", "example": "/api/v1/projects/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "refusal": { "$ref": "#/components/schemas/Refusal" }, "reason": { "type": "string", "description": "Why the request was refused, in sentence case.", "example": "The creator of a purchase order cannot approve it." }, "rule": { "type": "string", "description": "The rule that refused the request, such as a separation of duties rule.", "example": "sod.po.creator_cannot_approve" } }, "required": ["type", "title", "status", "refusal", "reason"], "description": "Problem details for a refusal. Returned with status 422." }, "Refusal": { "type": "string", "enum": ["NO_ANSWER", "UNRATIFIED", "REFUSE"], "description": "Refusal outcome (Section 3.7). NO_ANSWER: the data does not support an answer. UNRATIFIED: the value is proposed and not ratified. REFUSE: a rule forbids the action.", "example": "REFUSE" }, "ValidationProblem": { "type": "object", "properties": { "type": { "type": "string", "description": "URI reference that identifies the problem type.", "example": "/problems/not-found" }, "title": { "type": "string", "description": "Short summary of the problem type.", "example": "Not Found" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code.", "example": 404 }, "detail": { "type": "string", "description": "Explanation specific to this occurrence.", "example": "No project with this identifier is visible to you." }, "instance": { "type": "string", "description": "URI reference that identifies this occurrence.", "example": "/api/v1/projects/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the invalid member.", "example": "/title" }, "detail": { "type": "string", "description": "What is wrong with the value.", "example": "Required." } }, "required": ["pointer", "detail"] }, "description": "Invalid members of the request." } }, "required": ["type", "title", "status", "errors"], "description": "Problem details for a request that failed schema validation. Returned with status 422." }, "Limit": { "type": "integer", "minimum": 1, "maximum": 200, "example": 50 }, "Cursor": { "type": "string", "minLength": 1, "example": "eyJpZCI6IjAxOTJmMWUyIn0" }, "Fields": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*(,[a-z_][a-z0-9_]*)*$", "example": "id,title,record_state" }, "Sort": { "type": "string", "pattern": "^-?[a-z_][a-z0-9_]*(,-?[a-z_][a-z0-9_]*)*$", "example": "starts_at,-updated_at" }, "Filter": { "type": "object", "additionalProperties": { "type": "object", "properties": { "eq": { "type": "string" }, "ne": { "type": "string" }, "lt": { "type": "string" }, "lte": { "type": "string" }, "gt": { "type": "string" }, "gte": { "type": "string" }, "in": { "type": "string" }, "is_null": { "type": "string" }, "contains": { "type": "string" } } }, "example": { "record_state": { "eq": "Blocked" } } }, "IdempotencyKey": { "type": "string", "minLength": 8, "maxLength": 255, "example": "8f14e45f-ceea-467f-a0e6-1d2c3b4a5968" }, "IfMatch": { "type": "string", "minLength": 1, "example": "\"W/1a2b3c4d\"" }, "HomeSummary": { "type": "object", "properties": { "open_work_count": { "type": "integer", "minimum": 0, "description": "Records assigned to the caller that are not Complete or Canceled.", "example": 7 }, "blocked_work_count": { "type": "integer", "minimum": 0, "description": "Assigned records that are Blocked.", "example": 1 }, "projects_at_risk_count": { "type": "integer", "minimum": 0, "description": "Projects with an unsatisfied blocking criterion at the next gate.", "example": 2 }, "alert_count": { "type": "integer", "minimum": 0, "description": "Unread alerts.", "example": 3 }, "committed_spend": { "$ref": "#/components/schemas/MoneyTotal" } }, "required": [ "open_work_count", "blocked_work_count", "projects_at_risk_count", "alert_count", "committed_spend" ], "description": "The org dashboard: my work, gate readiness and alerts for the caller." }, "MoneyTotal": { "type": "object", "properties": { "total_minor": { "type": ["integer", "null"], "description": "Sum of priced inputs in minor units; null when every input is unpriced.", "example": 1250000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "unpriced_count": { "type": "integer", "minimum": 0, "description": "Number of inputs that are unpriced (null) and were not summed.", "example": 2 } }, "required": ["total_minor", "currency", "unpriced_count"], "description": "A money aggregate that never coerces unpriced inputs to zero." }, "ProjectPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Project key, chosen by the caller and unique in the organization; it addresses the project in Atlas URLs.", "example": "NWL-24" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Project name, Title Case.", "example": "Harborfront Summer Series" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Project description.", "example": "Six weekend shows on the harbor lawn." }, "workspace_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "region_code": { "$ref": "#/components/schemas/RegionCode" }, "tier_code": { "anyOf": [{ "$ref": "#/components/schemas/TierCode" }, { "type": "null" }] }, "current_phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "project_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Project lifecycle state. A Title Case value from the lifecycle's database enum.", "example": "Active" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Base currency of the project.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First show day.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last show day.", "example": "2026-10-08" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone of the project; local times are entered in it.", "example": "America/New_York" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the primary venue of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "client_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the client counterparty the project is produced for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "production_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Production lifecycle state, which runs beside the project state; changes only through its transition RPC. A Title Case value from the lifecycle's database enum.", "example": "Proposed" }, "archived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the project was archived; archived projects leave the default lists.", "example": "2026-10-08T14:30:00Z" }, "anchor_on": { "type": ["string", "null"], "format": "date", "description": "Anchor date (usually the show day) that template day offsets count from.", "example": "2026-10-08" }, "budget_envelope_minor": { "type": ["integer", "null"], "description": "Budget envelope approved for the project. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 25000000, "format": "int64" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_key", "name", "description", "workspace_id", "jurisdiction_id", "region_code", "tier_code", "current_phase_code", "project_state", "currency", "starts_on", "ends_on", "time_zone", "venue_id", "client_counterparty_id", "production_state", "archived_at", "anchor_on", "budget_envelope_minor" ], "description": "A production project. Jurisdiction is resolved at gate 1." }, "JurisdictionId": { "type": ["string", "null"], "pattern": "^[A-Z]{2}(-[A-Z0-9]+)*$", "description": "Jurisdiction identifier from `xpms.dim_jurisdiction`. An unpopulated jurisdiction returns no answer.", "example": "US-FL" }, "RegionCode": { "type": ["string", "null"], "pattern": "^[A-Z]{2}(-[A-Z0-9]+)+$", "description": "Cost region code from `xpms.dim_region`.", "example": "NA-SE-MIA" }, "TierCode": { "type": "string", "pattern": "^[0-9]{2}$", "description": "Tier of experience code from `xpms.dim_tier`.", "example": "04" }, "PhaseCode": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Phase code from `xpms.dim_phase`, ordered by gate ordinal.", "example": "SCP" }, "ProjectCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Project name, Title Case.", "example": "Harborfront Summer Series" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Project description.", "example": "Six weekend shows on the harbor lawn." }, "workspace_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "region_code": { "$ref": "#/components/schemas/RegionCode" }, "tier_code": { "anyOf": [{ "$ref": "#/components/schemas/TierCode" }, { "type": "null" }] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Base currency of the project.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First show day.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last show day.", "example": "2026-10-08" }, "project_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Project key, chosen by the caller and unique in the organization; it addresses the project in Atlas URLs.", "example": "NWL-24" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone of the project; local times are entered in it.", "example": "America/New_York" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the primary venue of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name", "project_key", "time_zone"], "description": "Fields accepted when creating a Project." }, "ProjectUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Project name, Title Case.", "example": "Harborfront Summer Series" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Project description.", "example": "Six weekend shows on the harbor lawn." }, "workspace_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "region_code": { "$ref": "#/components/schemas/RegionCode" }, "tier_code": { "anyOf": [{ "$ref": "#/components/schemas/TierCode" }, { "type": "null" }] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Base currency of the project.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First show day.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last show day.", "example": "2026-10-08" }, "project_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Project key, chosen by the caller and unique in the organization; it addresses the project in Atlas URLs.", "example": "NWL-24" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone of the project; local times are entered in it.", "example": "America/New_York" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the primary venue of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "client_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the client counterparty the project is produced for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "anchor_on": { "type": ["string", "null"], "format": "date", "description": "Anchor date (usually the show day) that template day offsets count from.", "example": "2026-10-08" }, "budget_envelope_minor": { "type": ["integer", "null"], "description": "Budget envelope approved for the project. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 25000000, "format": "int64" } }, "description": "Fields accepted when updating a Project. Omitted fields are unchanged." }, "ProjectTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Proposed" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Active" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "GateTransitionRequest": { "type": "object", "properties": { "expected_phase_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "The phase the caller believes the project is in (compare-and-set).", "example": "SCP" }, "to_phase_code": { "$ref": "#/components/schemas/PhaseCode" } }, "required": ["expected_phase_code", "to_phase_code"], "description": "Request to pass the current gate." }, "GateReadinessPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GateReadiness" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "GateReadiness": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "gate": { "type": "integer", "minimum": 1, "description": "Gate ordinal.", "example": 3 }, "criterion_id": { "$ref": "#/components/schemas/CriterionId" }, "blocking": { "type": "boolean", "description": "Whether the criterion blocks the gate.", "example": true }, "satisfied": { "type": "boolean", "description": "Whether evidence satisfies the criterion.", "example": false } }, "required": ["project_id", "gate", "criterion_id", "blocking", "satisfied"], "description": "Readiness of one gate criterion for a project. Derived, never stored by hand." }, "CriterionId": { "type": "string", "pattern": "^G[1-9]\\.[A-Z0-9_]+$", "description": "Gate criterion identifier from `xpms.dim_gate_criterion`.", "example": "G1.BUDGET_ENVELOPE" }, "ScopeNodePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeNode" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ScopeNode": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "parent_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the parent scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Scope code, unique in the project.", "example": "E01" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Scope node name.", "example": "Opening Weekend" }, "node_kind": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Kind of node. A Title Case value from the lifecycle's database enum.", "example": "Show" }, "path": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Materialized ltree path, derived.", "example": "root.e01" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "parent_id", "scope_code", "name", "node_kind", "path" ], "description": "A node of the project scope tree: engagement root, standing venue or show." }, "ScopeNodeCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "parent_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the parent scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Scope code, unique in the project.", "example": "E01" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Scope node name.", "example": "Opening Weekend" }, "node_kind": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Kind of node. A Title Case value from the lifecycle's database enum.", "example": "Show" } }, "required": ["project_id", "scope_code", "name", "node_kind"], "description": "Fields accepted when creating a ScopeNode." }, "ScopeNodeUpdate": { "type": "object", "properties": { "scope_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Scope code, unique in the project.", "example": "E01" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Scope node name.", "example": "Opening Weekend" }, "node_kind": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Kind of node. A Title Case value from the lifecycle's database enum.", "example": "Show" } }, "description": "Fields accepted when updating a ScopeNode. Omitted fields are unchanged." }, "ProjectPhaseTransitionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectPhaseTransition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectPhaseTransition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project phase transition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "from_phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "to_phase_code": { "anyOf": [{ "$ref": "#/components/schemas/PhaseCode" }, { "type": "null" }] }, "transitioned_at": { "type": "string", "format": "date-time", "description": "When the gate was passed.", "example": "2026-10-08T14:30:00Z" }, "transitioned_by": { "type": "string", "format": "uuid", "description": "Identifier of the person who passed the gate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "from_phase_code", "to_phase_code", "transitioned_at", "transitioned_by" ], "description": "An append-only gate transition of a project." }, "GateEvidencePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GateEvidence" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "GateEvidence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the gate evidence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "criterion_id": { "$ref": "#/components/schemas/CriterionId" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record that evidences the criterion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "attested_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who attested the evidence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "attested_at": { "type": "string", "format": "date-time", "description": "When the evidence was attested.", "example": "2026-10-08T14:30:00Z" }, "assertion_rank": { "type": "integer", "minimum": 0, "description": "Assertion rank of the evidence, 0 to 4.", "example": 4 }, "evidence_uri": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Where the evidence lives: a document or record URI.", "example": "urn:xpms:documents:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note on the evidence.", "example": "Signed by the venue manager." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "criterion_id", "record_id", "attested_by", "attested_at", "assertion_rank", "evidence_uri", "note" ], "description": "Evidence for a gate criterion. One evidence spine serves every criterion." }, "GateEvidenceCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "criterion_id": { "$ref": "#/components/schemas/CriterionId" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record that evidences the criterion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "assertion_rank": { "type": "integer", "minimum": 0, "description": "Assertion rank of the evidence, 0 to 4.", "example": 4 }, "evidence_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the evidence lives: a document or record URI.", "example": "urn:xpms:documents:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note on the evidence.", "example": "Signed by the venue manager." } }, "required": ["project_id", "criterion_id", "assertion_rank", "evidence_uri"], "description": "Fields accepted when creating a GateEvidence." }, "ActivityEventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ActivityEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the activity event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "actor_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who acted.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "verb": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "What happened.", "example": "record.state_changed" }, "subject_urn": { "type": "string", "minLength": 1, "maxLength": 300, "description": "URN of the subject.", "example": "urn:xpms:record:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When it happened.", "example": "2026-10-08T14:30:00Z" }, "summary": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Rendered summary key arguments.", "example": "Moved to Scheduled" }, "domain_event_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the domain event the activity row shows, as webhooks and the outbox name it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "actor_id", "verb", "subject_urn", "project_id", "occurred_at", "summary", "domain_event_id" ], "description": "A user-facing activity feed entry, separate from the compliance audit ledger." }, "ScheduleBaselinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleBaseline" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ScheduleBaseline": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the schedule baseline.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Baseline name.", "example": "Gate 3 Baseline" }, "captured_at": { "type": "string", "format": "date-time", "description": "When the baseline was captured.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "name", "captured_at" ], "description": "A frozen schedule baseline for variance tracking." }, "ScheduleBaselineCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Baseline name.", "example": "Gate 3 Baseline" } }, "required": ["project_id", "name"], "description": "Fields accepted when creating a ScheduleBaseline." }, "ScheduleActualPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleActual" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ScheduleActual": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the schedule actual.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "actual_start_at": { "type": ["string", "null"], "format": "date-time", "description": "Actual start.", "example": "2026-10-08T14:30:00Z" }, "actual_end_at": { "type": ["string", "null"], "format": "date-time", "description": "Actual finish.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_id", "actual_start_at", "actual_end_at" ], "description": "Actual start and finish of a record." }, "ScheduleActualCreate": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "actual_start_at": { "type": ["string", "null"], "format": "date-time", "description": "Actual start.", "example": "2026-10-08T14:30:00Z" }, "actual_end_at": { "type": ["string", "null"], "format": "date-time", "description": "Actual finish.", "example": "2026-10-08T14:30:00Z" } }, "required": ["record_id"], "description": "Fields accepted when creating a ScheduleActual." }, "ScheduleActualUpdate": { "type": "object", "properties": { "actual_start_at": { "type": ["string", "null"], "format": "date-time", "description": "Actual start.", "example": "2026-10-08T14:30:00Z" }, "actual_end_at": { "type": ["string", "null"], "format": "date-time", "description": "Actual finish.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a ScheduleActual. Omitted fields are unchanged." }, "CalendarPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Calendar": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Calendar name.", "example": "Venue Working Days" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "time_zone", "project_id" ], "description": "A working calendar with its time zone." }, "CalendarCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Calendar name.", "example": "Venue Working Days" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name", "time_zone"], "description": "Fields accepted when creating a Calendar." }, "CalendarUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Calendar name.", "example": "Venue Working Days" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Calendar. Omitted fields are unchanged." }, "RecordDependencyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordDependency" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RecordDependency": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record dependency.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "predecessor_id": { "type": "string", "format": "uuid", "description": "Identifier of the predecessor record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "successor_id": { "type": "string", "format": "uuid", "description": "Identifier of the successor record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "dependency_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Dependency type.", "example": "finish_to_start" }, "lag_minutes": { "type": "integer", "minimum": -100000, "description": "Lag in minutes; negative for lead.", "example": 0 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "predecessor_id", "successor_id", "dependency_type", "lag_minutes" ], "description": "A dependency between two records." }, "RecordDependencyCreate": { "type": "object", "properties": { "predecessor_id": { "type": "string", "format": "uuid", "description": "Identifier of the predecessor record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "successor_id": { "type": "string", "format": "uuid", "description": "Identifier of the successor record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "dependency_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Dependency type.", "example": "finish_to_start" }, "lag_minutes": { "type": "integer", "minimum": -100000, "description": "Lag in minutes; negative for lead.", "example": 0 } }, "required": ["predecessor_id", "successor_id", "dependency_type", "lag_minutes"], "description": "Fields accepted when creating a RecordDependency." }, "RecordRecurrencePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordRecurrence" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RecordRecurrence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record recurrence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the template record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rrule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "RFC 5545 recurrence rule.", "example": "FREQ=WEEKLY;BYDAY=SA" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "until": { "type": ["string", "null"], "format": "date", "description": "Last date of the series.", "example": "2026-10-08" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_id", "rrule", "time_zone", "until" ], "description": "A recurrence rule that generates records." }, "RecordRecurrenceCreate": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the template record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rrule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "RFC 5545 recurrence rule.", "example": "FREQ=WEEKLY;BYDAY=SA" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "until": { "type": ["string", "null"], "format": "date", "description": "Last date of the series.", "example": "2026-10-08" } }, "required": ["record_id", "rrule", "time_zone"], "description": "Fields accepted when creating a RecordRecurrence." }, "RecordRecurrenceUpdate": { "type": "object", "properties": { "rrule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "RFC 5545 recurrence rule.", "example": "FREQ=WEEKLY;BYDAY=SA" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "until": { "type": ["string", "null"], "format": "date", "description": "Last date of the series.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a RecordRecurrence. Omitted fields are unchanged." }, "RecordPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Record" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Record": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Display key issued by `next_sequence`.", "example": "NWL-24-118" }, "record_kind": { "$ref": "#/components/schemas/RecordKind" }, "record_subtype": { "$ref": "#/components/schemas/RecordSubtype" }, "record_class": { "$ref": "#/components/schemas/RecordClass" }, "record_state": { "$ref": "#/components/schemas/RecordState" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Title, validated against the kind's title grammar on write.", "example": "Install Main Stage Truss" }, "scope_node_id": { "type": "string", "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "xyz": { "$ref": "#/components/schemas/Xyz" }, "owner_party_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the owning person or organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "accountable_party_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the accountable person or organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Start of the record window.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "End of the record window.", "example": "2026-10-08T14:30:00Z" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "Due instant.", "example": "2026-10-08T14:30:00Z" }, "blocker_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "The named blocker; required when Blocked.", "example": "Waiting on the rigging plot." }, "replan_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Replan reason; required when Deferred.", "example": "Moved to the second weekend." }, "external_visibility": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRoleType" }, "description": "External role types that may see the record; empty means internal only. Stored as junction rows, presented as a set.", "example": ["Vendor"] }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project the record belongs to, derived from its scope node and never changed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "parent_record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the summary record this record rolls up to, in the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "wbs_code": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "pattern": "^[0-9]+(\\.[0-9]+)*$", "description": "Work breakdown structure code, dot separated.", "example": "1.2.1" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "What the record involves, in sentence case.", "example": "Rig the downstage truss." }, "sop_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the standard operating procedure that governs the work.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_code": { "anyOf": [{ "$ref": "#/components/schemas/TeamId" }, { "type": "null" }] }, "assignee_membership_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Identifier of the membership assigned to the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": "Memberships assigned to the record (app.record_assignments), oldest first.", "example": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"] }, "progress_pct": { "type": ["number", "null"], "minimum": 0, "maximum": 100, "description": "Progress of a task record, as a percentage.", "example": 40 }, "permit_identifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Permit identifier the authority issued, on a permit record.", "example": "BP-2027-0611" }, "inspection_result_enum_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Inspection Result enumeration row (Standard Library) of an inspection record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_key", "record_kind", "record_subtype", "record_class", "record_state", "title", "scope_node_id", "phase_code", "urid", "xyz", "owner_party_id", "accountable_party_id", "starts_at", "ends_at", "due_at", "blocker_text", "replan_reason", "external_visibility", "project_id", "parent_record_id", "wbs_code", "description", "sop_id", "team_code", "assignee_membership_ids", "progress_pct", "permit_identifier", "inspection_result_enum_id" ], "description": "A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`." }, "RecordKind": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Record kind from `xpms.dim_record_kind` (26 kinds, Section 3.10).", "example": "Task" }, "RecordSubtype": { "type": ["string", "null"], "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Kind-scoped record subtype from `xpms.dim_record_subtype`. A subtype of one kind cannot be stored on another.", "example": "Design" }, "RecordClass": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Record class from `xpms.dim_record_kind`, derived from the kind.", "example": "Work" }, "RecordState": { "type": "string", "enum": [ "Proposed", "Ready", "Scheduled", "Active", "Blocked", "In Review", "Complete", "Deferred", "Canceled" ], "description": "Record state (Section 3.10). Blocked names its blocker, Deferred carries a replan reason, Canceled is retained.", "example": "Scheduled" }, "UridAtAnyGrain": { "type": ["string", "null"], "pattern": "^[0-9]000(\\.[0-9]{2}){1,2}$", "description": "URID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.", "example": "4000.01" }, "Xyz": { "type": "string", "pattern": "^[XYZ]$", "description": "XYZ schema-family tag (Section 3.6): X Resource, Y Process, Z Timeline.", "example": "X" }, "ExternalRoleType": { "type": "string", "enum": [ "Client", "Vendor", "Contractor", "Crew", "Staff", "Artist", "Artist Representative", "Sponsor" ], "description": "External role type (Section 4.4.2).", "example": "Crew" }, "TeamId": { "type": "string", "pattern": "^[0-9]000-T[0-9]{2}$", "description": "Canon team identifier from `xpms.dim_team`.", "example": "4000-T01" }, "RecordCreate": { "type": "object", "properties": { "record_kind": { "$ref": "#/components/schemas/RecordKind" }, "record_subtype": { "$ref": "#/components/schemas/RecordSubtype" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Title, validated against the kind's title grammar on write.", "example": "Install Main Stage Truss" }, "scope_node_id": { "type": "string", "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "xyz": { "$ref": "#/components/schemas/Xyz" }, "owner_party_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the owning person or organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "accountable_party_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the accountable person or organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Start of the record window.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "End of the record window.", "example": "2026-10-08T14:30:00Z" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "Due instant.", "example": "2026-10-08T14:30:00Z" }, "blocker_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "The named blocker; required when Blocked.", "example": "Waiting on the rigging plot." }, "replan_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Replan reason; required when Deferred.", "example": "Moved to the second weekend." }, "external_visibility": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRoleType" }, "description": "External role types that may see the record; empty means internal only. Stored as junction rows, presented as a set.", "example": ["Vendor"] } }, "required": [ "record_kind", "title", "scope_node_id", "phase_code", "xyz", "external_visibility" ], "description": "Fields accepted when creating a Record." }, "RecordUpdate": { "type": "object", "properties": { "record_subtype": { "$ref": "#/components/schemas/RecordSubtype" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Title, validated against the kind's title grammar on write.", "example": "Install Main Stage Truss" }, "scope_node_id": { "type": "string", "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "xyz": { "$ref": "#/components/schemas/Xyz" }, "owner_party_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the owning person or organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "accountable_party_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the accountable person or organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Start of the record window.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "End of the record window.", "example": "2026-10-08T14:30:00Z" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "Due instant.", "example": "2026-10-08T14:30:00Z" }, "blocker_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "The named blocker; required when Blocked.", "example": "Waiting on the rigging plot." }, "replan_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Replan reason; required when Deferred.", "example": "Moved to the second weekend." }, "external_visibility": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRoleType" }, "description": "External role types that may see the record; empty means internal only. Stored as junction rows, presented as a set.", "example": ["Vendor"] }, "parent_record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the summary record this record rolls up to, in the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "wbs_code": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "pattern": "^[0-9]+(\\.[0-9]+)*$", "description": "Work breakdown structure code, dot separated.", "example": "1.2.1" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "What the record involves, in sentence case.", "example": "Rig the downstage truss." }, "sop_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the standard operating procedure that governs the work.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_code": { "anyOf": [{ "$ref": "#/components/schemas/TeamId" }, { "type": "null" }] } }, "description": "Fields accepted when updating a Record. Omitted fields are unchanged." }, "RecordTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": [ "Proposed", "Ready", "Scheduled", "Active", "Blocked", "In Review", "Complete", "Deferred", "Canceled" ], "description": "The state the caller believes the record is in (compare-and-set).", "example": "Scheduled" }, "to_state": { "$ref": "#/components/schemas/RecordState" }, "blocker_text": { "type": "string", "minLength": 1, "description": "Required when moving to Blocked.", "example": "Waiting on the rigging plot." }, "replan_reason": { "type": "string", "minLength": 1, "description": "Required when moving to Deferred.", "example": "Moved to the second weekend." } }, "required": ["expected_state", "to_state"], "description": "Request to move a record to another state." }, "RecordStateTransitionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordStateTransition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RecordStateTransition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record state transition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "from_state": { "$ref": "#/components/schemas/RecordState" }, "to_state": { "$ref": "#/components/schemas/RecordState" }, "transitioned_at": { "type": "string", "format": "date-time", "description": "When the state changed.", "example": "2026-10-08T14:30:00Z" }, "transitioned_by": { "type": "string", "format": "uuid", "description": "Identifier of the person who changed the state.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_id", "from_state", "to_state", "transitioned_at", "transitioned_by" ], "description": "An append-only record state transition." }, "RecordReplanPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordReplan" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RecordReplan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record replan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Replan reason.", "example": "Moved to the second weekend." }, "replanned_at": { "type": "string", "format": "date-time", "description": "When the replan was logged.", "example": "2026-10-08T14:30:00Z" }, "from_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Record state before the change. A Title Case value from the lifecycle's database enum.", "example": "Scheduled" }, "to_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Record state after the change. A Title Case value from the lifecycle's database enum.", "example": "Deferred" }, "old_starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Start before the change.", "example": "2026-10-08T14:30:00Z" }, "new_starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Start after the change.", "example": "2026-10-08T14:30:00Z" }, "old_ends_at": { "type": ["string", "null"], "format": "date-time", "description": "End before the change.", "example": "2026-10-08T14:30:00Z" }, "new_ends_at": { "type": ["string", "null"], "format": "date-time", "description": "End after the change.", "example": "2026-10-08T14:30:00Z" }, "old_due_at": { "type": ["string", "null"], "format": "date-time", "description": "Due time before the change.", "example": "2026-10-08T14:30:00Z" }, "new_due_at": { "type": ["string", "null"], "format": "date-time", "description": "Due time after the change.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_id", "reason", "replanned_at", "from_state", "to_state", "old_starts_at", "new_starts_at", "old_ends_at", "new_ends_at", "old_due_at", "new_due_at" ], "description": "An append-only replan entry, logged from Scheduled onward for every date or state change." }, "RecordChecklistItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordChecklistItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RecordChecklistItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record checklist item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Display position.", "example": 1 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Item label.", "example": "Check the safety cables" }, "done": { "type": "boolean", "description": "Whether the item is done.", "example": false }, "done_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who ticked the item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "done_at": { "type": ["string", "null"], "format": "date-time", "description": "When the item was ticked.", "example": "2026-10-08T14:30:00Z" }, "evidence_document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the photo or document evidence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_id", "position", "label", "done", "done_by", "done_at", "evidence_document_id" ], "description": "One checklist item of a record. Items are rows, never array positions." }, "RecordChecklistItemCreate": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Display position.", "example": 1 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Item label.", "example": "Check the safety cables" }, "done": { "type": "boolean", "description": "Whether the item is done.", "example": false }, "evidence_document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the photo or document evidence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["record_id", "position", "label", "done"], "description": "Fields accepted when creating a RecordChecklistItem." }, "RecordChecklistItemUpdate": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "description": "Display position.", "example": 1 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Item label.", "example": "Check the safety cables" }, "done": { "type": "boolean", "description": "Whether the item is done.", "example": false }, "evidence_document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the photo or document evidence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a RecordChecklistItem. Omitted fields are unchanged." }, "RecordWatcherPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordWatcher" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RecordWatcher": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record watcher.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the watching person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_id", "person_id" ], "description": "A person watching a record for notifications." }, "RecordWatcherCreate": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the watching person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["record_id", "person_id"], "description": "Fields accepted when creating a RecordWatcher." }, "WorkOrderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkOrder" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the work order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the work order fulfills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Work order title.", "example": "Fabricate Bar Fascia" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "work_order_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Work order state. A Title Case value from the lifecycle's database enum.", "example": "Proposed" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "When the work is due.", "example": "2026-10-08T14:30:00Z" }, "budget_minor": { "type": ["integer", "null"], "description": "Budget for the work. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 850000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "work_order_number": { "type": "integer", "minimum": 1, "description": "Sequence number within the project; the display key is {project_key}-WO-{number}.", "example": 12 }, "location_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Where the work happens, in words, when no zone says it.", "example": "Main stage, stage left wing." }, "scope_of_work": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "The scope bidders price, in sentence case.", "example": "Supply and hang 24 moving lights." }, "scheduled_starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Planned start.", "example": "2026-10-08T14:30:00Z" }, "estimated_hours": { "type": ["number", "null"], "description": "Estimated labor hours; null when unestimated.", "example": 16 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "record_id", "title", "urid", "work_order_state", "due_at", "budget_minor", "currency", "work_order_number", "location_text", "scope_of_work", "scheduled_starts_at", "estimated_hours" ], "description": "A work order issued against a record, open to bids." }, "WorkOrderCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the work order fulfills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Work order title.", "example": "Fabricate Bar Fascia" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "When the work is due.", "example": "2026-10-08T14:30:00Z" }, "budget_minor": { "type": ["integer", "null"], "description": "Budget for the work. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 850000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": ["project_id", "title", "currency"], "description": "Fields accepted when creating a WorkOrder." }, "WorkOrderUpdate": { "type": "object", "properties": { "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the work order fulfills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Work order title.", "example": "Fabricate Bar Fascia" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "When the work is due.", "example": "2026-10-08T14:30:00Z" }, "budget_minor": { "type": ["integer", "null"], "description": "Budget for the work. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 850000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "location_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Where the work happens, in words, when no zone says it.", "example": "Main stage, stage left wing." }, "scope_of_work": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "The scope bidders price, in sentence case.", "example": "Supply and hang 24 moving lights." }, "scheduled_starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Planned start.", "example": "2026-10-08T14:30:00Z" }, "estimated_hours": { "type": ["number", "null"], "description": "Estimated labor hours; null when unestimated.", "example": 16 } }, "description": "Fields accepted when updating a WorkOrder. Omitted fields are unchanged." }, "WorkOrderTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Proposed" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Active" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "WorkOrderBidPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkOrderBid" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkOrderBid": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the work order bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "work_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the work order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "bidder_organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the bidding organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "amount_minor": { "type": ["integer", "null"], "description": "Bid amount. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 790000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "bid_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Bid state. A Title Case value from the lifecycle's database enum.", "example": "Quoted" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Bid notes.", "example": "Includes delivery and install." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "work_order_id", "bidder_organization_id", "amount_minor", "currency", "bid_state", "notes" ], "description": "A bid on a work order." }, "WorkOrderBidCreate": { "type": "object", "properties": { "work_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the work order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "bidder_organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the bidding organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "amount_minor": { "type": ["integer", "null"], "description": "Bid amount. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 790000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Bid notes.", "example": "Includes delivery and install." } }, "required": ["work_order_id", "bidder_organization_id", "currency"], "description": "Fields accepted when creating a WorkOrderBid." }, "WorkOrderBidUpdate": { "type": "object", "properties": { "amount_minor": { "type": ["integer", "null"], "description": "Bid amount. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 790000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Bid notes.", "example": "Includes delivery and install." } }, "description": "Fields accepted when updating a WorkOrderBid. Omitted fields are unchanged." }, "RunOfShowPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RunOfShow" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RunOfShow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the run of show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the show scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Run of show title.", "example": "Saturday Main Stage" }, "show_date": { "type": "string", "format": "date", "description": "Show date.", "example": "2026-10-08" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the running order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the schedule record the running order belongs to, in the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "scope_node_id", "name", "show_date", "project_id", "record_id" ], "description": "A run of show for one show scope node." }, "RunOfShowCreate": { "type": "object", "properties": { "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the show scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Run of show title.", "example": "Saturday Main Stage" }, "show_date": { "type": "string", "format": "date", "description": "Show date.", "example": "2026-10-08" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the running order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the schedule record the running order belongs to, in the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name", "show_date", "project_id"], "description": "Fields accepted when creating a RunOfShow." }, "RunOfShowUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Run of show title.", "example": "Saturday Main Stage" }, "show_date": { "type": "string", "format": "date", "description": "Show date.", "example": "2026-10-08" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the schedule record the running order belongs to, in the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a RunOfShow. Omitted fields are unchanged." }, "CuePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cue" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Cue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the cue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "run_of_show_id": { "type": "string", "format": "uuid", "description": "Identifier of the run of show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Cue order.", "example": 10 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Cue title.", "example": "Headliner Walk-On" }, "planned_at": { "type": ["string", "null"], "format": "date-time", "description": "Planned cue time.", "example": "2026-10-08T14:30:00Z" }, "called_at": { "type": ["string", "null"], "format": "date-time", "description": "When the cue was called.", "example": "2026-10-08T14:30:00Z" }, "duration": { "type": ["string", "null"], "pattern": "^\\d{2,}:\\d{2}:\\d{2}(\\.\\d+)?$", "description": "Planned length as hours:minutes:seconds.", "example": "00:05:00" }, "called_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who called the cue, set by app.call_cue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the running order, stamped by the database.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "segment": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Show segment the cue belongs to.", "example": "Act II, Official Opening and Remarks" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What happens on the cue.", "example": "House lights to half; walk-in music fades." }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space the cue happens in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "run_of_show_id", "position", "label", "planned_at", "called_at", "duration", "called_by", "project_id", "segment", "description", "space_id" ], "description": "A cue in a run of show." }, "CueCreate": { "type": "object", "properties": { "run_of_show_id": { "type": "string", "format": "uuid", "description": "Identifier of the run of show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Cue order.", "example": 10 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Cue title.", "example": "Headliner Walk-On" }, "planned_at": { "type": ["string", "null"], "format": "date-time", "description": "Planned cue time.", "example": "2026-10-08T14:30:00Z" }, "duration": { "type": ["string", "null"], "pattern": "^\\d{2,}:\\d{2}:\\d{2}(\\.\\d+)?$", "description": "Planned length as hours:minutes:seconds.", "example": "00:05:00" }, "segment": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Show segment the cue belongs to.", "example": "Act II, Official Opening and Remarks" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What happens on the cue.", "example": "House lights to half; walk-in music fades." }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space the cue happens in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["run_of_show_id", "position", "label"], "description": "Fields accepted when creating a Cue." }, "CueUpdate": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "description": "Cue order.", "example": 10 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Cue title.", "example": "Headliner Walk-On" }, "planned_at": { "type": ["string", "null"], "format": "date-time", "description": "Planned cue time.", "example": "2026-10-08T14:30:00Z" }, "duration": { "type": ["string", "null"], "pattern": "^\\d{2,}:\\d{2}:\\d{2}(\\.\\d+)?$", "description": "Planned length as hours:minutes:seconds.", "example": "00:05:00" }, "segment": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Show segment the cue belongs to.", "example": "Act II, Official Opening and Remarks" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What happens on the cue.", "example": "House lights to half; walk-in music fades." }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space the cue happens in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Cue. Omitted fields are unchanged." }, "DaySheetPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DaySheet" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DaySheet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the day sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "day": { "type": "string", "format": "date", "description": "Day the sheet covers; one sheet per project and day.", "example": "2026-10-08" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Day sheet content as rich text.", "example": "Doors at 18:00. Load-out after the encore." }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the day sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "published_at": { "type": ["string", "null"], "format": "date-time", "description": "When the day sheet was published, stamped by the database; set once by the publish action.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "day", "body", "project_id", "published_at" ], "description": "A day sheet for one scope node and date." }, "DaySheetCreate": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "description": "Day the sheet covers; one sheet per project and day.", "example": "2026-10-08" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Day sheet content as rich text.", "example": "Doors at 18:00. Load-out after the encore." }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the day sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["day", "body", "project_id"], "description": "Fields accepted when creating a DaySheet." }, "DaySheetUpdate": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "description": "Day the sheet covers; one sheet per project and day.", "example": "2026-10-08" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Day sheet content as rich text.", "example": "Doors at 18:00. Load-out after the encore." } }, "description": "Fields accepted when updating a DaySheet. Omitted fields are unchanged." }, "CallSheetPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CallSheet" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CallSheet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the call sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "day": { "type": "string", "format": "date", "description": "Day the sheet covers; one sheet per project and day.", "example": "2026-10-08" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the call sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "published_at": { "type": ["string", "null"], "format": "date-time", "description": "When the call sheet was published, stamped by the database; set once by the publish action.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "day", "project_id", "published_at" ], "description": "A call sheet listing call times for one scope node and date." }, "CallSheetCreate": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "description": "Day the sheet covers; one sheet per project and day.", "example": "2026-10-08" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the call sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["day", "project_id"], "description": "Fields accepted when creating a CallSheet." }, "CallSheetUpdate": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "description": "Day the sheet covers; one sheet per project and day.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a CallSheet. Omitted fields are unchanged." }, "SopPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sop" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Sop": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the sop.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "SOP title.", "example": "Working at Height" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Procedure text.", "example": "Confirm the dock slot, then stage by department." }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "SOP code, SOP- and three to five digits.", "example": "SOP-001" }, "version": { "type": "integer", "minimum": 1, "description": "Version number, raised on each publish.", "example": 1 }, "published_at": { "type": ["string", "null"], "format": "date-time", "description": "When the current version was published; null while draft.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "title", "body", "code", "version", "published_at" ], "description": "A standard operating procedure that members acknowledge." }, "SopCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "SOP title.", "example": "Working at Height" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Procedure text.", "example": "Confirm the dock slot, then stage by department." }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "SOP code, SOP- and three to five digits.", "example": "SOP-001" } }, "required": ["title", "body", "code"], "description": "Fields accepted when creating a Sop." }, "SopUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "SOP title.", "example": "Working at Height" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Procedure text.", "example": "Confirm the dock slot, then stage by department." } }, "description": "Fields accepted when updating a Sop. Omitted fields are unchanged." }, "SopAcknowledgmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SopAcknowledgment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SopAcknowledgment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the sop acknowledgment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "sop_id": { "type": "string", "format": "uuid", "description": "Identifier of the SOP.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the acknowledging person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "acknowledged_at": { "type": "string", "format": "date-time", "description": "When it was acknowledged.", "example": "2026-10-08T14:30:00Z" }, "sop_version": { "type": "integer", "minimum": 1, "description": "Version acknowledged.", "example": 2 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "sop_id", "person_id", "acknowledged_at", "sop_version" ], "description": "A person's acknowledgment of an SOP version." }, "SopAcknowledgmentCreate": { "type": "object", "properties": { "sop_id": { "type": "string", "format": "uuid", "description": "Identifier of the SOP.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["sop_id"], "description": "Fields accepted when creating a SopAcknowledgment." }, "DocumentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Venue Site Plan" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "title", "project_id" ], "description": "A document with versions. Files are stored in tenant-scoped storage." }, "DocumentCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Venue Site Plan" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["title"], "description": "Fields accepted when creating a Document." }, "DocumentUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Venue Site Plan" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Document. Omitted fields are unchanged." }, "DocumentVersionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentVersion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DocumentVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the document version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "document_id": { "type": "string", "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "version_number": { "type": "integer", "minimum": 1, "description": "Version number.", "example": 3 }, "storage_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the file is stored.", "example": "https://files.example.com/site-plan-v3.pdf" }, "checksum_sha256": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "SHA-256 of the file, lowercase hex.", "example": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "document_id", "version_number", "storage_uri", "checksum_sha256" ], "description": "An immutable version of a document." }, "DocumentVersionCreate": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "storage_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the file is stored.", "example": "https://files.example.com/site-plan-v3.pdf" }, "checksum_sha256": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "SHA-256 of the file, lowercase hex.", "example": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } }, "required": ["document_id", "storage_uri", "checksum_sha256"], "description": "Fields accepted when creating a DocumentVersion." }, "VerbiageTermPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VerbiageTerm" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "VerbiageTerm": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the verbiage term.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "term": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Term.", "example": "Load-In" }, "casing_rule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Casing rule.", "example": "Title Case as a noun" }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, a sentence ending in a period.", "example": "The arrival of equipment before a show." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "term", "casing_rule", "definition" ], "description": "A controlled vocabulary term with casing rules. Em dashes are refused." }, "VerbiageTermCreate": { "type": "object", "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Term.", "example": "Load-In" }, "casing_rule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Casing rule.", "example": "Title Case as a noun" }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, a sentence ending in a period.", "example": "The arrival of equipment before a show." } }, "required": ["term", "casing_rule", "definition"], "description": "Fields accepted when creating a VerbiageTerm." }, "VerbiageTermUpdate": { "type": "object", "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Term.", "example": "Load-In" }, "casing_rule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Casing rule.", "example": "Title Case as a noun" }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, a sentence ending in a period.", "example": "The arrival of equipment before a show." } }, "description": "Fields accepted when updating a VerbiageTerm. Omitted fields are unchanged." }, "VenuePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Venue" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Venue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Venue name.", "example": "Harborfront Lawn" }, "street_address": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Street address.", "example": "100 Harbor Way" }, "locality": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "City.", "example": "Miami" }, "postal_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Postal code.", "example": "33132" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "street_address", "locality", "postal_code", "jurisdiction_id", "time_zone", "latitude", "longitude" ], "description": "A venue." }, "VenueCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Venue name.", "example": "Harborfront Lawn" }, "street_address": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Street address.", "example": "100 Harbor Way" }, "locality": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "City.", "example": "Miami" }, "postal_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Postal code.", "example": "33132" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 } }, "required": ["name", "jurisdiction_id", "time_zone"], "description": "Fields accepted when creating a Venue." }, "VenueUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Venue name.", "example": "Harborfront Lawn" }, "street_address": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Street address.", "example": "100 Harbor Way" }, "locality": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "City.", "example": "Miami" }, "postal_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Postal code.", "example": "33132" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 } }, "description": "Fields accepted when updating a Venue. Omitted fields are unchanged." }, "SpacePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Space" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Space": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the space.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Space name.", "example": "North Lawn" }, "capacity": { "type": ["integer", "null"], "minimum": 0, "description": "Rated occupant capacity.", "example": 2500 }, "area_sq_ft": { "type": ["number", "null"], "description": "Floor area in square feet.", "example": 18000 }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the space is used for.", "example": "Backstage green room for talent." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "venue_id", "name", "capacity", "area_sq_ft", "urid", "description" ], "description": "A space within a venue." }, "Urid": { "type": "string", "pattern": "^[0-9]000\\.[0-9]{2}\\.[0-9]{2}$", "description": "Category URID `DDDD.DD.DD` from `xpms.dim_category` (Section 3.3). There is no fourth segment.", "example": "4000.01.01" }, "SpaceCreate": { "type": "object", "properties": { "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Space name.", "example": "North Lawn" }, "capacity": { "type": ["integer", "null"], "minimum": 0, "description": "Rated occupant capacity.", "example": 2500 }, "area_sq_ft": { "type": ["number", "null"], "description": "Floor area in square feet.", "example": 18000 }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the space is used for.", "example": "Backstage green room for talent." } }, "required": ["venue_id", "name"], "description": "Fields accepted when creating a Space." }, "SpaceUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Space name.", "example": "North Lawn" }, "capacity": { "type": ["integer", "null"], "minimum": 0, "description": "Rated occupant capacity.", "example": 2500 }, "area_sq_ft": { "type": ["number", "null"], "description": "Floor area in square feet.", "example": 18000 }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the space is used for.", "example": "Backstage green room for talent." } }, "description": "Fields accepted when updating a Space. Omitted fields are unchanged." }, "ZonePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Zone" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Zone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space the zone sits in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Zone name.", "example": "Backstage" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Zone code used on credentials.", "example": "BS" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "space_id", "name", "code", "venue_id" ], "description": "An access or operations zone within a space." }, "ZoneCreate": { "type": "object", "properties": { "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space the zone sits in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Zone name.", "example": "Backstage" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Zone code used on credentials.", "example": "BS" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name", "code", "venue_id"], "description": "Fields accepted when creating a Zone." }, "ZoneUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Zone name.", "example": "Backstage" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Zone code used on credentials.", "example": "BS" }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space the zone sits in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Zone. Omitted fields are unchanged." }, "CapabilityDocumentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityDocument" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CapabilityDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the capability document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date", "description": "First day the document is valid.", "example": "2026-10-08" }, "valid_to": { "type": ["string", "null"], "format": "date", "description": "Last day the document is valid.", "example": "2026-10-08" }, "frozen": { "type": "boolean", "description": "Whether the document is frozen.", "example": false }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Tech Pack 2027" }, "document_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the document is stored.", "example": "https://docs.example.com/tech-pack.pdf" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "venue_id", "valid_from", "valid_to", "frozen", "title", "document_uri" ], "description": "A venue capability document with a validity window. A frozen document cannot change." }, "CapabilityDocumentCreate": { "type": "object", "properties": { "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date", "description": "First day the document is valid.", "example": "2026-10-08" }, "valid_to": { "type": ["string", "null"], "format": "date", "description": "Last day the document is valid.", "example": "2026-10-08" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Tech Pack 2027" }, "document_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the document is stored.", "example": "https://docs.example.com/tech-pack.pdf" } }, "required": ["venue_id", "valid_from", "title", "document_uri"], "description": "Fields accepted when creating a CapabilityDocument." }, "CapabilityDocumentUpdate": { "type": "object", "properties": { "valid_from": { "type": "string", "format": "date", "description": "First day the document is valid.", "example": "2026-10-08" }, "valid_to": { "type": ["string", "null"], "format": "date", "description": "Last day the document is valid.", "example": "2026-10-08" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Tech Pack 2027" }, "document_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the document is stored.", "example": "https://docs.example.com/tech-pack.pdf" } }, "description": "Fields accepted when updating a CapabilityDocument. Omitted fields are unchanged." }, "SitePlanPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SitePlan" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SitePlan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the site plan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue drawn.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Site plan title.", "example": "Festival Layout" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "image_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the drawing is stored.", "example": "plans/ground.png" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "venue_id", "title", "project_id", "image_uri" ], "description": "A site plan drawing for a venue." }, "SitePlanCreate": { "type": "object", "properties": { "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue drawn.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Site plan title.", "example": "Festival Layout" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "image_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the drawing is stored.", "example": "plans/ground.png" } }, "required": ["title", "project_id", "image_uri"], "description": "Fields accepted when creating a SitePlan." }, "SitePlanUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Site plan title.", "example": "Festival Layout" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue drawn.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "image_uri": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Where the drawing is stored.", "example": "plans/ground.png" } }, "description": "Fields accepted when updating a SitePlan. Omitted fields are unchanged." }, "SitePlanPinPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SitePlanPin" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SitePlanPin": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the site plan pin.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "site_plan_id": { "type": "string", "format": "uuid", "description": "Identifier of the site plan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pin label.", "example": "First Aid" }, "x": { "type": "number", "description": "Horizontal position, 0 to 1.", "example": 0.42 }, "y": { "type": "number", "description": "Vertical position, 0 to 1.", "example": 0.71 }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the pin marks.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the pin marks.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "site_plan_id", "label", "x", "y", "zone_id", "record_id" ], "description": "A pin on a site plan." }, "SitePlanPinCreate": { "type": "object", "properties": { "site_plan_id": { "type": "string", "format": "uuid", "description": "Identifier of the site plan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pin label.", "example": "First Aid" }, "x": { "type": "number", "description": "Horizontal position, 0 to 1.", "example": 0.42 }, "y": { "type": "number", "description": "Vertical position, 0 to 1.", "example": 0.71 }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the pin marks.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the pin marks.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["site_plan_id", "label", "x", "y"], "description": "Fields accepted when creating a SitePlanPin." }, "SitePlanPinUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pin label.", "example": "First Aid" }, "x": { "type": "number", "description": "Horizontal position, 0 to 1.", "example": 0.42 }, "y": { "type": "number", "description": "Vertical position, 0 to 1.", "example": 0.71 }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the pin marks.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the pin marks.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a SitePlanPin. Omitted fields are unchanged." }, "GeofencePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Geofence" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Geofence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the geofence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Geofence name.", "example": "Harborfront Site" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the geofence outlines.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "boundary": { "$ref": "#/components/schemas/GeoJsonPolygon" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "venue_id", "zone_id", "boundary" ], "description": "A geofence used for Compass clock in." }, "GeoJsonPolygon": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [{ "type": "number" }, { "type": "number" }] }, "minItems": 1 }, "minItems": 1 } }, "required": ["type", "coordinates"], "description": "A GeoJSON Polygon in WGS 84 (RFC 7946): rings of [longitude, latitude] positions.", "example": { "type": "Polygon", "coordinates": [ [ [-80.19, 25.77], [-80.18, 25.77], [-80.18, 25.78], [-80.19, 25.77] ] ] } }, "GeofenceCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Geofence name.", "example": "Harborfront Site" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the geofence outlines.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "boundary": { "$ref": "#/components/schemas/GeoJsonPolygon" } }, "required": ["name", "venue_id", "boundary"], "description": "Fields accepted when creating a Geofence." }, "GeofenceUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Geofence name.", "example": "Harborfront Site" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the geofence outlines.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "boundary": { "$ref": "#/components/schemas/GeoJsonPolygon" } }, "description": "Fields accepted when updating a Geofence. Omitted fields are unchanged." }, "RequirementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Requirement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Requirement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "direction": { "type": "string", "enum": ["Require", "Provide"], "description": "Require for a requirement of the project, Provide for a capability a venue or counterparty offers.", "example": "Require" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is required or provided.", "example": "Three-phase 400 A power at stage left." }, "quantity": { "type": ["number", "null"], "description": "Quantity required or provided.", "example": 1 }, "unit_basis": { "$ref": "#/components/schemas/UnitCode" }, "is_critical": { "type": "boolean", "description": "Whether the requirement is critical.", "example": true }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty that provides a capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "assertion_word": { "type": "string", "enum": ["CERTIFIED", "DOCUMENTED", "CLAIMED", "INFERRED", "UNKNOWN"], "description": "Canon capability assertion word (Bible tab 22); silence is UNKNOWN, which reconciles as Unknown.", "example": "DOCUMENTED" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "direction", "project_id", "venue_id", "urid", "description", "quantity", "unit_basis", "is_critical", "counterparty_id", "assertion_word" ], "description": "A requirement or a capability: one shape with a direction facet, so reconciliation is a join." }, "UnitCode": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_-]*$", "description": "Unit basis from the controlled unit list in `xpms.dim_unit_alias`.", "example": "each" }, "RequirementCreate": { "type": "object", "properties": { "direction": { "type": "string", "enum": ["Require", "Provide"], "description": "Require for a requirement of the project, Provide for a capability a venue or counterparty offers.", "example": "Require" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is required or provided.", "example": "Three-phase 400 A power at stage left." }, "quantity": { "type": ["number", "null"], "description": "Quantity required or provided.", "example": 1 }, "unit_basis": { "$ref": "#/components/schemas/UnitCode" }, "is_critical": { "type": "boolean", "description": "Whether the requirement is critical.", "example": true }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty that provides a capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "assertion_word": { "type": "string", "enum": ["CERTIFIED", "DOCUMENTED", "CLAIMED", "INFERRED", "UNKNOWN"], "description": "Canon capability assertion word (Bible tab 22); silence is UNKNOWN, which reconciles as Unknown.", "example": "DOCUMENTED" } }, "required": ["direction", "project_id", "urid", "description"], "description": "Fields accepted when creating a Requirement." }, "RequirementUpdate": { "type": "object", "properties": { "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is required or provided.", "example": "Three-phase 400 A power at stage left." }, "quantity": { "type": ["number", "null"], "description": "Quantity required or provided.", "example": 1 }, "unit_basis": { "$ref": "#/components/schemas/UnitCode" }, "is_critical": { "type": "boolean", "description": "Whether the requirement is critical.", "example": true }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty that provides a capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "assertion_word": { "type": "string", "enum": ["CERTIFIED", "DOCUMENTED", "CLAIMED", "INFERRED", "UNKNOWN"], "description": "Canon capability assertion word (Bible tab 22); silence is UNKNOWN, which reconciles as Unknown.", "example": "DOCUMENTED" } }, "description": "Fields accepted when updating a Requirement. Omitted fields are unchanged." }, "ReconciliationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reconciliation" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Reconciliation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the reconciliation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "run_at": { "type": "string", "format": "date-time", "description": "When the reconciliation ran.", "example": "2026-10-08T14:30:00Z" }, "met_count": { "type": "integer", "minimum": 0, "description": "Requirements met.", "example": 18 }, "gap_count": { "type": "integer", "minimum": 0, "description": "Requirements with a gap.", "example": 2 }, "unknown_count": { "type": "integer", "minimum": 0, "description": "Requirements with an unknown result.", "example": 1 }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes on the run.", "example": "Venue walk." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "run_at", "met_count", "gap_count", "unknown_count", "note" ], "description": "A reconciliation run of requirements against capabilities." }, "ReconciliationCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes on the run.", "example": "Venue walk." } }, "required": ["project_id"], "description": "Fields accepted when creating a Reconciliation." }, "ReconciliationLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReconciliationLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the reconciliation line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reconciliation_id": { "type": "string", "format": "uuid", "description": "Identifier of the reconciliation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "requirement_id": { "type": "string", "format": "uuid", "description": "Identifier of the requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the matching capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "result": { "$ref": "#/components/schemas/ReconciliationResult" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "reconciliation_id", "requirement_id", "capability_id", "result" ], "description": "One requirement's reconciliation result." }, "ReconciliationResult": { "type": "string", "enum": ["Met", "Gap", "Unknown"], "description": "Requirement against capability result. Unknown against a critical requirement is a gap at gate 3.", "example": "Met" }, "ShipmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Shipment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tracking_identifier": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Carrier tracking identifier.", "example": "CF123456789" }, "direction": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Inbound or outbound.", "example": "inbound" }, "ships_at": { "type": ["string", "null"], "format": "date-time", "description": "Expected arrival or departure.", "example": "2026-10-08T14:30:00Z" }, "carrier_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the carrier, as a counterparty of the org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "freight_type_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon freight type, from xpms.std_enumeration.", "example": "ENM-041" }, "arrives_at": { "type": ["string", "null"], "format": "date-time", "description": "When the shipment is due to arrive.", "example": "2026-10-08T14:30:00Z" }, "shipment_number": { "type": "integer", "minimum": 1, "description": "Number within the project; the display key is {project_key}-{shipment_number}.", "example": 7 }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the shipment carries, in a sentence.", "example": "Two pallets of truss and motors." }, "origin": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Where the freight ships from, as a locality.", "example": "Orlando, FL" }, "sender_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the vendor sending the freight; the carrier is carrier_counterparty_id.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "pallet_count": { "type": ["integer", "null"], "minimum": 0, "description": "Number of pallets.", "example": 2 }, "piece_count": { "type": ["integer", "null"], "minimum": 0, "description": "Number of pieces.", "example": 14 }, "length_ft": { "type": ["number", "null"], "description": "Length of the load in feet.", "example": 48 }, "width_ft": { "type": ["number", "null"], "description": "Width of the load in feet.", "example": 8.5 }, "height_ft": { "type": ["number", "null"], "description": "Height of the load in feet.", "example": 9 }, "weight_lb": { "type": ["number", "null"], "description": "Weight of the load in pounds.", "example": 12000 }, "trailer_license": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "License plate of the trailer.", "example": "FL TRL-4410" }, "seal_identifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Number of the seal applied to the trailer.", "example": "SL-778120" }, "bill_of_lading_identifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Bill of lading number issued by the carrier.", "example": "BOL-2027-0611" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "tracking_identifier", "direction", "ships_at", "carrier_counterparty_id", "freight_type_enum_id", "arrives_at", "shipment_number", "urid", "description", "origin", "sender_counterparty_id", "pallet_count", "piece_count", "length_ft", "width_ft", "height_ft", "weight_lb", "trailer_license", "seal_identifier", "bill_of_lading_identifier" ], "description": "A shipment into or out of a venue." }, "ShipmentCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tracking_identifier": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Carrier tracking identifier.", "example": "CF123456789" }, "direction": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Inbound or outbound.", "example": "inbound" }, "ships_at": { "type": ["string", "null"], "format": "date-time", "description": "Expected arrival or departure.", "example": "2026-10-08T14:30:00Z" }, "carrier_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the carrier, as a counterparty of the org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "freight_type_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon freight type, from xpms.std_enumeration.", "example": "ENM-041" }, "arrives_at": { "type": ["string", "null"], "format": "date-time", "description": "When the shipment is due to arrive.", "example": "2026-10-08T14:30:00Z" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the shipment carries, in a sentence.", "example": "Two pallets of truss and motors." }, "origin": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Where the freight ships from, as a locality.", "example": "Orlando, FL" }, "sender_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the vendor sending the freight; the carrier is carrier_counterparty_id.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "pallet_count": { "type": ["integer", "null"], "minimum": 0, "description": "Number of pallets.", "example": 2 }, "piece_count": { "type": ["integer", "null"], "minimum": 0, "description": "Number of pieces.", "example": 14 }, "length_ft": { "type": ["number", "null"], "description": "Length of the load in feet.", "example": 48 }, "width_ft": { "type": ["number", "null"], "description": "Width of the load in feet.", "example": 8.5 }, "height_ft": { "type": ["number", "null"], "description": "Height of the load in feet.", "example": 9 }, "weight_lb": { "type": ["number", "null"], "description": "Weight of the load in pounds.", "example": 12000 }, "trailer_license": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "License plate of the trailer.", "example": "FL TRL-4410" }, "seal_identifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Number of the seal applied to the trailer.", "example": "SL-778120" }, "bill_of_lading_identifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Bill of lading number issued by the carrier.", "example": "BOL-2027-0611" } }, "required": ["project_id", "direction"], "description": "Fields accepted when creating a Shipment." }, "ShipmentUpdate": { "type": "object", "properties": { "tracking_identifier": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Carrier tracking identifier.", "example": "CF123456789" }, "direction": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Inbound or outbound.", "example": "inbound" }, "ships_at": { "type": ["string", "null"], "format": "date-time", "description": "Expected arrival or departure.", "example": "2026-10-08T14:30:00Z" }, "carrier_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the carrier, as a counterparty of the org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "freight_type_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon freight type, from xpms.std_enumeration.", "example": "ENM-041" }, "arrives_at": { "type": ["string", "null"], "format": "date-time", "description": "When the shipment is due to arrive.", "example": "2026-10-08T14:30:00Z" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the shipment carries, in a sentence.", "example": "Two pallets of truss and motors." }, "origin": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Where the freight ships from, as a locality.", "example": "Orlando, FL" }, "sender_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the vendor sending the freight; the carrier is carrier_counterparty_id.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "pallet_count": { "type": ["integer", "null"], "minimum": 0, "description": "Number of pallets.", "example": 2 }, "piece_count": { "type": ["integer", "null"], "minimum": 0, "description": "Number of pieces.", "example": 14 }, "length_ft": { "type": ["number", "null"], "description": "Length of the load in feet.", "example": 48 }, "width_ft": { "type": ["number", "null"], "description": "Width of the load in feet.", "example": 8.5 }, "height_ft": { "type": ["number", "null"], "description": "Height of the load in feet.", "example": 9 }, "weight_lb": { "type": ["number", "null"], "description": "Weight of the load in pounds.", "example": 12000 }, "trailer_license": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "License plate of the trailer.", "example": "FL TRL-4410" }, "seal_identifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Number of the seal applied to the trailer.", "example": "SL-778120" }, "bill_of_lading_identifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Bill of lading number issued by the carrier.", "example": "BOL-2027-0611" } }, "description": "Fields accepted when updating a Shipment. Omitted fields are unchanged." }, "ShipmentLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ShipmentLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the shipment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shipment_id": { "type": "string", "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Truss sections, 10 ft" }, "quantity": { "type": "number", "description": "Quantity.", "example": 24 }, "element_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon element carried.", "example": "4000.01.01-XPMS-001" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "shipment_id", "description", "quantity", "element_id" ], "description": "A line on a shipping manifest." }, "ShipmentLineCreate": { "type": "object", "properties": { "shipment_id": { "type": "string", "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Truss sections, 10 ft" }, "quantity": { "type": "number", "description": "Quantity.", "example": 24 }, "element_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon element carried.", "example": "4000.01.01-XPMS-001" } }, "required": ["shipment_id", "description"], "description": "Fields accepted when creating a ShipmentLine." }, "ShipmentLineUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Truss sections, 10 ft" }, "quantity": { "type": "number", "description": "Quantity.", "example": 24 }, "element_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon element carried.", "example": "4000.01.01-XPMS-001" } }, "description": "Fields accepted when updating a ShipmentLine. Omitted fields are unchanged." }, "DockSlotPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DockSlot" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DockSlot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the dock slot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Slot start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Slot end.", "example": "2026-10-08T14:30:00Z" }, "checked_in_at": { "type": ["string", "null"], "format": "date-time", "description": "When the vehicle checked in.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project whose site the dock is at.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": "string", "format": "uuid", "description": "Identifier of the loading dock zone of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "checked_in_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who checked the shipment in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "shipment_id", "starts_at", "ends_at", "checked_in_at", "project_id", "zone_id", "checked_in_by" ], "description": "A dock slot booking." }, "DockSlotCreate": { "type": "object", "properties": { "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Slot start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Slot end.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project whose site the dock is at.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": "string", "format": "uuid", "description": "Identifier of the loading dock zone of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["starts_at", "ends_at", "project_id", "zone_id"], "description": "Fields accepted when creating a DockSlot." }, "DockSlotUpdate": { "type": "object", "properties": { "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Slot start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Slot end.", "example": "2026-10-08T14:30:00Z" }, "zone_id": { "type": "string", "format": "uuid", "description": "Identifier of the loading dock zone of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a DockSlot. Omitted fields are unchanged." }, "GateQueueEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GateQueueEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "GateQueueEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the gate queue entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vehicle_identifier": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Plate or trailer number as written.", "example": "FL TRK-2231" }, "arrived_at": { "type": "string", "format": "date-time", "description": "When the vehicle arrived.", "example": "2026-10-08T14:30:00Z" }, "released_at": { "type": ["string", "null"], "format": "date-time", "description": "When the vehicle was released.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project whose site the gate is at.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment the vehicle carries.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "released_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who released the vehicle.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vehicle_type": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Kind of vehicle at the gate.", "example": "53ft Tractor-Trailer" }, "driver_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Driver of the vehicle, as given at check-in.", "example": "Luis Ortega" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "vehicle_identifier", "arrived_at", "released_at", "project_id", "shipment_id", "released_by", "vehicle_type", "driver_name" ], "description": "A vehicle waiting at the venue gate." }, "GateQueueEntryCreate": { "type": "object", "properties": { "vehicle_identifier": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Plate or trailer number as written.", "example": "FL TRK-2231" }, "arrived_at": { "type": "string", "format": "date-time", "description": "When the vehicle arrived.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project whose site the gate is at.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment the vehicle carries.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vehicle_type": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Kind of vehicle at the gate.", "example": "53ft Tractor-Trailer" }, "driver_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Driver of the vehicle, as given at check-in.", "example": "Luis Ortega" } }, "required": ["vehicle_identifier", "project_id"], "description": "Fields accepted when creating a GateQueueEntry." }, "GateQueueEntryUpdate": { "type": "object", "properties": { "vehicle_identifier": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Plate or trailer number as written.", "example": "FL TRK-2231" }, "arrived_at": { "type": "string", "format": "date-time", "description": "When the vehicle arrived.", "example": "2026-10-08T14:30:00Z" }, "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment the vehicle carries.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vehicle_type": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Kind of vehicle at the gate.", "example": "53ft Tractor-Trailer" }, "driver_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Driver of the vehicle, as given at check-in.", "example": "Luis Ortega" } }, "description": "Fields accepted when updating a GateQueueEntry. Omitted fields are unchanged." }, "MarshallingLogEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarshallingLogEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MarshallingLogEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the marshalling log entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "entry": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What happened in the yard.", "example": "Staged in lane 2." }, "logged_at": { "type": "string", "format": "date-time", "description": "When the event was logged.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project whose yard the entry records.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment concerned.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the yard zone concerned.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "entry", "logged_at", "project_id", "shipment_id", "zone_id", "urid" ], "description": "A marshalling yard log entry: staging and release." }, "MarshallingLogEntryCreate": { "type": "object", "properties": { "entry": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What happened in the yard.", "example": "Staged in lane 2." }, "logged_at": { "type": "string", "format": "date-time", "description": "When the event was logged.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project whose yard the entry records.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shipment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shipment concerned.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the yard zone concerned.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] } }, "required": ["entry", "project_id"], "description": "Fields accepted when creating a MarshallingLogEntry." }, "AdvancePacketPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdvancePacket" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AdvancePacket": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Packet title.", "example": "Headliner Advance" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "When submissions are due.", "example": "2026-10-08T14:30:00Z" }, "sent_at": { "type": ["string", "null"], "format": "date-time", "description": "When the packet was sent.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "title", "due_at", "sent_at" ], "description": "An advance packet sent to parties for one project." }, "AdvancePacketCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Packet title.", "example": "Headliner Advance" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "When submissions are due.", "example": "2026-10-08T14:30:00Z" } }, "required": ["project_id", "title"], "description": "Fields accepted when creating a AdvancePacket." }, "AdvancePacketUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Packet title.", "example": "Headliner Advance" }, "due_at": { "type": ["string", "null"], "format": "date-time", "description": "When submissions are due.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a AdvancePacket. Omitted fields are unchanged." }, "AdvanceSectionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdvanceSection" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AdvanceSection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the advance section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "advance_packet_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Section order.", "example": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Section title.", "example": "Hospitality" }, "prompt": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the recipient is asked.", "example": "When does the party arrive?" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "advance_packet_id", "position", "title", "prompt" ], "description": "A section of an advance packet." }, "AdvanceSectionCreate": { "type": "object", "properties": { "advance_packet_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Section order.", "example": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Section title.", "example": "Hospitality" }, "prompt": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the recipient is asked.", "example": "When does the party arrive?" } }, "required": ["advance_packet_id", "position", "title"], "description": "Fields accepted when creating a AdvanceSection." }, "AdvanceSectionUpdate": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "description": "Section order.", "example": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Section title.", "example": "Hospitality" }, "prompt": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the recipient is asked.", "example": "When does the party arrive?" } }, "description": "Fields accepted when updating a AdvanceSection. Omitted fields are unchanged." }, "AdvanceRecipientPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdvanceRecipient" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AdvanceRecipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the advance recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "advance_packet_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the recipient person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the recipient counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "advance_packet_id", "person_id", "counterparty_id" ], "description": "A party bound to an advance packet. Recipients without an account use a token and access code." }, "AdvanceRecipientCreate": { "type": "object", "properties": { "advance_packet_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the recipient person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the recipient counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["advance_packet_id"], "description": "Fields accepted when creating a AdvanceRecipient." }, "AdvanceSubmissionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdvanceSubmission" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AdvanceSubmission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the advance submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "advance_section_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "advance_recipient_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "submitted_at": { "type": "string", "format": "date-time", "description": "When it was submitted.", "example": "2026-10-08T14:30:00Z" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The answer as rich text.", "example": "Party of 8 lands at 14:20." }, "reviewed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the answer was reviewed.", "example": "2026-10-08T14:30:00Z" }, "reviewed_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who reviewed the answer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "review_outcome": { "type": ["string", "null"], "enum": ["Accepted", "Returned", null], "description": "Accepted or Returned.", "example": "Accepted" }, "return_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Why the answer was returned.", "example": "Please add the flight number." }, "via_link": { "type": "boolean", "description": "True when the recipient answered through a Gateway link.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "advance_section_id", "advance_recipient_id", "submitted_at", "body", "reviewed_at", "reviewed_by", "review_outcome", "return_reason", "via_link" ], "description": "A recipient's submission for one section." }, "AdvanceSubmissionCreate": { "type": "object", "properties": { "advance_section_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "advance_recipient_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "The answer as rich text.", "example": "Party of 8 lands at 14:20." } }, "required": ["advance_section_id", "advance_recipient_id", "body"], "description": "Fields accepted when creating a AdvanceSubmission." }, "AdvanceSubmissionReviewRequest": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["Accepted", "Returned"], "description": "Accepted, or Returned to the recipient to answer again.", "example": "Returned" }, "return_reason": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Why the answer is returned; required when Returned, shown to the recipient.", "example": "Please add the flight number." } }, "required": ["outcome"], "description": "Review of one advance answer." }, "AdvancePromotionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdvancePromotion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AdvancePromotion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the advance promotion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "advance_submission_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record created from the answer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "advance_submission_id", "record_id" ], "description": "A submission promoted into project records, such as a requirement or a fulfillment." }, "AdvancePromotionCreate": { "type": "object", "properties": { "advance_submission_id": { "type": "string", "format": "uuid", "description": "Identifier of the advance submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record created from the answer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["advance_submission_id", "record_id"], "description": "Fields accepted when creating a AdvancePromotion." }, "RiderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rider" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Rider": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Rider title.", "example": "Technical Rider 2026" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty whose rider it is.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "title", "project_id", "counterparty_id" ], "description": "A technical or hospitality rider for an engagement." }, "RiderCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Rider title.", "example": "Technical Rider 2026" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty whose rider it is.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["title", "project_id"], "description": "Fields accepted when creating a Rider." }, "RiderUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Rider title.", "example": "Technical Rider 2026" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty whose rider it is.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Rider. Omitted fields are unchanged." }, "RiderLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RiderLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RiderLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rider line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rider_id": { "type": "string", "format": "uuid", "description": "Identifier of the rider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 2 }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What is asked.", "example": "Two wedge monitors per vocalist." }, "element_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "Catalog element that fulfills the ask.", "example": "5000.02.01-NWL-001" }, "fulfilled_at": { "type": ["string", "null"], "format": "date-time", "description": "When the ask was fulfilled; NULL while open.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "rider_id", "quantity", "description", "element_id", "fulfilled_at" ], "description": "A rider line, reconciled against capabilities." }, "RiderLineCreate": { "type": "object", "properties": { "rider_id": { "type": "string", "format": "uuid", "description": "Identifier of the rider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 2 }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What is asked.", "example": "Two wedge monitors per vocalist." }, "element_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "Catalog element that fulfills the ask.", "example": "5000.02.01-NWL-001" }, "fulfilled_at": { "type": ["string", "null"], "format": "date-time", "description": "When the ask was fulfilled; NULL while open.", "example": "2026-10-08T14:30:00Z" } }, "required": ["rider_id", "description"], "description": "Fields accepted when creating a RiderLine." }, "RiderLineUpdate": { "type": "object", "properties": { "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 2 }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What is asked.", "example": "Two wedge monitors per vocalist." }, "element_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "Catalog element that fulfills the ask.", "example": "5000.02.01-NWL-001" }, "fulfilled_at": { "type": ["string", "null"], "format": "date-time", "description": "When the ask was fulfilled; NULL while open.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a RiderLine. Omitted fields are unchanged." }, "FulfillmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Fulfillment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "fulfillment_kind": { "$ref": "#/components/schemas/FulfillmentKind" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Fulfillment title.", "example": "Headliner Hotel Block" }, "fulfillment_state": { "type": "string", "enum": ["Proposed", "Active", "Blocked", "Complete", "Canceled"], "description": "Fulfillment state.", "example": "Proposed" }, "starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Service start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "Service end.", "example": "2026-10-08T14:30:00Z" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the supplier, such as the hotel or caterer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "fulfillment_number": { "type": "integer", "minimum": 1, "description": "Number within the project; the display key is {project_key}-{fulfillment_number}.", "example": 3 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "fulfillment_kind", "title", "fulfillment_state", "starts_at", "ends_at", "counterparty_id", "fulfillment_number" ], "description": "A lodging, catering, travel or amenity fulfillment." }, "FulfillmentKind": { "type": "string", "enum": ["Lodging", "Catering", "Travel", "Amenity"], "description": "Hospitality fulfillment kind.", "example": "Lodging" }, "FulfillmentCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "fulfillment_kind": { "$ref": "#/components/schemas/FulfillmentKind" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Fulfillment title.", "example": "Headliner Hotel Block" }, "starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Service start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "Service end.", "example": "2026-10-08T14:30:00Z" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the supplier, such as the hotel or caterer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["project_id", "fulfillment_kind", "title"], "description": "Fields accepted when creating a Fulfillment." }, "FulfillmentUpdate": { "type": "object", "properties": { "fulfillment_kind": { "$ref": "#/components/schemas/FulfillmentKind" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Fulfillment title.", "example": "Headliner Hotel Block" }, "starts_at": { "type": ["string", "null"], "format": "date-time", "description": "Service start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "Service end.", "example": "2026-10-08T14:30:00Z" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the supplier, such as the hotel or caterer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Fulfillment. Omitted fields are unchanged." }, "FulfillmentTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Proposed" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Active" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "FulfillmentLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "FulfillmentLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "fulfillment_id": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "King room, 3 nights" }, "quantity": { "type": "number", "description": "Quantity.", "example": 4 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 32900, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the price; required when the line is priced.", "example": "USD" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the guest the line is for, such as a room night.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "fulfillment_id", "description", "quantity", "unit_price_minor", "currency_code", "person_id" ], "description": "A line of a fulfillment." }, "FulfillmentLineCreate": { "type": "object", "properties": { "fulfillment_id": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "King room, 3 nights" }, "quantity": { "type": "number", "description": "Quantity.", "example": 4 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 32900, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the price; required when the line is priced.", "example": "USD" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the guest the line is for, such as a room night.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["fulfillment_id", "description"], "description": "Fields accepted when creating a FulfillmentLine." }, "FulfillmentLineUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "King room, 3 nights" }, "quantity": { "type": "number", "description": "Quantity.", "example": 4 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 32900, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the price; required when the line is priced.", "example": "USD" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the guest the line is for, such as a room night.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a FulfillmentLine. Omitted fields are unchanged." }, "BeoPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Beo" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Beo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the beo.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "fulfillment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the catering fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "event_at": { "type": "string", "format": "date-time", "description": "Service time.", "example": "2026-10-08T14:30:00Z" }, "guest_count": { "type": ["integer", "null"], "minimum": 0, "description": "Guaranteed count.", "example": 140 }, "beo_number": { "type": "integer", "minimum": 1, "description": "Number within the project; the display key is {project_key}-{beo_number}.", "example": 4 }, "approved_at": { "type": ["string", "null"], "format": "date-time", "description": "When the BEO was approved.", "example": "2026-10-08T14:30:00Z" }, "approved_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who approved the BEO; never its author.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "fulfillment_id", "event_at", "guest_count", "beo_number", "approved_at", "approved_by" ], "description": "A banquet event order." }, "BeoCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "fulfillment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the catering fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "event_at": { "type": "string", "format": "date-time", "description": "Service time.", "example": "2026-10-08T14:30:00Z" }, "guest_count": { "type": ["integer", "null"], "minimum": 0, "description": "Guaranteed count.", "example": 140 } }, "required": ["project_id", "event_at"], "description": "Fields accepted when creating a Beo." }, "BeoUpdate": { "type": "object", "properties": { "fulfillment_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the catering fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "event_at": { "type": "string", "format": "date-time", "description": "Service time.", "example": "2026-10-08T14:30:00Z" }, "guest_count": { "type": ["integer", "null"], "minimum": 0, "description": "Guaranteed count.", "example": 140 } }, "description": "Fields accepted when updating a Beo. Omitted fields are unchanged." }, "BeoLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BeoLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "BeoLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the beo line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "beo_id": { "type": "string", "format": "uuid", "description": "Identifier of the BEO.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Menu item or service.", "example": "Grilled vegetable wraps" }, "quantity": { "type": "number", "description": "Quantity.", "example": 140 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1450, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the price; required when the line is priced.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "beo_id", "description", "quantity", "unit_price_minor", "currency_code" ], "description": "A line of a banquet event order." }, "BeoLineCreate": { "type": "object", "properties": { "beo_id": { "type": "string", "format": "uuid", "description": "Identifier of the BEO.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Menu item or service.", "example": "Grilled vegetable wraps" }, "quantity": { "type": "number", "description": "Quantity.", "example": 140 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1450, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the price; required when the line is priced.", "example": "USD" } }, "required": ["beo_id", "description"], "description": "Fields accepted when creating a BeoLine." }, "BeoLineUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Menu item or service.", "example": "Grilled vegetable wraps" }, "quantity": { "type": "number", "description": "Quantity.", "example": 140 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1450, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the price; required when the line is priced.", "example": "USD" } }, "description": "Fields accepted when updating a BeoLine. Omitted fields are unchanged." }, "AssetClassPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetClass" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AssetClass": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Asset class name.", "example": "Truss Section 10 ft" }, "element_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon element the class is.", "example": "5000.02.02-XPMS-003" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "element_id" ], "description": "An asset class bound to a catalog element (class grain)." }, "AssetClassCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Asset class name.", "example": "Truss Section 10 ft" }, "element_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon element the class is.", "example": "5000.02.02-XPMS-003" } }, "required": ["name", "element_id"], "description": "Fields accepted when creating a AssetClass." }, "AssetClassUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Asset class name.", "example": "Truss Section 10 ft" }, "element_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon element the class is.", "example": "5000.02.02-XPMS-003" } }, "description": "Fields accepted when updating a AssetClass. Omitted fields are unchanged." }, "AssetUnitPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetUnit" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AssetUnit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_class_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_tag": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Asset tag (a code that is ours).", "example": "NWL-TR-0042" }, "asset_state": { "type": "string", "enum": [ "Proposed", "Received", "Available", "Reserved", "Deployed", "In Maintenance", "Damaged", "Lost", "Retired" ], "description": "Asset lifecycle state.", "example": "Available" }, "condition_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Condition: a row of the canon Asset Condition enumeration.", "example": "ENM-017" }, "home_venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue the unit returns to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "asset_class_id", "asset_tag", "asset_state", "condition_enum_id", "home_venue_id" ], "description": "An individual asset tracked by serial or asset tag (unit grain), with a nine-value lifecycle." }, "AssetUnitCreate": { "type": "object", "properties": { "asset_class_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_tag": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Asset tag (a code that is ours).", "example": "NWL-TR-0042" }, "condition_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Condition: a row of the canon Asset Condition enumeration.", "example": "ENM-017" }, "home_venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue the unit returns to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["asset_class_id", "asset_tag"], "description": "Fields accepted when creating a AssetUnit." }, "AssetUnitUpdate": { "type": "object", "properties": { "condition_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Condition: a row of the canon Asset Condition enumeration.", "example": "ENM-017" }, "home_venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue the unit returns to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a AssetUnit. Omitted fields are unchanged." }, "AssetTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Active" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "In Review" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "ScanRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "Scanned barcode, QR or NFC payload.", "example": "NWL-TR-0042" }, "symbology": { "type": "string", "minLength": 1, "description": "Symbology of the scan.", "example": "code128" } }, "required": ["code", "symbology"], "description": "A scanned code." }, "AssetScanResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["applied", "duplicate"], "description": "applied for a new event; duplicate when the event id was already applied.", "example": "applied" }, "subject_kind": { "type": "string", "enum": ["unit", "lot"], "description": "What the code named.", "example": "unit" }, "subject_id": { "type": "string", "format": "uuid", "description": "The asset unit or lot moved.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "ledger_id": { "type": "string", "format": "uuid", "description": "The custody entry or lot movement, equal to the event id.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_state": { "type": ["string", "null"], "enum": [ "Proposed", "Received", "Available", "Reserved", "Deployed", "In Maintenance", "Damaged", "Lost", "Retired", null ], "description": "Units: the state after the move.", "example": "Available" }, "on_hand": { "type": ["number", "null"], "description": "Lots: the quantity on hand after the move.", "example": 72 } }, "required": [ "outcome", "subject_kind", "subject_id", "ledger_id", "asset_state", "on_hand" ], "description": "The outcome of one scan event." }, "AssetScanEvent": { "type": "object", "properties": { "event_id": { "type": "string", "format": "uuid", "description": "UUID the device minted when the scan happened and keeps in its offline queue. It becomes the custody entry or lot movement id, so replaying the event at any later time changes nothing.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e70" }, "code": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The scanned asset tag, external identifier (serial, GTIN) or lot label (LOT:).", "example": "NWL-RAD-014" }, "action": { "type": "string", "enum": ["check-out", "check-in", "transfer"], "description": "check-out hands the item to one custodian (the unit becomes Deployed); check-in returns it to a venue (the unit becomes Available); transfer passes a deployed unit to another custodian.", "example": "check-out" }, "custodian_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who takes the item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "custodian_engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external engagement that takes the item; never together with a member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue the item returns to; the unit's home venue by default.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the item is out for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "maxLength": 1000, "description": "Hand-over note.", "example": "Stage left radio." }, "quantity": { "type": ["number", "null"], "exclusiveMinimum": 0, "description": "Lots only: how many move.", "example": 12 } }, "required": ["event_id", "code", "action"], "description": "One custody move scanned on a device." }, "AssetLotPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetLot" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AssetLot": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the asset lot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_class_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue the lot sits at.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "quantity": { "type": "number", "description": "Quantity on hand.", "example": 36 }, "on_hand": { "type": "number", "description": "Quantity on hand: the opening count plus the lot ledger.", "example": 34 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "asset_class_id", "venue_id", "quantity", "on_hand" ], "description": "A quantity of an asset class at a place (lot grain)." }, "AssetLotCreate": { "type": "object", "properties": { "asset_class_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue the lot sits at.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "quantity": { "type": "number", "description": "Quantity on hand.", "example": 36 } }, "required": ["asset_class_id", "venue_id", "quantity"], "description": "Fields accepted when creating a AssetLot." }, "AssetLotUpdate": { "type": "object", "properties": { "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue the lot sits at.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a AssetLot. Omitted fields are unchanged." }, "AssetIdentifierPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetIdentifier" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AssetIdentifier": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the asset identifier.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "identifier_class": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Identifier class.", "example": "gtin" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Identifier value.", "example": "00012345678905" }, "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Scheme, such as serial, gtin14 or mpn.", "example": "serial" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "asset_unit_id", "identifier_class", "value", "scheme" ], "description": "An external identifier recorded against an asset unit, such as a GTIN or an NFC tag." }, "AssetIdentifierCreate": { "type": "object", "properties": { "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Identifier value.", "example": "00012345678905" }, "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Scheme, such as serial, gtin14 or mpn.", "example": "serial" } }, "required": ["asset_unit_id", "value", "scheme"], "description": "Fields accepted when creating a AssetIdentifier." }, "AssetCustodyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetCustody" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AssetCustody": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the asset custody.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "custodian_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who holds the unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "custodian_engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external engagement that holds the unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the place the unit is kept.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the unit is out for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "maxLength": 1000, "description": "Hand-over note.", "example": "Issued for load-in." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "asset_unit_id", "custodian_membership_id", "custodian_engagement_id", "venue_id", "project_id", "note" ], "description": "An append-only custody ledger entry." }, "AssetCustodyCreate": { "type": "object", "properties": { "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "custodian_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who holds the unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "custodian_engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external engagement that holds the unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the place the unit is kept.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the unit is out for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "maxLength": 1000, "description": "Hand-over note.", "example": "Issued for load-in." } }, "required": ["asset_unit_id"], "description": "Fields accepted when creating a AssetCustody." }, "AssetMaintenancePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetMaintenance" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AssetMaintenance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the asset maintenance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "performed_on": { "type": "string", "format": "date", "description": "When the maintenance was done.", "example": "2026-10-08" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What was done.", "example": "Replaced the spigots." }, "cost_minor": { "type": ["integer", "null"], "description": "Maintenance cost. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 12000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "asset_unit_id", "performed_on", "description", "cost_minor", "currency_code" ], "description": "A maintenance event for an asset unit." }, "AssetMaintenanceCreate": { "type": "object", "properties": { "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "performed_on": { "type": "string", "format": "date", "description": "When the maintenance was done.", "example": "2026-10-08" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What was done.", "example": "Replaced the spigots." }, "cost_minor": { "type": ["integer", "null"], "description": "Maintenance cost. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 12000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": ["asset_unit_id", "performed_on", "description"], "description": "Fields accepted when creating a AssetMaintenance." }, "AssetMaintenanceUpdate": { "type": "object", "properties": { "performed_on": { "type": "string", "format": "date", "description": "When the maintenance was done.", "example": "2026-10-08" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What was done.", "example": "Replaced the spigots." }, "cost_minor": { "type": ["integer", "null"], "description": "Maintenance cost. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 12000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "description": "Fields accepted when updating a AssetMaintenance. Omitted fields are unchanged." }, "AssetDamagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetDamage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AssetDamage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the asset damage.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reported_at": { "type": "string", "format": "date-time", "description": "When the damage was reported.", "example": "2026-10-08T14:30:00Z" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is damaged.", "example": "Bent chord on one end." }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project during which the damage happened.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "responsible_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty responsible.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "asset_unit_id", "reported_at", "description", "project_id", "responsible_counterparty_id" ], "description": "A damage report for an asset unit." }, "AssetDamageCreate": { "type": "object", "properties": { "asset_unit_id": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reported_at": { "type": "string", "format": "date-time", "description": "When the damage was reported.", "example": "2026-10-08T14:30:00Z" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is damaged.", "example": "Bent chord on one end." }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project during which the damage happened.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "responsible_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty responsible.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["asset_unit_id", "description"], "description": "Fields accepted when creating a AssetDamage." }, "AssetDamageUpdate": { "type": "object", "properties": { "reported_at": { "type": "string", "format": "date-time", "description": "When the damage was reported.", "example": "2026-10-08T14:30:00Z" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is damaged.", "example": "Bent chord on one end." }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project during which the damage happened.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "responsible_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty responsible.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a AssetDamage. Omitted fields are unchanged." }, "RoleAssignmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RoleAssignment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the role assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the assigned person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "requisition_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the requisition the assignment fills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "staffing_basis": { "type": "string", "enum": ["Declared", "Ratio", "Fixed"], "description": "How the role was sized: from the canon staffing ratio, a fixed canon count per tier, or declared.", "example": "Declared" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the assignment.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the assignment.", "example": "2026-10-08" }, "assignment_state": { "type": "string", "enum": ["Proposed", "Active", "Complete", "Canceled"], "description": "Assignment state.", "example": "Proposed" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "role_code", "scope_node_id", "person_id", "requisition_id", "staffing_basis", "starts_on", "ends_on", "assignment_state" ], "description": "A canon workforce role staffed on a project, with its staffing ratio basis." }, "RoleCode": { "type": "string", "pattern": "^[0-9]000\\.[0-9]{2}\\.[0-9]{2}$", "description": "Workforce role code from `xpms.dim_role`, on URID grammar.", "example": "5000.50.01" }, "RoleAssignmentCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the assigned person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "requisition_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the requisition the assignment fills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "staffing_basis": { "type": "string", "enum": ["Declared", "Ratio", "Fixed"], "description": "How the role was sized: from the canon staffing ratio, a fixed canon count per tier, or declared.", "example": "Declared" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the assignment.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the assignment.", "example": "2026-10-08" } }, "required": ["project_id", "role_code", "person_id"], "description": "Fields accepted when creating a RoleAssignment." }, "RoleAssignmentUpdate": { "type": "object", "properties": { "role_code": { "$ref": "#/components/schemas/RoleCode" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the assigned person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "requisition_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the requisition the assignment fills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "staffing_basis": { "type": "string", "enum": ["Declared", "Ratio", "Fixed"], "description": "How the role was sized: from the canon staffing ratio, a fixed canon count per tier, or declared.", "example": "Declared" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the assignment.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the assignment.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a RoleAssignment. Omitted fields are unchanged." }, "RequisitionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Requisition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Requisition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the requisition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "requisition_state": { "type": "string", "enum": ["Proposed", "Approved", "Rejected", "Filled", "Canceled"], "description": "Requisition state.", "example": "Proposed" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line the cost is charged to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_type": { "type": ["string", "null"], "enum": [ "Crew", "Contractor", "Staff", "Vendor", "Artist", "Artist Representative", "Client", "Sponsor", null ], "description": "External role type an opportunity published from the requisition seeks; null when filled internally.", "example": "Crew" }, "worker_classification": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification, from xpms.worker_classification.", "example": "EMPLOYEE" }, "pay_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pay basis; set with the arrangement.", "example": "Hourly" }, "arrangement": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Arrangement; set with the pay basis.", "example": "Per Engagement" }, "headcount": { "type": "integer", "minimum": 1, "description": "People requested.", "example": 12 }, "units_per_head": { "type": ["number", "null"], "description": "Pay basis units each person works, such as hours.", "example": 10 }, "rate_minor": { "type": ["integer", "null"], "description": "Rate per pay basis unit. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the rate.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work.", "example": "2026-10-08" }, "justification": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the staff are needed.", "example": "Second stage added for the festival." }, "requested_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who requested; they cannot approve it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "role_code", "requisition_state", "scope_node_id", "budget_line_id", "role_type", "worker_classification", "pay_basis", "arrangement", "headcount", "units_per_head", "rate_minor", "currency_code", "starts_on", "ends_on", "justification", "requested_by" ], "description": "A staffing or purchase requisition, approved before an opportunity is published." }, "RequisitionCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line the cost is charged to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_type": { "type": ["string", "null"], "enum": [ "Crew", "Contractor", "Staff", "Vendor", "Artist", "Artist Representative", "Client", "Sponsor", null ], "description": "External role type an opportunity published from the requisition seeks; null when filled internally.", "example": "Crew" }, "worker_classification": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification, from xpms.worker_classification.", "example": "EMPLOYEE" }, "pay_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pay basis; set with the arrangement.", "example": "Hourly" }, "arrangement": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Arrangement; set with the pay basis.", "example": "Per Engagement" }, "headcount": { "type": "integer", "minimum": 1, "description": "People requested.", "example": 12 }, "units_per_head": { "type": ["number", "null"], "description": "Pay basis units each person works, such as hours.", "example": 10 }, "rate_minor": { "type": ["integer", "null"], "description": "Rate per pay basis unit. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the rate.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work.", "example": "2026-10-08" }, "justification": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the staff are needed.", "example": "Second stage added for the festival." } }, "required": ["project_id", "role_code", "currency_code", "justification"], "description": "Fields accepted when creating a Requisition." }, "RequisitionUpdate": { "type": "object", "properties": { "role_code": { "$ref": "#/components/schemas/RoleCode" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line the cost is charged to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_type": { "type": ["string", "null"], "enum": [ "Crew", "Contractor", "Staff", "Vendor", "Artist", "Artist Representative", "Client", "Sponsor", null ], "description": "External role type an opportunity published from the requisition seeks; null when filled internally.", "example": "Crew" }, "worker_classification": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification, from xpms.worker_classification.", "example": "EMPLOYEE" }, "pay_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pay basis; set with the arrangement.", "example": "Hourly" }, "arrangement": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Arrangement; set with the pay basis.", "example": "Per Engagement" }, "headcount": { "type": "integer", "minimum": 1, "description": "People requested.", "example": 12 }, "units_per_head": { "type": ["number", "null"], "description": "Pay basis units each person works, such as hours.", "example": 10 }, "rate_minor": { "type": ["integer", "null"], "description": "Rate per pay basis unit. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the rate.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work.", "example": "2026-10-08" }, "justification": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the staff are needed.", "example": "Second stage added for the festival." } }, "description": "Fields accepted when updating a Requisition. Omitted fields are unchanged." }, "RequisitionTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Approved" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Filled" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "OfferPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Offer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application the offer answers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the offered person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the offered organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_type": { "anyOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": "null" }] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the terms in force lapse unanswered.", "example": "2026-10-08T14:30:00Z" }, "offer_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Offer state. A Title Case value from the lifecycle's database enum.", "example": "Active" }, "responded_at": { "type": ["string", "null"], "format": "date-time", "description": "When the offer was answered.", "example": "2026-10-08T14:30:00Z" }, "version_number": { "type": "integer", "minimum": 0, "description": "Version of the terms in force, issued by the database; the highest is in force.", "example": 1 }, "proposed_side": { "type": "string", "enum": ["Organization", "Party"], "description": "Side that proposed the terms in force.", "example": "Organization" }, "amount_minor": { "type": ["integer", "null"], "description": "Offered amount per rate unit; null when the version leaves the amount open. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 45000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the amount.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work offered.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work offered.", "example": "2026-10-08" }, "message": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Message to the other side with the terms. Visible to both sides.", "example": "Rate includes the load-in day." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "application_id", "person_id", "organization_id", "rate_type", "expires_at", "offer_state", "responded_at", "version_number", "proposed_side", "amount_minor", "currency_code", "starts_on", "ends_on", "message" ], "description": "Terms issued to a person or organization: accepted, countered or declined." }, "RateType": { "type": "string", "enum": ["Hourly", "Day", "Flat", "Milestone", "Bid"], "description": "Compensation rate type.", "example": "Day" }, "OfferCreate": { "type": "object", "properties": { "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application the offer answers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_type": { "anyOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": "null" }] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the terms in force lapse unanswered.", "example": "2026-10-08T14:30:00Z" }, "amount_minor": { "type": ["integer", "null"], "description": "Offered amount per rate unit; null when the version leaves the amount open. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 45000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the amount.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work offered.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work offered.", "example": "2026-10-08" }, "message": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Message to the other side with the terms. Visible to both sides.", "example": "Rate includes the load-in day." } }, "required": ["application_id"], "description": "Fields accepted when creating a Offer." }, "OfferUpdate": { "type": "object", "properties": { "rate_type": { "anyOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": "null" }] }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the terms in force lapse unanswered.", "example": "2026-10-08T14:30:00Z" }, "amount_minor": { "type": ["integer", "null"], "description": "Offered amount per rate unit; null when the version leaves the amount open. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 45000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the amount.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work offered.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work offered.", "example": "2026-10-08" }, "message": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Message to the other side with the terms. Visible to both sides.", "example": "Rate includes the load-in day." } }, "description": "Fields accepted when updating a Offer. Omitted fields are unchanged." }, "OfferDeclineRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why, recorded on the offer's state transition.", "example": "The dates conflict with another booking." } }, "required": ["reason"], "description": "Request to decline an offer." }, "OfferCounterRequest": { "type": "object", "properties": { "rate_type": { "anyOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": "null" }] }, "amount_minor": { "type": ["integer", "null"], "description": "Offered amount per rate unit; null when the version leaves the amount open. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 45000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the amount.", "example": "USD" }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work offered.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work offered.", "example": "2026-10-08" }, "message": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Message to the other side with the terms. Visible to both sides.", "example": "Rate includes the load-in day." } }, "description": "Counter terms for an offer." }, "OfferWithdrawRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why, recorded on the offer's state transition.", "example": "The position was filled internally." } }, "required": ["reason"], "description": "Request to withdraw an offer." }, "AgreementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agreement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Agreement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Agreement title.", "example": "Crew Agreement 2026" }, "agreement_state": { "type": "string", "enum": ["Proposed", "Sent", "Signed", "Superseded", "Expired", "Canceled"], "description": "Agreement state.", "example": "Proposed" }, "signed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the agreement was signed.", "example": "2026-10-08T14:30:00Z" }, "agreement_kind": { "type": "string", "enum": [ "Offer Letter", "Contractor Agreement", "Master Services Agreement", "Non-Disclosure Agreement" ], "description": "Kind of agreement.", "example": "Offer Letter" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Full text the signer reads and signs; changes only while Proposed.", "example": "The crew member agrees to the call times in the schedule." }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the agreement covers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "offer_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the offer the agreement follows.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person party to the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external organization party to the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "token_expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the signing link stops working.", "example": "2026-10-08T14:30:00Z" }, "signed_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Name the signer typed as their signature.", "example": "Alex Rivera" }, "signed_body_sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the text that was signed, lowercase hex.", "example": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "title", "agreement_state", "signed_at", "agreement_kind", "body", "project_id", "offer_id", "person_id", "counterparty_id", "token_expires_at", "signed_name", "signed_body_sha256" ], "description": "A contractor MSA, offer letter or crew agreement with token signing. A signed agreement cannot be revoked or unsigned." }, "AgreementCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Agreement title.", "example": "Crew Agreement 2026" }, "agreement_kind": { "type": "string", "enum": [ "Offer Letter", "Contractor Agreement", "Master Services Agreement", "Non-Disclosure Agreement" ], "description": "Kind of agreement.", "example": "Offer Letter" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Full text the signer reads and signs; changes only while Proposed.", "example": "The crew member agrees to the call times in the schedule." }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the agreement covers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "offer_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the offer the agreement follows.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person party to the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external organization party to the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["title", "agreement_kind", "body"], "description": "Fields accepted when creating a Agreement." }, "AgreementUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Agreement title.", "example": "Crew Agreement 2026" }, "agreement_kind": { "type": "string", "enum": [ "Offer Letter", "Contractor Agreement", "Master Services Agreement", "Non-Disclosure Agreement" ], "description": "Kind of agreement.", "example": "Offer Letter" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Full text the signer reads and signs; changes only while Proposed.", "example": "The crew member agrees to the call times in the schedule." }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the agreement covers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "offer_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the offer the agreement follows.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person party to the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external organization party to the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Agreement. Omitted fields are unchanged." }, "AgreementSignRequest": { "type": "object", "properties": { "signed_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name the signer types as their signature.", "example": "Alex Rivera" }, "body_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the agreement text the signer read, lowercase hex.", "example": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } }, "required": ["signed_name", "body_sha256"], "description": "The signature on an agreement." }, "ShiftPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shift" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Shift": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Shift record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Call time.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Wrap time.", "example": "2026-10-08T14:30:00Z" }, "shift_state": { "type": "string", "enum": ["Draft", "Published", "Accepted", "Canceled"], "description": "Shift state.", "example": "Draft" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person on the shift; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node of the same project, such as the show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the call and wrap times are shown in.", "example": "America/New_York" }, "scheduled_break_minutes": { "type": ["integer", "null"], "minimum": 0, "description": "Meal break scheduled within the shift, in minutes.", "example": 30 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "record_id", "role_code", "engagement_id", "starts_at", "ends_at", "shift_state", "membership_id", "scope_node_id", "time_zone", "scheduled_break_minutes" ], "description": "A staffed crew block. A shift cannot end before it starts." }, "ShiftCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Shift record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Call time.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Wrap time.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person on the shift; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node of the same project, such as the show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the call and wrap times are shown in.", "example": "America/New_York" }, "scheduled_break_minutes": { "type": ["integer", "null"], "minimum": 0, "description": "Meal break scheduled within the shift, in minutes.", "example": 30 } }, "required": ["project_id", "starts_at", "ends_at", "time_zone"], "description": "Fields accepted when creating a Shift." }, "ShiftUpdate": { "type": "object", "properties": { "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Shift record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Call time.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Wrap time.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person on the shift; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node of the same project, such as the show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the call and wrap times are shown in.", "example": "America/New_York" }, "scheduled_break_minutes": { "type": ["integer", "null"], "minimum": 0, "description": "Meal break scheduled within the shift, in minutes.", "example": 30 } }, "description": "Fields accepted when updating a Shift. Omitted fields are unchanged." }, "ShiftTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Draft" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Published" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "ShiftClaimResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Shift record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Call time.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Wrap time.", "example": "2026-10-08T14:30:00Z" }, "shift_state": { "type": "string", "enum": ["Draft", "Published", "Accepted", "Canceled"], "description": "Shift state.", "example": "Draft" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person on the shift; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node of the same project, such as the show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the call and wrap times are shown in.", "example": "America/New_York" }, "scheduled_break_minutes": { "type": ["integer", "null"], "minimum": 0, "description": "Meal break scheduled within the shift, in minutes.", "example": 30 }, "claim": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the waiting claim.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "claim_state": { "type": "string", "enum": ["Requested"], "description": "State of the claim: Requested until a supervisor approves or rejects it.", "example": "Requested" } }, "required": ["id", "claim_state"], "description": "The caller's waiting claim when the claiming rule is approval or seniority; null when the caller got the shift (first-come)." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "record_id", "role_code", "engagement_id", "starts_at", "ends_at", "shift_state", "membership_id", "scope_node_id", "time_zone", "scheduled_break_minutes", "claim" ], "description": "The shift after a claim, with the caller's waiting claim when a supervisor decides it.", "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": null, "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Published", "membership_id": null, "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30, "claim": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "claim_state": "Requested" } } }, "ShiftSwapPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShiftSwap" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ShiftSwap": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the shift swap.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shift_id": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "swap_state": { "type": "string", "enum": ["Proposed", "Approved", "Rejected", "Canceled"], "description": "Swap state.", "example": "Proposed" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the shift, copied from it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "requested_by_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person on the shift who asks to swap.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "proposed_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person who would take the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "shift_id", "swap_state", "project_id", "requested_by_membership_id", "proposed_membership_id" ], "description": "A swap request. A crew member cannot approve their own swap." }, "ShiftSwapCreate": { "type": "object", "properties": { "shift_id": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "proposed_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person who would take the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["shift_id", "proposed_membership_id"], "description": "Fields accepted when creating a ShiftSwap." }, "TimeEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TimeEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the time entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shift_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "clock_in": { "type": "string", "format": "date-time", "description": "Clock in.", "example": "2026-10-08T14:30:00Z" }, "clock_out": { "type": ["string", "null"], "format": "date-time", "description": "Clock out.", "example": "2026-10-08T14:30:00Z" }, "break_minutes": { "type": "integer", "minimum": 0, "description": "Break minutes.", "example": 30 }, "kiosk_device_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the kiosk device.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project worked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person who worked; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement of the person who worked when external crew; null for members.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "source": { "type": "string", "enum": ["Web", "Mobile", "Kiosk"], "description": "Where the punch came from.", "example": "Web" }, "auto_closed_at": { "type": ["string", "null"], "format": "date-time", "description": "When a forgotten clock-out was closed automatically at 16 hours.", "example": "2026-10-08T14:30:00Z" }, "needs_review": { "type": "boolean", "description": "Whether the entry was closed automatically and awaits review.", "example": false }, "meal_out_at": { "type": ["string", "null"], "format": "date-time", "description": "Effective time of the entry's first Break Start punch (meal out).", "example": "2026-10-08T14:30:00Z" }, "meal_in_at": { "type": ["string", "null"], "format": "date-time", "description": "Effective time of the entry's last Break End punch (meal in).", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "shift_id", "clock_in", "clock_out", "break_minutes", "kiosk_device_id", "project_id", "membership_id", "engagement_id", "source", "auto_closed_at", "needs_review", "meal_out_at", "meal_in_at" ], "description": "A time entry. Entries cannot overlap for one person; forgotten clock-outs close at 16 hours and are flagged." }, "TimeEntryClockInRequest": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project the caller clocks in on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shift_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Accepted shift of the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the caller's open engagement, when they work as external crew.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "punch_id": { "type": "string", "format": "uuid", "description": "Client punch id; a replay with the same id returns the same entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "device_time": { "type": "string", "format": "date-time", "description": "When the punch was made on the device; defaults to now.", "example": "2026-10-08T14:30:00Z" }, "monotonic_offset_ms": { "type": "integer", "minimum": 0, "description": "Milliseconds since the punch on the device's monotonic clock, for a punch queued offline.", "example": 0, "format": "int64" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 }, "accuracy_m": { "type": ["number", "null"], "minimum": 0, "description": "Location accuracy in metres.", "example": 12 }, "geofence_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the geofence the location is checked against.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["project_id"], "description": "The punch that opens the caller's time entry." }, "TimeEntryCorrectionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntryCorrection" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TimeEntryCorrection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the time entry correction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_entry_id": { "type": "string", "format": "uuid", "description": "Identifier of the time entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why the correction is needed.", "example": "Forgot to clock out at wrap." }, "correction_state": { "type": "string", "enum": ["Proposed", "Approved", "Rejected"], "description": "Correction state.", "example": "Proposed" }, "proposed_clock_in": { "type": "string", "format": "date-time", "description": "Proposed clock in.", "example": "2026-10-08T14:30:00Z" }, "proposed_clock_out": { "type": ["string", "null"], "format": "date-time", "description": "Proposed clock out.", "example": "2026-10-08T14:30:00Z" }, "proposed_break_minutes": { "type": "integer", "minimum": 0, "description": "Proposed unpaid break minutes.", "example": 30 }, "requested_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who asked for the correction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "time_entry_id", "reason", "correction_state", "proposed_clock_in", "proposed_clock_out", "proposed_break_minutes", "requested_by" ], "description": "A requested correction to a time entry." }, "TimeEntryCorrectionCreate": { "type": "object", "properties": { "time_entry_id": { "type": "string", "format": "uuid", "description": "Identifier of the time entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why the correction is needed.", "example": "Forgot to clock out at wrap." }, "proposed_clock_in": { "type": "string", "format": "date-time", "description": "Proposed clock in.", "example": "2026-10-08T14:30:00Z" }, "proposed_clock_out": { "type": ["string", "null"], "format": "date-time", "description": "Proposed clock out.", "example": "2026-10-08T14:30:00Z" }, "proposed_break_minutes": { "type": "integer", "minimum": 0, "description": "Proposed unpaid break minutes.", "example": 30 } }, "required": ["time_entry_id", "reason", "proposed_clock_in"], "description": "Fields accepted when creating a TimeEntryCorrection." }, "TimeEntryAuditPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntryAudit" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TimeEntryAudit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the time entry audit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_entry_id": { "type": "string", "format": "uuid", "description": "Identifier of the time entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "old_values": { "type": ["object", "null"], "additionalProperties": {}, "description": "Changed columns before the change; null on insert.", "example": { "type": "doc" } }, "new_values": { "type": "object", "additionalProperties": {}, "description": "Changed columns after the change.", "example": { "type": "doc" } } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "time_entry_id", "old_values", "new_values" ], "description": "An append-only audit row for a time entry change." }, "TimesheetPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Timesheet" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Timesheet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the timesheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "timesheet_state": { "type": "string", "enum": ["Proposed", "Submitted", "Approved", "Rejected"], "description": "Timesheet state.", "example": "Proposed" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project worked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person who worked; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement of the person who worked when external crew; null for members.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "period_start": { "type": "string", "format": "date", "description": "First day of the period.", "example": "2026-10-08" }, "period_end": { "type": "string", "format": "date", "description": "Last day of the period.", "example": "2026-10-08" }, "submitted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who submitted the timesheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "timesheet_state", "project_id", "membership_id", "engagement_id", "period_start", "period_end", "submitted_by" ], "description": "A timesheet for one person and pay period. An approval is voided when its hours change." }, "TimesheetCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project worked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person who worked; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement of the person who worked when external crew; null for members.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "period_start": { "type": "string", "format": "date", "description": "First day of the period.", "example": "2026-10-08" }, "period_end": { "type": "string", "format": "date", "description": "Last day of the period.", "example": "2026-10-08" } }, "required": ["project_id", "period_start", "period_end"], "description": "Fields accepted when creating a Timesheet." }, "TimesheetApprovalPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetApproval" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TimesheetApproval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the timesheet approval.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "timesheet_id": { "type": "string", "format": "uuid", "description": "Identifier of the timesheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approved_by": { "type": "string", "format": "uuid", "description": "Identifier of the approver.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approved_minutes": { "type": "integer", "minimum": 0, "description": "Minutes approved.", "example": 2490 }, "voided_at": { "type": ["string", "null"], "format": "date-time", "description": "When an hours change voided the approval.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "timesheet_id", "approved_by", "approved_minutes", "voided_at" ], "description": "An approval decision on a timesheet. The submitter cannot approve it." }, "KioskDevicePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KioskDevice" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "KioskDevice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the kiosk device.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Device name.", "example": "Gate A Kiosk" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the kiosk serves.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "device_key": { "type": ["string", "null"], "pattern": "^xkio_[0-9a-f]{64}$", "description": "Device key the kiosk signs in with. Returned once, in the create response; null on every read, because only its hash is kept (invariant 8).", "example": "xkio_9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "last_seen_at": { "type": ["string", "null"], "format": "date-time", "description": "Last time the kiosk checked in.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the kiosk was revoked; it accepts no punches.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "project_id", "device_key", "last_seen_at", "revoked_at" ], "description": "A shared device in kiosk mode. Worker PINs are stored hashed and never returned." }, "KioskDeviceCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Device name.", "example": "Gate A Kiosk" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the kiosk serves.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name"], "description": "Fields accepted when creating a KioskDevice." }, "KioskDeviceUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Device name.", "example": "Gate A Kiosk" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the kiosk serves.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a KioskDevice. Omitted fields are unchanged." }, "RateCardPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RateCard" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RateCard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rate card.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Rate card name.", "example": "Local Stagehand Rates 2026" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the card applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the card applies.", "example": "2026-10-08" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "currency_code", "effective_from", "effective_to" ], "description": "A labor rate card." }, "RateCardCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Rate card name.", "example": "Local Stagehand Rates 2026" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the card applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the card applies.", "example": "2026-10-08" } }, "required": ["name", "currency_code", "effective_from"], "description": "Fields accepted when creating a RateCard." }, "RateCardUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Rate card name.", "example": "Local Stagehand Rates 2026" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the card applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the card applies.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a RateCard. Omitted fields are unchanged." }, "RateCardLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RateCardLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RateCardLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rate card line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_card_id": { "type": "string", "format": "uuid", "description": "Identifier of the rate card.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "anyOf": [ { "type": "integer" }, { "$ref": "#/components/schemas/Masked" }, { "type": "null" } ] }, "worker_classification": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification priced, from xpms.worker_classification.", "example": "EMPLOYEE" }, "pay_basis": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pay basis; with the classification a permitted pair.", "example": "Hourly" }, "arrangement": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Arrangement; with the classification a permitted pair.", "example": "Per Engagement" }, "overtime_rule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon overtime rule whose multipliers apply.", "example": "OTR-001" }, "canon_rate_card_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon rate card the line was adopted from.", "example": "LRC-001" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "rate_card_id", "role_code", "rate_minor", "worker_classification", "pay_basis", "arrangement", "overtime_rule_id", "canon_rate_card_id" ], "description": "A rate card line by role." }, "Masked": { "type": "object", "properties": { "masked": { "type": "boolean", "enum": [true], "description": "Always true for a masked value.", "example": true }, "reason": { "type": "string", "description": "Why the value is masked, naming the capability that would reveal it.", "example": "Requires data.restricted.read.payroll." } }, "required": ["masked", "reason"], "description": "A Restricted field the caller may not read. The field stays present." }, "RateCardLineCreate": { "type": "object", "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "Identifier of the rate card.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "type": ["integer", "null"], "description": "Rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "worker_classification": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification priced, from xpms.worker_classification.", "example": "EMPLOYEE" }, "pay_basis": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pay basis; with the classification a permitted pair.", "example": "Hourly" }, "arrangement": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Arrangement; with the classification a permitted pair.", "example": "Per Engagement" }, "overtime_rule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon overtime rule whose multipliers apply.", "example": "OTR-001" }, "canon_rate_card_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon rate card the line was adopted from.", "example": "LRC-001" } }, "required": [ "rate_card_id", "role_code", "worker_classification", "pay_basis", "arrangement", "overtime_rule_id" ], "description": "Fields accepted when creating a RateCardLine." }, "RateCardLineUpdate": { "type": "object", "properties": { "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "type": ["integer", "null"], "description": "Rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "worker_classification": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification priced, from xpms.worker_classification.", "example": "EMPLOYEE" }, "pay_basis": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pay basis; with the classification a permitted pair.", "example": "Hourly" }, "arrangement": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Arrangement; with the classification a permitted pair.", "example": "Per Engagement" }, "overtime_rule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon overtime rule whose multipliers apply.", "example": "OTR-001" }, "canon_rate_card_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon rate card the line was adopted from.", "example": "LRC-001" } }, "description": "Fields accepted when updating a RateCardLine. Omitted fields are unchanged." }, "PayRatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayRate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PayRate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the pay rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "anyOf": [ { "type": "integer" }, { "$ref": "#/components/schemas/Masked" }, { "type": "null" } ] }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person paid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the rate.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "role_code", "rate_minor", "effective_from", "membership_id", "currency_code" ], "description": "An append-only pay rate ledger entry for a person. Restricted." }, "PayRateCreate": { "type": "object", "properties": { "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "type": "integer", "minimum": 0, "description": "Pay rate per hour. Integer minor units of the row's currency.", "example": 5200, "format": "int64" }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person paid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the rate.", "example": "USD" } }, "required": ["role_code", "rate_minor", "effective_from", "membership_id", "currency_code"], "description": "Fields accepted when creating a PayRate." }, "OvertimeRulePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OvertimeRule" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OvertimeRule": { "type": "object", "properties": { "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "source": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Statute or source of the rule.", "example": "Fair Labor Standards Act, 29 U.S.C. 207" }, "weekly_ot_after_hours": { "type": ["number", "null"], "description": "Weekly hours after which overtime applies.", "example": 40 }, "daily_ot_after_hours": { "type": ["number", "null"], "description": "Daily hours after which overtime applies.", "example": 8 }, "daily_dt_after_hours": { "type": ["number", "null"], "description": "Daily hours after which double time applies.", "example": 12 }, "min_ot_multiplier": { "type": ["number", "null"], "description": "Minimum overtime multiplier.", "example": 1.5 }, "min_dt_multiplier": { "type": ["number", "null"], "description": "Minimum double time multiplier.", "example": 2 } }, "required": [ "jurisdiction_id", "source", "weekly_ot_after_hours", "daily_ot_after_hours", "daily_dt_after_hours", "min_ot_multiplier", "min_dt_multiplier" ], "description": "A jurisdiction's wage and hour rule from canon: daily and weekly overtime thresholds and minimum multipliers. A lower jurisdiction inherits its parent's rule." }, "UnionLocalRatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UnionLocalRate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "UnionLocalRate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the union local rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "union_local": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Union local.", "example": "Local 500" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "anyOf": [ { "type": "integer" }, { "$ref": "#/components/schemas/Masked" }, { "type": "null" } ] }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "fringe_minor": { "type": ["integer", "null"], "description": "Fringe per hour. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1200, "format": "int64" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the rate applies.", "example": "2026-10-08" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "union_local", "role_code", "rate_minor", "currency_code", "effective_from", "fringe_minor", "effective_to" ], "description": "A union local's scale rate for a role." }, "UnionLocalRateCreate": { "type": "object", "properties": { "union_local": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Union local.", "example": "Local 500" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "type": "integer", "minimum": 0, "description": "Scale rate per hour. Integer minor units of the row's currency.", "example": 5600, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "fringe_minor": { "type": ["integer", "null"], "description": "Fringe per hour. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1200, "format": "int64" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the rate applies.", "example": "2026-10-08" } }, "required": ["union_local", "role_code", "rate_minor", "currency_code", "effective_from"], "description": "Fields accepted when creating a UnionLocalRate." }, "UnionLocalRateUpdate": { "type": "object", "properties": { "union_local": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Union local.", "example": "Local 500" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "rate_minor": { "type": "integer", "minimum": 0, "description": "Scale rate per hour. Integer minor units of the row's currency.", "example": 5600, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "fringe_minor": { "type": ["integer", "null"], "description": "Fringe per hour. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1200, "format": "int64" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the rate applies.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a UnionLocalRate. Omitted fields are unchanged." }, "WageDeterminationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WageDetermination" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WageDetermination": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the wage determination.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "minimum_rate_minor": { "type": ["integer", "null"], "description": "Prevailing minimum rate per hour. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4800, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the determination applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the determination applies.", "example": "2026-10-08" }, "source": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Determination source or reference.", "example": "FL20260001" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "jurisdiction_id", "role_code", "minimum_rate_minor", "currency_code", "effective_from", "effective_to", "source" ], "description": "A prevailing wage determination by jurisdiction." }, "WageDeterminationCreate": { "type": "object", "properties": { "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "minimum_rate_minor": { "type": "integer", "minimum": 0, "description": "Prevailing minimum rate per hour. Integer minor units of the row's currency.", "example": 4800, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the determination applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the determination applies.", "example": "2026-10-08" }, "source": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Determination source or reference.", "example": "FL20260001" } }, "required": [ "jurisdiction_id", "role_code", "minimum_rate_minor", "currency_code", "effective_from", "source" ], "description": "Fields accepted when creating a WageDetermination." }, "WageDeterminationUpdate": { "type": "object", "properties": { "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "minimum_rate_minor": { "type": "integer", "minimum": 0, "description": "Prevailing minimum rate per hour. Integer minor units of the row's currency.", "example": 4800, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency.", "example": "USD" }, "effective_from": { "type": "string", "format": "date", "description": "First day the determination applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the determination applies.", "example": "2026-10-08" }, "source": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Determination source or reference.", "example": "FL20260001" } }, "description": "Fields accepted when updating a WageDetermination. Omitted fields are unchanged." }, "PayPeriodPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayPeriod" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PayPeriod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the pay period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_on": { "type": "string", "format": "date", "description": "First day.", "example": "2026-10-08" }, "ends_on": { "type": "string", "format": "date", "description": "Last day.", "example": "2026-10-08" }, "pay_period_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Pay period state. A Title Case value from the lifecycle's database enum.", "example": "Open" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "starts_on", "ends_on", "pay_period_state" ], "description": "A pay period. A posted pay period cannot reopen." }, "PayPeriodCreate": { "type": "object", "properties": { "starts_on": { "type": "string", "format": "date", "description": "First day.", "example": "2026-10-08" }, "ends_on": { "type": "string", "format": "date", "description": "Last day.", "example": "2026-10-08" } }, "required": ["starts_on", "ends_on"], "description": "Fields accepted when creating a PayPeriod." }, "PayPeriodUpdate": { "type": "object", "properties": { "starts_on": { "type": "string", "format": "date", "description": "First day.", "example": "2026-10-08" }, "ends_on": { "type": "string", "format": "date", "description": "Last day.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a PayPeriod. Omitted fields are unchanged." }, "PayPeriodTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Open" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Closed" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "PayrollRunPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollRun" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PayrollRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "pay_period_id": { "type": "string", "format": "uuid", "description": "Identifier of the pay period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payroll_run_state": { "type": "string", "enum": ["Draft", "Calculated", "Approved", "Exported", "Accepted", "Canceled"], "description": "Payroll run state.", "example": "Draft" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "pay_period_id", "payroll_run_state", "currency_code" ], "description": "A payroll run. It cannot jump from Draft to Accepted." }, "PayrollRunCreate": { "type": "object", "properties": { "pay_period_id": { "type": "string", "format": "uuid", "description": "Identifier of the pay period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": ["pay_period_id", "currency_code"], "description": "Fields accepted when creating a PayrollRun." }, "PayrollRunTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Exported" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Accepted" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "PayrollLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PayrollLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the payroll line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payroll_run_id": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "earning_code_id": { "type": "string", "format": "uuid", "description": "Identifier of the earning code.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hours": { "type": "number", "description": "Hours.", "example": 8 }, "amount_minor": { "anyOf": [ { "type": "integer" }, { "$ref": "#/components/schemas/Masked" }, { "type": "null" } ] }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person paid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_minor": { "anyOf": [ { "type": "integer" }, { "$ref": "#/components/schemas/Masked" }, { "type": "null" } ] }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center charged.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "payroll_run_id", "earning_code_id", "hours", "amount_minor", "membership_id", "rate_minor", "role_code", "cost_center_id" ], "description": "A payroll line, derived from approved timesheets." }, "PayrollExportPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollExport" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PayrollExport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the payroll export.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payroll_run_id": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provider": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Target payroll provider.", "example": "payroll_csv" }, "file_uri": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Logical location of the export file.", "example": "payroll-exports/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f.csv" }, "checksum_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the export file, lowercase hex.", "example": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "payroll_run_id", "provider", "file_uri", "checksum_sha256" ], "description": "A payroll export file for a payroll provider." }, "PayrollExportCreate": { "type": "object", "properties": { "payroll_run_id": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provider": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Target payroll provider.", "example": "payroll_csv" } }, "required": ["payroll_run_id", "provider"], "description": "Fields accepted when creating a PayrollExport." }, "EarningCodePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EarningCode" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EarningCode": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the earning code.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Earning code.", "example": "REG" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Earning name.", "example": "Regular Hours" }, "is_overtime": { "type": "boolean", "description": "Whether it is an overtime code.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "code", "name", "is_overtime" ], "description": "An earning code mapped to the payroll provider." }, "EarningCodeCreate": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Earning code.", "example": "REG" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Earning name.", "example": "Regular Hours" }, "is_overtime": { "type": "boolean", "description": "Whether it is an overtime code.", "example": false } }, "required": ["code", "name"], "description": "Fields accepted when creating a EarningCode." }, "EarningCodeUpdate": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Earning code.", "example": "REG" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Earning name.", "example": "Regular Hours" }, "is_overtime": { "type": "boolean", "description": "Whether it is an overtime code.", "example": false } }, "description": "Fields accepted when updating a EarningCode. Omitted fields are unchanged." }, "PerDiemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PerDiem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PerDiem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the per diem.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project worked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person paid; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "day": { "type": "string", "format": "date", "description": "Day the allowance covers.", "example": "2026-10-08" }, "amount_minor": { "type": ["integer", "null"], "description": "Allowance for the day. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 6500, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_id", "project_id", "membership_id", "day", "amount_minor", "currency_code" ], "description": "A per diem allowance for an engagement." }, "PerDiemCreate": { "type": "object", "properties": { "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project worked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person paid; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "day": { "type": "string", "format": "date", "description": "Day the allowance covers.", "example": "2026-10-08" }, "amount_minor": { "type": "integer", "minimum": 0, "description": "Allowance for the day. Integer minor units of the row's currency.", "example": 6500, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency.", "example": "USD" } }, "required": ["project_id", "day", "amount_minor", "currency_code"], "description": "Fields accepted when creating a PerDiem." }, "PerDiemUpdate": { "type": "object", "properties": { "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project worked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the person paid; null for external crew, who carry an engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "day": { "type": "string", "format": "date", "description": "Day the allowance covers.", "example": "2026-10-08" }, "amount_minor": { "type": "integer", "minimum": 0, "description": "Allowance for the day. Integer minor units of the row's currency.", "example": 6500, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency.", "example": "USD" } }, "description": "Fields accepted when updating a PerDiem. Omitted fields are unchanged." }, "TimeOffPolicyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeOffPolicy" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TimeOffPolicy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the time off policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Policy name.", "example": "Paid Time Off" }, "accrual_hours_per_period": { "type": ["number", "null"], "description": "Hours accrued per pay period.", "example": 3.08 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "accrual_hours_per_period" ], "description": "A time off policy." }, "TimeOffPolicyCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Policy name.", "example": "Paid Time Off" }, "accrual_hours_per_period": { "type": ["number", "null"], "description": "Hours accrued per pay period.", "example": 3.08 } }, "required": ["name"], "description": "Fields accepted when creating a TimeOffPolicy." }, "TimeOffPolicyUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Policy name.", "example": "Paid Time Off" }, "accrual_hours_per_period": { "type": ["number", "null"], "description": "Hours accrued per pay period.", "example": 3.08 } }, "description": "Fields accepted when updating a TimeOffPolicy. Omitted fields are unchanged." }, "TimeOffRequestPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeOffRequest" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TimeOffRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the time off request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_off_policy_id": { "type": "string", "format": "uuid", "description": "Identifier of the time off policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_on": { "type": "string", "format": "date", "description": "First day off.", "example": "2026-10-08" }, "ends_on": { "type": "string", "format": "date", "description": "Last day off.", "example": "2026-10-08" }, "time_off_state": { "type": "string", "enum": ["Proposed", "Approved", "Rejected", "Canceled"], "description": "Request state.", "example": "Proposed" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person requesting.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hours": { "type": "number", "description": "Hours requested.", "example": 16 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "time_off_policy_id", "starts_on", "ends_on", "time_off_state", "membership_id", "hours" ], "description": "A time off request. The submitter cannot approve it." }, "TimeOffRequestCreate": { "type": "object", "properties": { "time_off_policy_id": { "type": "string", "format": "uuid", "description": "Identifier of the time off policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_on": { "type": "string", "format": "date", "description": "First day off.", "example": "2026-10-08" }, "ends_on": { "type": "string", "format": "date", "description": "Last day off.", "example": "2026-10-08" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the person requesting.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hours": { "type": "number", "description": "Hours requested.", "example": 16 } }, "required": ["time_off_policy_id", "starts_on", "ends_on", "membership_id", "hours"], "description": "Fields accepted when creating a TimeOffRequest." }, "CredentialCategoryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialCategory" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CredentialCategory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Category name.", "example": "All Access" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Category code, unique per project.", "example": "ALL-ACCESS" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "project_id", "code" ], "description": "A credential category, such as All Access or Artist." }, "CredentialCategoryCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Category name.", "example": "All Access" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Category code, unique per project.", "example": "ALL-ACCESS" } }, "required": ["name", "project_id", "code"], "description": "Fields accepted when creating a CredentialCategory." }, "CredentialCategoryUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Category name.", "example": "All Access" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Category code, unique per project.", "example": "ALL-ACCESS" } }, "description": "Fields accepted when updating a CredentialCategory. Omitted fields are unchanged." }, "CredentialPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Credential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the credential.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "credential_category_id": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "issued_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the issuer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of validity.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of validity.", "example": "2026-10-08T14:30:00Z" }, "holder_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "credential_number": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Number printed on the badge, issued by the database.", "example": "CR-000123" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the credential was revoked.", "example": "2026-10-08T14:30:00Z" }, "revoked_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who revoked it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "credential_category_id", "engagement_id", "issued_by", "valid_from", "valid_to", "holder_person_id", "credential_number", "revoked_at", "revoked_by" ], "description": "An issued credential. Credentials cannot be self-issued." }, "CredentialCreate": { "type": "object", "properties": { "credential_category_id": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of validity.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of validity.", "example": "2026-10-08T14:30:00Z" }, "holder_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["credential_category_id", "holder_person_id"], "description": "Fields accepted when creating a Credential." }, "AccessGridEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccessGridEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AccessGridEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the access grid entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "credential_category_id": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "access_level_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Access level: a row of the canon Access Level enumeration.", "example": "ENM-036" }, "window_starts_at": { "type": "string", "format": "date-time", "description": "When access opens.", "example": "2026-10-08T14:30:00Z" }, "window_ends_at": { "type": "string", "format": "date-time", "description": "When access closes.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the category, copied from it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "zone_id", "credential_category_id", "access_level_enum_id", "window_starts_at", "window_ends_at", "project_id" ], "description": "A zone by credential category access rule with a time window." }, "AccessGridEntryCreate": { "type": "object", "properties": { "zone_id": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "credential_category_id": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "access_level_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Access level: a row of the canon Access Level enumeration.", "example": "ENM-036" }, "window_starts_at": { "type": "string", "format": "date-time", "description": "When access opens.", "example": "2026-10-08T14:30:00Z" }, "window_ends_at": { "type": "string", "format": "date-time", "description": "When access closes.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "zone_id", "credential_category_id", "access_level_enum_id", "window_starts_at", "window_ends_at" ], "description": "Fields accepted when creating a AccessGridEntry." }, "AccessGridEntryUpdate": { "type": "object", "properties": { "access_level_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Access level: a row of the canon Access Level enumeration.", "example": "ENM-036" }, "window_starts_at": { "type": "string", "format": "date-time", "description": "When access opens.", "example": "2026-10-08T14:30:00Z" }, "window_ends_at": { "type": "string", "format": "date-time", "description": "When access closes.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a AccessGridEntry. Omitted fields are unchanged." }, "AccessScanPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccessScan" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AccessScan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the access scan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "credential_id": { "type": "string", "format": "uuid", "description": "Identifier of the credential.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scanned_at": { "type": "string", "format": "date-time", "description": "When the scan happened.", "example": "2026-10-08T14:30:00Z" }, "result": { "type": "string", "enum": ["Granted", "Denied"], "description": "The database's decision for the scan.", "example": "Granted" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the credential, copied from it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "device_scanned_at": { "type": ["string", "null"], "format": "date-time", "description": "When the device scanned, for a scan made offline.", "example": "2026-10-08T14:30:00Z" }, "offline_result": { "type": ["string", "null"], "enum": ["Granted", "Denied", null], "description": "What the device decided offline.", "example": "Granted" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "zone_id", "credential_id", "scanned_at", "result", "project_id", "device_scanned_at", "offline_result" ], "description": "A credential scan at an access point, validated against the Access Grid." }, "AccessScanCreate": { "type": "object", "properties": { "zone_id": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "credential_id": { "type": "string", "format": "uuid", "description": "Identifier of the credential.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "device_scanned_at": { "type": ["string", "null"], "format": "date-time", "description": "When the device scanned, for a scan made offline.", "example": "2026-10-08T14:30:00Z" }, "offline_result": { "type": ["string", "null"], "enum": ["Granted", "Denied", null], "description": "What the device decided offline.", "example": "Granted" } }, "required": ["zone_id", "credential_id"], "description": "Fields accepted when creating a AccessScan." }, "CertificationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Certification" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Certification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Certification name.", "example": "OSHA 10" }, "issuing_body": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Body that issues the certification.", "example": "OSHA" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "issuing_body" ], "description": "A certification type, linked to canon compliance tags." }, "CertificationCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Certification name.", "example": "OSHA 10" }, "issuing_body": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Body that issues the certification.", "example": "OSHA" } }, "required": ["name", "issuing_body"], "description": "Fields accepted when creating a Certification." }, "CertificationUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Certification name.", "example": "OSHA 10" }, "issuing_body": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Body that issues the certification.", "example": "OSHA" } }, "description": "Fields accepted when updating a Certification. Omitted fields are unchanged." }, "CertificationHolderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CertificationHolder" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CertificationHolder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the certification holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "certification_id": { "type": "string", "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "expires_on": { "type": ["string", "null"], "format": "date", "description": "Expiry date.", "example": "2026-10-08" }, "verified_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the verifier.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "issued_on": { "type": "string", "format": "date", "description": "When the certification was issued.", "example": "2026-10-08" }, "public_verification_consented": { "type": "boolean", "description": "Whether the holder allows public verification by code.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "certification_id", "person_id", "expires_on", "verified_by", "issued_on", "public_verification_consented" ], "description": "A person's certification with evidence and expiry. It cannot be self-verified and verifies publicly only with consent." }, "CertificationHolderCreate": { "type": "object", "properties": { "certification_id": { "type": "string", "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "expires_on": { "type": ["string", "null"], "format": "date", "description": "Expiry date.", "example": "2026-10-08" }, "issued_on": { "type": "string", "format": "date", "description": "When the certification was issued.", "example": "2026-10-08" } }, "required": ["certification_id", "person_id", "issued_on"], "description": "Fields accepted when creating a CertificationHolder." }, "CertificationHolderUpdate": { "type": "object", "properties": { "expires_on": { "type": ["string", "null"], "format": "date", "description": "Expiry date.", "example": "2026-10-08" }, "issued_on": { "type": "string", "format": "date", "description": "When the certification was issued.", "example": "2026-10-08" }, "public_verification_consented": { "type": "boolean", "description": "Whether the holder allows public verification by code.", "example": false } }, "description": "Fields accepted when updating a CertificationHolder. Omitted fields are unchanged." }, "BudgetPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Budget": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Budget name.", "example": "Gate 3 Budget" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "is_baseline": { "type": "boolean", "description": "Whether this is the gate 3 baseline the final cost report compares against.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "name", "currency_code", "is_baseline" ], "description": "A project budget, structured as a chart of accounts by department and discipline." }, "BudgetCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Budget name.", "example": "Gate 3 Budget" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "is_baseline": { "type": "boolean", "description": "Whether this is the gate 3 baseline the final cost report compares against.", "example": false } }, "required": ["project_id", "name", "currency_code"], "description": "Fields accepted when creating a Budget." }, "BudgetUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Budget name.", "example": "Gate 3 Budget" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "is_baseline": { "type": "boolean", "description": "Whether this is the gate 3 baseline the final cost report compares against.", "example": false } }, "description": "Fields accepted when updating a Budget. Omitted fields are unchanged." }, "BudgetSummary": { "type": "object", "properties": { "budget_id": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "estimate": { "$ref": "#/components/schemas/MoneyTotal" }, "committed": { "$ref": "#/components/schemas/MoneyTotal" }, "actual": { "$ref": "#/components/schemas/MoneyTotal" }, "variance": { "$ref": "#/components/schemas/MoneyTotal" } }, "required": ["budget_id", "estimate", "committed", "actual", "variance"], "description": "Budget totals. Unpriced lines stay out of the sum and are counted." }, "BudgetLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "BudgetLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_id": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "xyz": { "$ref": "#/components/schemas/Xyz" }, "xyz_basis": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Basis for the XYZ tag.", "example": "Rented inventory" }, "line_type": { "$ref": "#/components/schemas/LineType" }, "grade_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Price band grade of the catalog element.", "example": "base" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": "number", "description": "Quantity; defaults to 1.", "example": 24 }, "unit_basis": { "$ref": "#/components/schemas/UnitCode" }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_total_minor": { "type": ["integer", "null"], "description": "Line total, generated from quantity and unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 108000, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the budget.", "example": 1 }, "phase_code": { "anyOf": [{ "$ref": "#/components/schemas/PhaseCode" }, { "type": "null" }] }, "tier_code": { "anyOf": [{ "$ref": "#/components/schemas/TierCode" }, { "type": "null" }] }, "actual_minor": { "type": ["integer", "null"], "description": "Approved and paid expenses posted to the line (app.budget_line_facts); null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 480000, "format": "int64" }, "account_code": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "budget_id", "cost_center_id", "urid", "xyz", "xyz_basis", "line_type", "grade_code", "element_id", "description", "quantity", "unit_basis", "unit_price_minor", "line_total_minor", "line_number", "phase_code", "tier_code", "actual_minor", "account_code" ], "description": "A budget line. A blank unit price is unpriced; zero is a claim. Fee and Contingency are line types." }, "LineType": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Budget line type from the budget template specification (Bible tab 34). Fee and Contingency are line types, not accounts.", "example": "Contingency" }, "ItemId": { "type": ["string", "null"], "pattern": "^[0-9]000\\.[0-9]{2}\\.[0-9]{2}-[A-Z0-9]+-[0-9]+$", "description": "Catalog item identifier `{URID}-{ORG}-{SEQ}` (Section 3.6).", "example": "4000.01.01-XPMS-001" }, "GlAccountCode": { "type": "string", "pattern": "^[0-9]{4}$", "description": "GL account code from the fixed chart in `xpms.dim_gl_account` (Section 3.11).", "example": "5400" }, "BudgetLineCreate": { "type": "object", "properties": { "budget_id": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "xyz": { "$ref": "#/components/schemas/Xyz" }, "xyz_basis": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Basis for the XYZ tag.", "example": "Rented inventory" }, "line_type": { "$ref": "#/components/schemas/LineType" }, "grade_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Price band grade of the catalog element.", "example": "base" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": "number", "description": "Quantity; defaults to 1.", "example": 24 }, "unit_basis": { "$ref": "#/components/schemas/UnitCode" }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the budget.", "example": 1 }, "phase_code": { "anyOf": [{ "$ref": "#/components/schemas/PhaseCode" }, { "type": "null" }] }, "tier_code": { "anyOf": [{ "$ref": "#/components/schemas/TierCode" }, { "type": "null" }] } }, "required": ["budget_id", "urid", "xyz", "xyz_basis", "description", "line_number"], "description": "Fields accepted when creating a BudgetLine." }, "BudgetLineUpdate": { "type": "object", "properties": { "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "xyz": { "$ref": "#/components/schemas/Xyz" }, "xyz_basis": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Basis for the XYZ tag.", "example": "Rented inventory" }, "line_type": { "$ref": "#/components/schemas/LineType" }, "grade_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Price band grade of the catalog element.", "example": "base" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": "number", "description": "Quantity; defaults to 1.", "example": 24 }, "unit_basis": { "$ref": "#/components/schemas/UnitCode" }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the budget.", "example": 1 }, "phase_code": { "anyOf": [{ "$ref": "#/components/schemas/PhaseCode" }, { "type": "null" }] }, "tier_code": { "anyOf": [{ "$ref": "#/components/schemas/TierCode" }, { "type": "null" }] } }, "description": "Fields accepted when updating a BudgetLine. Omitted fields are unchanged." }, "ExpensePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Expense" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Expense": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the expense.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "submitter_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who submitted the expense.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Expense description.", "example": "Gaffer tape, 12 rolls" }, "amount_minor": { "type": ["integer", "null"], "description": "Expense amount. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 14388, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "incurred_on": { "type": "string", "format": "date", "description": "When it was incurred.", "example": "2026-10-08" }, "expense_state": { "type": "string", "enum": ["Proposed", "Approved", "Rejected", "Paid", "Canceled"], "description": "Expense state.", "example": "Proposed" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty paid, when it is not the submitter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "budget_line_id", "submitter_person_id", "description", "amount_minor", "currency_code", "incurred_on", "expense_state", "counterparty_id" ], "description": "An expense. One expense posts to exactly one budget line; the submitter cannot approve it." }, "ExpenseCreate": { "type": "object", "properties": { "budget_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Expense description.", "example": "Gaffer tape, 12 rolls" }, "amount_minor": { "type": "integer", "minimum": 0, "description": "Expense amount. Integer minor units of the document currency.", "example": 14388, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "incurred_on": { "type": "string", "format": "date", "description": "When it was incurred.", "example": "2026-10-08" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty paid, when it is not the submitter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "budget_line_id", "description", "amount_minor", "currency_code", "incurred_on" ], "description": "Fields accepted when creating a Expense." }, "ExpenseUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Expense description.", "example": "Gaffer tape, 12 rolls" }, "amount_minor": { "type": "integer", "minimum": 0, "description": "Expense amount. Integer minor units of the document currency.", "example": 14388, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "incurred_on": { "type": "string", "format": "date", "description": "When it was incurred.", "example": "2026-10-08" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty paid, when it is not the submitter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Expense. Omitted fields are unchanged." }, "ContingencyDrawPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContingencyDraw" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ContingencyDraw": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the contingency draw.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "from_budget_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the contingency budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_budget_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the receiving budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "amount_minor": { "type": ["integer", "null"], "description": "Amount drawn. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 250000, "format": "int64" }, "reason": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why contingency is drawn.", "example": "Added wind bracing after the engineering review." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "from_budget_line_id", "to_budget_line_id", "amount_minor", "reason" ], "description": "A draw from a contingency line onto another budget line." }, "ContingencyDrawCreate": { "type": "object", "properties": { "from_budget_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the contingency budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_budget_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the receiving budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "amount_minor": { "type": "integer", "minimum": 1, "description": "Amount drawn. Integer minor units of the document currency.", "example": 250000, "format": "int64" }, "reason": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why contingency is drawn.", "example": "Added wind bracing after the engineering review." } }, "required": ["from_budget_line_id", "to_budget_line_id", "amount_minor", "reason"], "description": "Fields accepted when creating a ContingencyDraw." }, "ChangeOrderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeOrder" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ChangeOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Change order title.", "example": "Add Second Bar" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What changes and why.", "example": "Client added a second bar at the north lawn." }, "requested_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the requester.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "change_order_state": { "type": "string", "enum": ["Proposed", "Priced", "Approved", "Rejected", "Canceled"], "description": "Change order state.", "example": "Proposed" }, "total": { "$ref": "#/components/schemas/MoneyTotal" }, "budget_id": { "type": "string", "format": "uuid", "description": "Identifier of the budget the change order revises.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "change_order_number": { "type": "integer", "minimum": 1, "description": "Change order number within the project.", "example": 3 }, "order_type_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon change order type.", "example": "ENM-092" }, "priced_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who priced the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schedule_impact_days": { "type": ["integer", "null"], "minimum": -3650, "description": "Days the change moves the schedule; negative when it pulls it in, zero for none.", "example": 2 }, "client_impact": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Effect of the change on the client, as stated.", "example": "Adds a second stage to the run of show." }, "approved_at": { "type": ["string", "null"], "format": "date-time", "description": "When the change order moved to Approved, from its transition ledger.", "example": "2026-10-08T14:30:00Z" }, "approved_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who moved the change order to Approved.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "title", "reason", "requested_by", "change_order_state", "total", "budget_id", "change_order_number", "order_type_enum_id", "priced_by", "schedule_impact_days", "client_impact", "approved_at", "approved_by" ], "description": "A change order. An unpriced change order cannot be stored at zero; its requester cannot price and approve it alone." }, "ChangeOrderCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Change order title.", "example": "Add Second Bar" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What changes and why.", "example": "Client added a second bar at the north lawn." }, "budget_id": { "type": "string", "format": "uuid", "description": "Identifier of the budget the change order revises.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "order_type_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon change order type.", "example": "ENM-092" }, "schedule_impact_days": { "type": ["integer", "null"], "minimum": -3650, "description": "Days the change moves the schedule; negative when it pulls it in, zero for none.", "example": 2 }, "client_impact": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Effect of the change on the client, as stated.", "example": "Adds a second stage to the run of show." } }, "required": ["project_id", "title", "budget_id"], "description": "Fields accepted when creating a ChangeOrder." }, "ChangeOrderUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Change order title.", "example": "Add Second Bar" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What changes and why.", "example": "Client added a second bar at the north lawn." }, "order_type_enum_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon change order type.", "example": "ENM-092" }, "schedule_impact_days": { "type": ["integer", "null"], "minimum": -3650, "description": "Days the change moves the schedule; negative when it pulls it in, zero for none.", "example": 2 }, "client_impact": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Effect of the change on the client, as stated.", "example": "Adds a second stage to the run of show." } }, "description": "Fields accepted when updating a ChangeOrder. Omitted fields are unchanged." }, "ChangeOrderTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Proposed", "Priced", "Approved", "Rejected", "Canceled"], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Proposed" }, "to_state": { "type": "string", "enum": ["Proposed", "Priced", "Approved", "Rejected", "Canceled"], "description": "Target state.", "example": "Canceled" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "ChangeOrderLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeOrderLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ChangeOrderLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the change order line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "change_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the affected budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Bar build and dressing" }, "quantity": { "type": "number", "description": "Quantity; defaults to 1.", "example": 24 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price; null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1200000, "format": "int64" }, "is_no_cost": { "type": "boolean", "description": "Whether the line is deliberately free of charge.", "example": false }, "account_code": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center (dimension 1) of the budget line the change revises.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "change_order_id", "budget_line_id", "urid", "description", "quantity", "unit_price_minor", "is_no_cost", "account_code", "cost_center_id" ], "description": "A line of a change order." }, "ChangeOrderLineCreate": { "type": "object", "properties": { "change_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the affected budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Bar build and dressing" }, "quantity": { "type": "number", "description": "Quantity; defaults to 1.", "example": 24 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price; null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1200000, "format": "int64" }, "is_no_cost": { "type": "boolean", "description": "Whether the line is deliberately free of charge.", "example": false } }, "required": ["change_order_id", "urid", "description"], "description": "Fields accepted when creating a ChangeOrderLine." }, "ChangeOrderLineUpdate": { "type": "object", "properties": { "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the affected budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Bar build and dressing" }, "quantity": { "type": "number", "description": "Quantity; defaults to 1.", "example": 24 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price; null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1200000, "format": "int64" }, "is_no_cost": { "type": "boolean", "description": "Whether the line is deliberately free of charge.", "example": false } }, "description": "Fields accepted when updating a ChangeOrderLine. Omitted fields are unchanged." }, "AccountingPeriodPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountingPeriod" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AccountingPeriod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_on": { "type": "string", "format": "date", "description": "First day.", "example": "2026-10-08" }, "ends_on": { "type": "string", "format": "date", "description": "Last day.", "example": "2026-10-08" }, "period_state": { "$ref": "#/components/schemas/AccountingPeriodState" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "starts_on", "ends_on", "period_state" ], "description": "An accounting period. A closed period refuses postings; an open period cannot become Audited without passing through Closed." }, "AccountingPeriodState": { "type": "string", "enum": ["Open", "In Period", "Closing", "Closed", "Audited", "Archived"], "description": "Accounting period lifecycle. A closed period refuses postings.", "example": "Open" }, "AccountingPeriodCreate": { "type": "object", "properties": { "starts_on": { "type": "string", "format": "date", "description": "First day.", "example": "2026-10-08" }, "ends_on": { "type": "string", "format": "date", "description": "Last day.", "example": "2026-10-08" } }, "required": ["starts_on", "ends_on"], "description": "Fields accepted when creating a AccountingPeriod." }, "AccountingPeriodTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Open", "In Period", "Closing", "Closed", "Audited", "Archived"], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Closing" }, "to_state": { "type": "string", "enum": ["Open", "In Period", "Closing", "Closed", "Audited", "Archived"], "description": "Target state.", "example": "Closed" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "JournalEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "JournalEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the journal entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "accounting_period_id": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "entry_date": { "type": "string", "format": "date", "description": "Entry date.", "example": "2026-10-08" }, "memo": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Memo.", "example": "Reclass staging rental" }, "journal_state": { "type": "string", "enum": ["Proposed", "Posted", "Canceled"], "description": "Journal state.", "example": "Proposed" }, "posted_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was posted.", "example": "2026-10-08T14:30:00Z" }, "posted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the poster.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "prepared_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who prepared the entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "source_table": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Table of the document that produced the entry.", "example": "invoices" }, "source_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the document that produced the entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "accounting_period_id", "entry_date", "memo", "journal_state", "posted_at", "posted_by", "project_id", "prepared_by", "source_table", "source_id" ], "description": "A journal entry. The preparer cannot post it." }, "JournalEntryCreate": { "type": "object", "properties": { "accounting_period_id": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "entry_date": { "type": "string", "format": "date", "description": "Entry date.", "example": "2026-10-08" }, "memo": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Memo.", "example": "Reclass staging rental" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["accounting_period_id", "entry_date", "memo"], "description": "Fields accepted when creating a JournalEntry." }, "JournalEntryUpdate": { "type": "object", "properties": { "accounting_period_id": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "entry_date": { "type": "string", "format": "date", "description": "Entry date.", "example": "2026-10-08" }, "memo": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Memo.", "example": "Reclass staging rental" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a JournalEntry. Omitted fields are unchanged." }, "JournalLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JournalLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "JournalLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the journal line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "journal_entry_id": { "type": "string", "format": "uuid", "description": "Identifier of the journal entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_code": { "$ref": "#/components/schemas/GlAccountCode" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the entry.", "example": 1 }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Reclass staging rental" }, "debit_minor": { "type": ["integer", "null"], "description": "Debit amount; zero on a credit line. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 45000, "format": "int64" }, "credit_minor": { "type": ["integer", "null"], "description": "Credit amount; zero on a debit line. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 0, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field on the row.", "example": "USD" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "anyOf": [{ "$ref": "#/components/schemas/ItemId" }, { "type": "null" }] }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 24 }, "unit_basis": { "anyOf": [{ "$ref": "#/components/schemas/UnitCode" }, { "type": "null" }] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "journal_entry_id", "account_code", "cost_center_id", "urid", "line_number", "description", "debit_minor", "credit_minor", "currency_code", "counterparty_id", "element_id", "quantity", "unit_basis" ], "description": "A line of a journal entry." }, "JournalLineCreate": { "type": "object", "properties": { "journal_entry_id": { "type": "string", "format": "uuid", "description": "Identifier of the journal entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_code": { "$ref": "#/components/schemas/GlAccountCode" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the entry.", "example": 1 }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Reclass staging rental" }, "debit_minor": { "type": "integer", "minimum": 0, "description": "Debit amount; zero on a credit line. Integer minor units of the document currency.", "example": 45000, "format": "int64" }, "credit_minor": { "type": "integer", "minimum": 0, "description": "Credit amount; zero on a debit line. Integer minor units of the document currency.", "example": 0, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field on the row.", "example": "USD" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "anyOf": [{ "$ref": "#/components/schemas/ItemId" }, { "type": "null" }] }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 24 }, "unit_basis": { "anyOf": [{ "$ref": "#/components/schemas/UnitCode" }, { "type": "null" }] } }, "required": [ "journal_entry_id", "account_code", "line_number", "description", "currency_code" ], "description": "Fields accepted when creating a JournalLine." }, "JournalLineUpdate": { "type": "object", "properties": { "account_code": { "$ref": "#/components/schemas/GlAccountCode" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the entry.", "example": 1 }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Reclass staging rental" }, "debit_minor": { "type": "integer", "minimum": 0, "description": "Debit amount; zero on a credit line. Integer minor units of the document currency.", "example": 45000, "format": "int64" }, "credit_minor": { "type": "integer", "minimum": 0, "description": "Credit amount; zero on a debit line. Integer minor units of the document currency.", "example": 0, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field on the row.", "example": "USD" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "anyOf": [{ "$ref": "#/components/schemas/ItemId" }, { "type": "null" }] }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 24 }, "unit_basis": { "anyOf": [{ "$ref": "#/components/schemas/UnitCode" }, { "type": "null" }] } }, "description": "Fields accepted when updating a JournalLine. Omitted fields are unchanged." }, "PostingLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostingLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PostingLine": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "date": { "type": "string", "format": "date", "description": "Date the cost or revenue is recognized.", "example": "2026-10-08" }, "account_code": { "$ref": "#/components/schemas/GlAccountCode" }, "cost_center_id": { "anyOf": [{ "$ref": "#/components/schemas/CostCenterCode" }, { "type": "null" }] }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] }, "vendor_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the vendor organization; null for revenue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "item_id": { "$ref": "#/components/schemas/ItemId" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Sentence-case line description.", "example": "Stage deck rental for opening weekend." }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 24 }, "unit_basis": { "$ref": "#/components/schemas/UnitCode" }, "amount_minor": { "type": ["integer", "null"], "description": "Signed amount; negative for credits. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 108000, "format": "int64" }, "tax_type": { "$ref": "#/components/schemas/TaxType" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "external_ref": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Invoice, card transaction or record identifier.", "example": "INV-2026-0042" }, "line_state": { "$ref": "#/components/schemas/SharedState" }, "posting_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the posting line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "org_id", "date", "account_code", "cost_center_id", "urid", "vendor_id", "item_id", "description", "quantity", "unit_basis", "amount_minor", "tax_type", "currency", "external_ref", "line_state", "posting_line_id", "project_id" ], "description": "A Universal Posting Line (Bible tab 36): the one export shape, projected to every accounting platform." }, "CostCenterCode": { "type": "string", "pattern": "^CC-[A-Z0-9-]+$", "description": "Cost center identifier (GL dimension 1).", "example": "CC-VENUE" }, "TaxType": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Tax type from the Universal Posting Line specification (Bible tab 36).", "example": "Tax on Purchases" }, "SharedState": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "A value from the shared finance and commercial state vocabulary (Bible tab 37): the five core states plus declared domain extensions.", "example": "Committed" }, "PostingExport": { "type": "object", "properties": { "target": { "type": "string", "enum": ["xero", "quickbooks", "netsuite", "ramp"], "description": "Accounting platform the rows were projected to.", "example": "xero" }, "accounting_period_id": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period exported.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "filename": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Suggested file name.", "example": "upl-xero-2026-09-01-2026-09-30.csv" }, "content_type": { "type": "string", "enum": ["text/csv"], "description": "Media type.", "example": "text/csv" }, "header": { "type": "array", "items": { "type": "string" }, "description": "Column names after the canon mapping.", "example": ["Date", "Amount"] }, "row_count": { "type": "integer", "minimum": 0, "description": "Posting lines exported.", "example": 42 }, "csv": { "type": "string", "description": "RFC 4180 CSV with CRLF line endings: the header, then one row per line.", "example": "Date,AccountCode\r\n2026-09-14,5400\r\n" } }, "required": [ "target", "accounting_period_id", "filename", "content_type", "header", "row_count", "csv" ], "description": "Universal Posting Lines of one period projected to one platform through the canon mapping." }, "PostingExportRequest": { "type": "object", "properties": { "target": { "type": "string", "enum": ["xero", "quickbooks", "netsuite", "ramp"], "description": "Accounting platform the rows are projected to.", "example": "xero" }, "accounting_period_id": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["target", "accounting_period_id"], "description": "Request to export posting lines for a period." }, "InvoicePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "direction": { "type": "string", "enum": ["Payable", "Receivable"], "description": "Whether the invoice is owed or owing.", "example": "Payable" }, "invoice_number": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Invoice number.", "example": "INV-2026-0042" }, "issued_on": { "type": ["string", "null"], "format": "date", "description": "Issue date.", "example": "2026-10-08" }, "due_on": { "type": ["string", "null"], "format": "date", "description": "Due date.", "example": "2026-10-08" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "invoice_state": { "type": "string", "enum": ["Proposed", "Issued", "Approved", "Disputed", "Canceled"], "description": "Invoice state.", "example": "Proposed" }, "total": { "$ref": "#/components/schemas/MoneyTotal" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty billed or billing; null for an individual payee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payee_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person billing as an individual.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement the invoice bills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "direction", "invoice_number", "issued_on", "due_on", "currency_code", "invoice_state", "total", "counterparty_id", "payee_person_id", "engagement_id" ], "description": "An invoice issued or received. A closed production refuses new invoices." }, "InvoiceCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "direction": { "type": "string", "enum": ["Payable", "Receivable"], "description": "Whether the invoice is owed or owing.", "example": "Payable" }, "invoice_number": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Invoice number.", "example": "INV-2026-0042" }, "issued_on": { "type": ["string", "null"], "format": "date", "description": "Issue date.", "example": "2026-10-08" }, "due_on": { "type": ["string", "null"], "format": "date", "description": "Due date.", "example": "2026-10-08" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty billed or billing; null for an individual payee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement the invoice bills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["project_id", "direction", "currency_code"], "description": "Fields accepted when creating a Invoice." }, "InvoiceUpdate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "invoice_number": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Invoice number.", "example": "INV-2026-0042" }, "issued_on": { "type": ["string", "null"], "format": "date", "description": "Issue date.", "example": "2026-10-08" }, "due_on": { "type": ["string", "null"], "format": "date", "description": "Due date.", "example": "2026-10-08" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "description": "Fields accepted when updating a Invoice. Omitted fields are unchanged." }, "InvoiceTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Proposed", "Issued", "Approved", "Disputed", "Canceled"], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Proposed" }, "to_state": { "type": "string", "enum": ["Proposed", "Issued", "Approved", "Disputed", "Canceled"], "description": "Target state.", "example": "Canceled" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "InvoicePaymentRequest": { "type": "object", "properties": { "paid_on": { "type": "string", "format": "date", "description": "Date the money moved.", "example": "2026-10-08" }, "amount_minor": { "type": ["integer", "null"], "minimum": 1, "description": "Amount paid; the whole balance when null or omitted. Integer minor units of the document currency.", "example": 349000, "format": "int64" }, "reference": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Remittance reference from the bank or payout provider.", "example": "ACH-2027-0042" } }, "required": ["paid_on"], "description": "A payment made on the org's own rails, recorded against an invoice." }, "InvoiceLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InvoiceLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "invoice_id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 24 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the invoice.", "example": 1 }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tax_rate_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the tax rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "invoice_id", "description", "quantity", "unit_price_minor", "line_number", "budget_line_id", "tax_rate_id", "urid" ], "description": "A line of an invoice." }, "InvoiceLineCreate": { "type": "object", "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 24 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the invoice.", "example": 1 }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tax_rate_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the tax rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] } }, "required": ["invoice_id", "description", "line_number"], "description": "Fields accepted when creating a InvoiceLine." }, "InvoiceLineUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 24 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Line number within the invoice.", "example": 1 }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tax_rate_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the tax rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] } }, "description": "Fields accepted when updating a InvoiceLine. Omitted fields are unchanged." }, "PaymentApplicationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentApplication" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PaymentApplication": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the payment application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "invoice_id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "paid_on": { "type": "string", "format": "date", "description": "Payment date.", "example": "2026-10-08" }, "amount_minor": { "type": ["integer", "null"], "description": "Amount applied. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 108000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "external_ref": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Bank or card reference.", "example": "ACH-77812" }, "payment_id": { "type": "string", "format": "uuid", "description": "Identifier of the payment applied.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "invoice_id", "paid_on", "amount_minor", "currency_code", "external_ref", "payment_id" ], "description": "A payment applied to an invoice. Billed-to-date counts each payment once." }, "PaymentApplicationCreate": { "type": "object", "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "amount_minor": { "type": "integer", "minimum": 1, "description": "Amount applied. Integer minor units of the document currency.", "example": 108000, "format": "int64" }, "payment_id": { "type": "string", "format": "uuid", "description": "Identifier of the payment applied.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["invoice_id", "amount_minor", "payment_id"], "description": "Fields accepted when creating a PaymentApplication." }, "BillingDrawPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillingDraw" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "BillingDraw": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the billing draw.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "draw_number": { "type": "integer", "minimum": 1, "description": "Draw number within the project.", "example": 1 }, "period_end": { "type": "string", "format": "date", "description": "Last day the draw bills for.", "example": "2026-10-08" }, "amount_requested_minor": { "type": ["integer", "null"], "description": "Amount requested. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 5000000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field on the row.", "example": "USD" }, "invoice_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the receivable invoice of the draw.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "draw_number", "period_end", "amount_requested_minor", "currency_code", "invoice_id" ], "description": "A client billing draw against the project." }, "BillingDrawCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "draw_number": { "type": "integer", "minimum": 1, "description": "Draw number within the project.", "example": 1 }, "period_end": { "type": "string", "format": "date", "description": "Last day the draw bills for.", "example": "2026-10-08" }, "amount_requested_minor": { "type": "integer", "minimum": 0, "description": "Amount requested. Integer minor units of the document currency.", "example": 5000000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field on the row.", "example": "USD" } }, "required": [ "project_id", "draw_number", "period_end", "amount_requested_minor", "currency_code" ], "description": "Fields accepted when creating a BillingDraw." }, "BillingDrawUpdate": { "type": "object", "properties": { "draw_number": { "type": "integer", "minimum": 1, "description": "Draw number within the project.", "example": 1 }, "period_end": { "type": "string", "format": "date", "description": "Last day the draw bills for.", "example": "2026-10-08" }, "amount_requested_minor": { "type": "integer", "minimum": 0, "description": "Amount requested. Integer minor units of the document currency.", "example": 5000000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field on the row.", "example": "USD" } }, "description": "Fields accepted when updating a BillingDraw. Omitted fields are unchanged." }, "CostCenterPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenter" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CostCenter": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "code": { "$ref": "#/components/schemas/CostCenterCode" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Cost center name.", "example": "Event 01 Opening Weekend" }, "kind": { "type": "string", "enum": ["Standing", "Overhead", "Event"], "description": "Cost center kind.", "example": "Standing" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "template_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon cost center template.", "example": "CC-VENUE" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "code", "name", "kind", "scope_node_id", "template_id" ], "description": "A tenant cost center (GL dimension 1), created from canon templates or per event scope." }, "CostCenterCreate": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/CostCenterCode" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Cost center name.", "example": "Event 01 Opening Weekend" }, "kind": { "type": "string", "enum": ["Standing", "Overhead", "Event"], "description": "Cost center kind.", "example": "Standing" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["code", "name", "kind"], "description": "Fields accepted when creating a CostCenter." }, "CostCenterUpdate": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/CostCenterCode" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Cost center name.", "example": "Event 01 Opening Weekend" }, "kind": { "type": "string", "enum": ["Standing", "Overhead", "Event"], "description": "Cost center kind.", "example": "Standing" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a CostCenter. Omitted fields are unchanged." }, "TaxJurisdictionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxJurisdiction" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TaxJurisdiction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the tax jurisdiction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Tax jurisdiction name.", "example": "Florida Sales Tax" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "jurisdiction_id", "name" ], "description": "A tax jurisdiction the org collects or pays tax in." }, "TaxJurisdictionCreate": { "type": "object", "properties": { "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Tax jurisdiction name.", "example": "Florida Sales Tax" } }, "required": ["jurisdiction_id", "name"], "description": "Fields accepted when creating a TaxJurisdiction." }, "TaxJurisdictionUpdate": { "type": "object", "properties": { "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Tax jurisdiction name.", "example": "Florida Sales Tax" } }, "description": "Fields accepted when updating a TaxJurisdiction. Omitted fields are unchanged." }, "TaxRatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxRate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TaxRate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the tax rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tax_jurisdiction_id": { "type": "string", "format": "uuid", "description": "Identifier of the tax jurisdiction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_percent": { "type": "number", "description": "Rate in percent.", "example": 7 }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the rate applies.", "example": "2026-10-08" }, "tax_type": { "$ref": "#/components/schemas/TaxType" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "tax_jurisdiction_id", "rate_percent", "effective_from", "effective_to", "tax_type" ], "description": "A tax rate with its effective dates." }, "TaxRateCreate": { "type": "object", "properties": { "tax_jurisdiction_id": { "type": "string", "format": "uuid", "description": "Identifier of the tax jurisdiction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_percent": { "type": "number", "description": "Rate in percent.", "example": 7 }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the rate applies.", "example": "2026-10-08" }, "tax_type": { "$ref": "#/components/schemas/TaxType" } }, "required": ["tax_jurisdiction_id", "rate_percent", "effective_from", "tax_type"], "description": "Fields accepted when creating a TaxRate." }, "TaxRateUpdate": { "type": "object", "properties": { "rate_percent": { "type": "number", "description": "Rate in percent.", "example": 7 }, "effective_from": { "type": "string", "format": "date", "description": "First day the rate applies.", "example": "2026-10-08" }, "effective_to": { "type": ["string", "null"], "format": "date", "description": "Last day the rate applies.", "example": "2026-10-08" }, "tax_type": { "$ref": "#/components/schemas/TaxType" } }, "description": "Fields accepted when updating a TaxRate. Omitted fields are unchanged." }, "FxRatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FxRate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "FxRate": { "type": "object", "properties": { "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Base currency.", "example": "USD" }, "quote_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Quote currency.", "example": "USD" }, "rate": { "type": "number", "description": "Units of quote currency per unit of base currency.", "example": 0.9213 }, "effective_on": { "type": "string", "format": "date", "description": "Reference rate date.", "example": "2026-10-08" }, "source": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Rate source.", "example": "ECB" } }, "required": ["base_currency", "quote_currency", "rate", "effective_on", "source"], "description": "A daily reference exchange rate with its rate date and source." }, "PriceBookPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceBook" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PriceBook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the price book.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Price book name.", "example": "Standard Client Rates" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "currency_code" ], "description": "An org price book for selling items." }, "PriceBookCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Price book name.", "example": "Standard Client Rates" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": ["name", "currency_code"], "description": "Fields accepted when creating a PriceBook." }, "PriceBookUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Price book name.", "example": "Standard Client Rates" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "description": "Fields accepted when updating a PriceBook. Omitted fields are unchanged." }, "RfqPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rfq" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Rfq": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rfq.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "RFQ title.", "example": "Main Stage Audio Package" }, "rfq_state": { "type": "string", "enum": ["Proposed", "Issued", "Closed", "Awarded", "Canceled"], "description": "RFQ state.", "example": "Proposed" }, "rfq_number": { "type": "integer", "minimum": 1, "description": "Number from the project's display key sequence.", "example": 3 }, "responses_due_at": { "type": ["string", "null"], "format": "date-time", "description": "Deadline for responses; responses unseal when the RFQ closes.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "title", "rfq_state", "rfq_number", "responses_due_at" ], "description": "A request for quotation. Responses stay sealed until the deadline." }, "RfqCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "RFQ title.", "example": "Main Stage Audio Package" }, "responses_due_at": { "type": ["string", "null"], "format": "date-time", "description": "Deadline for responses; responses unseal when the RFQ closes.", "example": "2026-10-08T14:30:00Z" } }, "required": ["project_id", "title"], "description": "Fields accepted when creating a Rfq." }, "RfqUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "RFQ title.", "example": "Main Stage Audio Package" }, "responses_due_at": { "type": ["string", "null"], "format": "date-time", "description": "Deadline for responses; responses unseal when the RFQ closes.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a Rfq. Omitted fields are unchanged." }, "RFQTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Issued" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Closed" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "RfqInvitationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RfqInvitation" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RfqInvitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rfq invitation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rfq_id": { "type": "string", "format": "uuid", "description": "Identifier of the RFQ.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the invited vendor of the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "rfq_id", "vendor_id" ], "description": "An invitation to bid on an RFQ." }, "RfqInvitationCreate": { "type": "object", "properties": { "rfq_id": { "type": "string", "format": "uuid", "description": "Identifier of the RFQ.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the invited vendor of the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["rfq_id", "vendor_id"], "description": "Fields accepted when creating a RfqInvitation." }, "RfqResponsePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RfqResponse" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RfqResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rfq response.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rfq_id": { "type": "string", "format": "uuid", "description": "Identifier of the RFQ.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "submitted_at": { "type": ["string", "null"], "format": "date-time", "description": "When the response was submitted.", "example": "2026-10-08T14:30:00Z" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the responding vendor; must have been invited.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_until": { "type": ["string", "null"], "format": "date", "description": "Last day the quoted prices hold.", "example": "2026-10-08" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "rfq_id", "submitted_at", "vendor_id", "valid_until" ], "description": "A sealed RFQ response. A bidder sees only their own response." }, "RfqResponseReceipt": { "type": "object", "properties": { "rfq_response_id": { "type": "string", "format": "uuid", "description": "Identifier of the recorded response.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rfq_id": { "type": "string", "format": "uuid", "description": "Identifier of the RFQ.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the responding vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "line_count": { "type": "integer", "minimum": 1, "description": "Lines recorded.", "example": 3 }, "sealed": { "type": "boolean", "description": "True while the RFQ is not Closed: the response stays unreadable until it closes.", "example": true } }, "required": ["rfq_response_id", "rfq_id", "vendor_id", "line_count", "sealed"], "description": "A recorded RFQ response. The response itself stays sealed until the RFQ closes." }, "RfqResponseCreate": { "type": "object", "properties": { "rfq_id": { "type": "string", "format": "uuid", "description": "Identifier of the RFQ.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the responding vendor; must have been invited.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_until": { "type": ["string", "null"], "format": "date", "description": "Last day the quoted prices hold.", "example": "2026-10-08" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of every quoted line.", "example": "USD" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/RfqResponseQuotedLine" }, "minItems": 1, "description": "Lines quoted, at least one." } }, "required": ["rfq_id", "vendor_id", "currency_code", "lines"], "description": "Fields accepted when creating a RfqResponse." }, "RfqResponseQuotedLine": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Line array, 12 boxes per side" }, "element_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Catalog element quoted.", "example": "0000.01.01-XOS-001" }, "quantity": { "type": "number", "description": "Quantity; 1 when omitted.", "example": 2 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price quoted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1800000, "format": "int64" } }, "required": ["description", "unit_price_minor"], "description": "A line quoted in an RFQ response." }, "RfqResponseLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RfqResponseLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RfqResponseLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rfq response line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rfq_response_id": { "type": "string", "format": "uuid", "description": "Identifier of the RFQ response.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Line array, 12 boxes per side" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 1 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1800000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "element_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Catalog element quoted.", "example": "0000.01.01-XOS-001" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "rfq_response_id", "description", "quantity", "unit_price_minor", "currency_code", "element_id" ], "description": "A line of an RFQ response." }, "RfqResponseLineCreate": { "type": "object", "properties": { "rfq_response_id": { "type": "string", "format": "uuid", "description": "Identifier of the RFQ response.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Line array, 12 boxes per side" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 1 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1800000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "element_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Catalog element quoted.", "example": "0000.01.01-XOS-001" } }, "required": ["rfq_response_id", "description", "currency_code"], "description": "Fields accepted when creating a RfqResponseLine." }, "RfqResponseLineUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Line array, 12 boxes per side" }, "quantity": { "type": ["number", "null"], "description": "Quantity.", "example": 1 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1800000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "element_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Catalog element quoted.", "example": "0000.01.01-XOS-001" } }, "description": "Fields accepted when updating a RfqResponseLine. Omitted fields are unchanged." }, "PurchaseOrderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrder" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PurchaseOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "po_number": { "type": "integer", "minimum": 1, "description": "Number from the project's display key sequence.", "example": 7 }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "po_state": { "type": "string", "enum": ["Proposed", "Approved", "Sent", "Closed", "Canceled"], "description": "Purchase order state.", "example": "Proposed" }, "rfq_response_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the awarded RFQ response the order comes from.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "delivery_due_on": { "type": ["string", "null"], "format": "date", "description": "Date the order is due to be delivered.", "example": "2026-10-08" }, "payment_terms_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days after invoice the order is payable (Net 30 is 30).", "example": 30 }, "tax_minor": { "type": ["integer", "null"], "description": "Tax on the order. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4200, "format": "int64" }, "shipping_minor": { "type": ["integer", "null"], "description": "Shipping charged on the order. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 15000, "format": "int64" }, "sent_at": { "type": ["string", "null"], "format": "date-time", "description": "When the order moved to Sent (its issue date), from its transition ledger.", "example": "2026-10-08T14:30:00Z" }, "invoiced_minor": { "type": ["integer", "null"], "description": "Subtotal of the invoices matched to the order; null when none is matched or one is unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1250000, "format": "int64" }, "paid_minor": { "type": ["integer", "null"], "description": "Payments applied to the invoices matched to the order; null when none is matched. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 600000, "format": "int64" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "vendor_id", "po_number", "currency_code", "po_state", "rfq_response_id", "delivery_due_on", "payment_terms_days", "tax_minor", "shipping_minor", "sent_at", "invoiced_minor", "paid_minor" ], "description": "A purchase order. Its creator cannot approve it; spend authority applies inside the approval RPC." }, "PurchaseOrderCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "rfq_response_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the awarded RFQ response the order comes from.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "delivery_due_on": { "type": ["string", "null"], "format": "date", "description": "Date the order is due to be delivered.", "example": "2026-10-08" }, "payment_terms_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days after invoice the order is payable (Net 30 is 30).", "example": 30 }, "tax_minor": { "type": ["integer", "null"], "description": "Tax on the order. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4200, "format": "int64" }, "shipping_minor": { "type": ["integer", "null"], "description": "Shipping charged on the order. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 15000, "format": "int64" } }, "required": ["project_id", "vendor_id", "currency_code"], "description": "Fields accepted when creating a PurchaseOrder." }, "PurchaseOrderUpdate": { "type": "object", "properties": { "rfq_response_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the awarded RFQ response the order comes from.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "delivery_due_on": { "type": ["string", "null"], "format": "date", "description": "Date the order is due to be delivered.", "example": "2026-10-08" }, "payment_terms_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days after invoice the order is payable (Net 30 is 30).", "example": 30 }, "tax_minor": { "type": ["integer", "null"], "description": "Tax on the order. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4200, "format": "int64" }, "shipping_minor": { "type": ["integer", "null"], "description": "Shipping charged on the order. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 15000, "format": "int64" } }, "description": "Fields accepted when updating a PurchaseOrder. Omitted fields are unchanged." }, "PurchaseOrderApproveRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why approve the order.", "example": "Within budget." } }, "required": ["reason"], "description": "Request to approve the order." }, "PurchaseOrderTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Approved" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Sent" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "PoLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PoLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the po line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": "number", "description": "Quantity ordered.", "example": 24 }, "unit_basis": { "anyOf": [{ "$ref": "#/components/schemas/UnitCode" }, { "type": "null" }] }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Order of the line within the purchase order.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "purchase_order_id", "budget_line_id", "element_id", "description", "quantity", "unit_basis", "unit_price_minor", "line_number" ], "description": "A purchase order line." }, "PoLineCreate": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": "number", "description": "Quantity ordered.", "example": 24 }, "unit_basis": { "anyOf": [{ "$ref": "#/components/schemas/UnitCode" }, { "type": "null" }] }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Order of the line within the purchase order.", "example": 1 } }, "required": ["purchase_order_id", "description", "quantity"], "description": "Fields accepted when creating a PoLine." }, "PoLineUpdate": { "type": "object", "properties": { "budget_line_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Stage deck rental" }, "quantity": { "type": "number", "description": "Quantity ordered.", "example": 24 }, "unit_basis": { "anyOf": [{ "$ref": "#/components/schemas/UnitCode" }, { "type": "null" }] }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "line_number": { "type": "integer", "minimum": 1, "description": "Order of the line within the purchase order.", "example": 1 } }, "description": "Fields accepted when updating a PoLine. Omitted fields are unchanged." }, "PoChangeOrderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoChangeOrder" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PoChangeOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the po change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What changes.", "example": "Add six deck sections." }, "amount_delta_minor": { "type": ["integer", "null"], "description": "Change amount; null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 27000, "format": "int64" }, "po_change_order_state": { "type": "string", "enum": ["Proposed", "Approved", "Rejected", "Canceled"], "description": "PO change order state.", "example": "Proposed" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "purchase_order_id", "description", "amount_delta_minor", "po_change_order_state" ], "description": "A change to an issued purchase order." }, "PoChangeOrderCreate": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What changes.", "example": "Add six deck sections." }, "amount_delta_minor": { "type": ["integer", "null"], "description": "Change amount; null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 27000, "format": "int64" } }, "required": ["purchase_order_id", "description"], "description": "Fields accepted when creating a PoChangeOrder." }, "PoChangeOrderUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What changes.", "example": "Add six deck sections." }, "amount_delta_minor": { "type": ["integer", "null"], "description": "Change amount; null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 27000, "format": "int64" } }, "description": "Fields accepted when updating a PoChangeOrder. Omitted fields are unchanged." }, "PoChangeOrderApproveRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why approve the change.", "example": "Within budget." } }, "required": ["reason"], "description": "Request to approve the change." }, "PoChangeOrderRejectRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why reject the change.", "example": "Within budget." } }, "required": ["reason"], "description": "Request to reject the change." }, "GoodsReceiptPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GoodsReceipt" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "GoodsReceipt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the goods receipt.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "received_at": { "type": "string", "format": "date-time", "description": "When the goods arrived.", "example": "2026-10-08T14:30:00Z" }, "received_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the receiver.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Condition or exceptions noted.", "example": "Two cases dented." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "purchase_order_id", "received_at", "received_by", "note" ], "description": "A goods receipt against a purchase order. Duplicate receipts are refused." }, "GoodsReceiptCreate": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "received_at": { "type": "string", "format": "date-time", "description": "When the goods arrived.", "example": "2026-10-08T14:30:00Z" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Condition or exceptions noted.", "example": "Two cases dented." } }, "required": ["purchase_order_id"], "description": "Fields accepted when creating a GoodsReceipt." }, "ReceiptLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReceiptLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the receipt line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "goods_receipt_id": { "type": "string", "format": "uuid", "description": "Identifier of the goods receipt.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "po_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the PO line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "quantity_received": { "type": "number", "description": "Quantity received.", "example": 24 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "goods_receipt_id", "po_line_id", "quantity_received" ], "description": "A received quantity against a PO line." }, "ReceiptLineCreate": { "type": "object", "properties": { "goods_receipt_id": { "type": "string", "format": "uuid", "description": "Identifier of the goods receipt.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "po_line_id": { "type": "string", "format": "uuid", "description": "Identifier of the PO line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "quantity_received": { "type": "number", "description": "Quantity received.", "example": 24 } }, "required": ["goods_receipt_id", "po_line_id", "quantity_received"], "description": "Fields accepted when creating a ReceiptLine." }, "InvoiceMatchPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceMatch" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InvoiceMatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice match.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "invoice_id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "goods_receipt_id": { "type": "string", "format": "uuid", "description": "Identifier of the goods receipt.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "matched": { "type": "boolean", "description": "Whether all three agree.", "example": true }, "variance_minor": { "type": ["integer", "null"], "description": "Invoice total minus value received at order prices. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 2000, "format": "int64" }, "resolution_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Why a mismatch was accepted.", "example": "Freight surcharge agreed." }, "resolved_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who accepted the mismatch.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "resolved_at": { "type": ["string", "null"], "format": "date-time", "description": "When the mismatch was accepted.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "invoice_id", "purchase_order_id", "goods_receipt_id", "matched", "variance_minor", "resolution_note", "resolved_by", "resolved_at" ], "description": "A three-way match of PO, receipt and invoice. A mismatch is never auto-approved." }, "InvoiceMatchCreate": { "type": "object", "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purchase_order_id": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "goods_receipt_id": { "type": "string", "format": "uuid", "description": "Identifier of the goods receipt.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["invoice_id", "purchase_order_id", "goods_receipt_id"], "description": "Fields accepted when creating a InvoiceMatch." }, "InvoiceMatchResolveRequest": { "type": "object", "properties": { "resolution_note": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Why the difference is accepted.", "example": "Freight surcharge agreed by phone." } }, "required": ["resolution_note"], "description": "Request to accept a mismatch." }, "CatalogBindingPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogBinding" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CatalogBinding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the catalog binding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "item_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Item ID {URID}-{ORG}-{SEQ}, issued by the database.", "example": "0000.01.01-NORTHW-001" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Name the org uses for the item.", "example": "4x8 Stage Deck" }, "unit_basis": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Unit the item is bought in.", "example": "ea" }, "default_unit_price_minor": { "type": ["integer", "null"], "description": "Default unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the default price.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "element_id", "item_id", "name", "unit_basis", "default_unit_price_minor", "currency_code" ], "description": "A tenant item bound to a canon element." }, "CatalogBindingCreate": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Name the org uses for the item.", "example": "4x8 Stage Deck" }, "unit_basis": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Unit the item is bought in.", "example": "ea" }, "default_unit_price_minor": { "type": ["integer", "null"], "description": "Default unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the default price.", "example": "USD" } }, "required": ["element_id", "name"], "description": "Fields accepted when creating a CatalogBinding." }, "CatalogBindingUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Name the org uses for the item.", "example": "4x8 Stage Deck" }, "unit_basis": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Unit the item is bought in.", "example": "ea" }, "default_unit_price_minor": { "type": ["integer", "null"], "description": "Default unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the default price.", "example": "USD" } }, "description": "Fields accepted when updating a CatalogBinding. Omitted fields are unchanged." }, "VendorProductPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VendorProduct" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "VendorProduct": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor product.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "unit_price_minor": { "type": ["integer", "null"], "description": "List unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "vendor_sku": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The vendor's product identifier.", "example": "DSS-DECK-0408" }, "catalog_binding_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the catalog item the product fulfills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "lead_time_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days from order to delivery.", "example": 14 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "vendor_id", "element_id", "unit_price_minor", "currency_code", "vendor_sku", "catalog_binding_id", "lead_time_days" ], "description": "A product a vendor offers, optionally bound to an element." }, "VendorProductCreate": { "type": "object", "properties": { "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "unit_price_minor": { "type": ["integer", "null"], "description": "List unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "vendor_sku": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The vendor's product identifier.", "example": "DSS-DECK-0408" }, "catalog_binding_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the catalog item the product fulfills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "lead_time_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days from order to delivery.", "example": 14 } }, "required": ["vendor_id", "vendor_sku"], "description": "Fields accepted when creating a VendorProduct." }, "VendorProductUpdate": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "unit_price_minor": { "type": ["integer", "null"], "description": "List unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "vendor_sku": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The vendor's product identifier.", "example": "DSS-DECK-0408" }, "catalog_binding_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the catalog item the product fulfills.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "lead_time_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days from order to delivery.", "example": 14 } }, "description": "Fields accepted when updating a VendorProduct. Omitted fields are unchanged." }, "VendorPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Vendor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_type": { "anyOf": [{ "$ref": "#/components/schemas/CounterpartyType" }, { "type": "null" }] }, "vendor_state": { "type": "string", "enum": ["Prospect", "Onboarded", "Active", "Blocked", "Canceled"], "description": "Vendor state.", "example": "Prospect" }, "counterparty_id": { "type": "string", "format": "uuid", "description": "Identifier of the counterparty the vendor facet belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payment_terms_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days after invoice the vendor is paid.", "example": 30 }, "default_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency the vendor bills in by default.", "example": "USD" }, "default_account_code": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] }, "default_cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center (dimension 1) the vendor's costs post to unless a line says otherwise.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "bank_account_last4": { "type": ["string", "null"], "minLength": 1, "maxLength": 4, "pattern": "^[0-9]{4}$", "description": "Last four digits of the vendor's most recent bank account; null when none is on file.", "example": "4321" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "counterparty_type", "vendor_state", "counterparty_id", "payment_terms_days", "default_currency_code", "default_account_code", "default_cost_center_id", "bank_account_last4" ], "description": "An organization in the vendor relationship with this org, with its counterparty type." }, "CounterpartyType": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Counterparty type from `xpms.dim_counterparty_type`.", "example": "AV Integrator" }, "VendorCreate": { "type": "object", "properties": { "counterparty_id": { "type": "string", "format": "uuid", "description": "Identifier of the counterparty the vendor facet belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payment_terms_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days after invoice the vendor is paid.", "example": 30 }, "default_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency the vendor bills in by default.", "example": "USD" }, "default_account_code": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] }, "default_cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center (dimension 1) the vendor's costs post to unless a line says otherwise.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["counterparty_id"], "description": "Fields accepted when creating a Vendor." }, "VendorUpdate": { "type": "object", "properties": { "payment_terms_days": { "type": ["integer", "null"], "minimum": 0, "description": "Days after invoice the vendor is paid.", "example": 30 }, "default_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency the vendor bills in by default.", "example": "USD" }, "default_account_code": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] }, "default_cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center (dimension 1) the vendor's costs post to unless a line says otherwise.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Vendor. Omitted fields are unchanged." }, "VendorTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Prospect" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Onboarded" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "VendorClassPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VendorClass" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "VendorClass": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Vendor class name.", "example": "Staging" }, "std_vendor_class_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Standard Library vendor class adopted.", "example": "VC-001" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the class covers.", "example": "Staging rental houses." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "std_vendor_class_id", "description" ], "description": "An org vendor class, seeded from the Standard Library." }, "VendorClassCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Vendor class name.", "example": "Staging" }, "std_vendor_class_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Standard Library vendor class adopted.", "example": "VC-001" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the class covers.", "example": "Staging rental houses." } }, "required": ["name"], "description": "Fields accepted when creating a VendorClass." }, "VendorClassUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Vendor class name.", "example": "Staging" }, "std_vendor_class_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Standard Library vendor class adopted.", "example": "VC-001" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the class covers.", "example": "Staging rental houses." } }, "description": "Fields accepted when updating a VendorClass. Omitted fields are unchanged." }, "VendorClassAssignmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VendorClassAssignment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "VendorClassAssignment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_class_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "vendor_id", "vendor_class_id" ], "description": "A vendor placed in a vendor class." }, "VendorClassAssignmentCreate": { "type": "object", "properties": { "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_class_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["vendor_id", "vendor_class_id"], "description": "Fields accepted when creating a VendorClassAssignment." }, "PrequalificationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Prequalification" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Prequalification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the prequalification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_to": { "type": ["string", "null"], "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "scope_note": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What the vendor is prequalified for.", "example": "Rigging over 2,000 kg." }, "decision": { "type": ["string", "null"], "enum": ["Approved", "Rejected", null], "description": "Decision; null while pending.", "example": "Approved" }, "decided_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who decided.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was decided.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "vendor_id", "valid_to", "scope_note", "decision", "decided_by", "decided_at" ], "description": "A vendor prequalification." }, "PrequalificationCreate": { "type": "object", "properties": { "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_to": { "type": ["string", "null"], "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "scope_note": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What the vendor is prequalified for.", "example": "Rigging over 2,000 kg." } }, "required": ["vendor_id", "scope_note"], "description": "Fields accepted when creating a Prequalification." }, "PrequalificationUpdate": { "type": "object", "properties": { "valid_to": { "type": ["string", "null"], "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "scope_note": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What the vendor is prequalified for.", "example": "Rigging over 2,000 kg." } }, "description": "Fields accepted when updating a Prequalification. Omitted fields are unchanged." }, "PrequalificationDecideRequest": { "type": "object", "properties": { "decision": { "type": "string", "enum": ["Approved", "Rejected"], "description": "Decision.", "example": "Approved" }, "valid_to": { "type": "string", "format": "date", "description": "Last day an approval holds.", "example": "2027-12-31" } }, "required": ["decision"], "description": "Request to decide a prequalification." }, "InsuranceCertificatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsuranceCertificate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InsuranceCertificate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "coverage_type": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Coverage type.", "example": "General Liability" }, "coverage_limit_minor": { "type": ["integer", "null"], "description": "Each occurrence limit. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 100000000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "valid_to": { "type": "string", "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the insured vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insurer": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Insurance carrier.", "example": "Example Mutual" }, "policy_identifier": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Policy number.", "example": "GL-2027-0042" }, "valid_from": { "type": "string", "format": "date", "description": "First day of coverage.", "example": "2026-10-08" }, "document_uri": { "type": ["string", "null"], "format": "uri", "description": "Where the certificate document is stored.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "coverage_type", "coverage_limit_minor", "currency_code", "valid_to", "vendor_id", "insurer", "policy_identifier", "valid_from", "document_uri" ], "description": "A certificate of insurance naming the required additional insureds." }, "InsuranceCertificateCreate": { "type": "object", "properties": { "coverage_type": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Coverage type.", "example": "General Liability" }, "coverage_limit_minor": { "type": ["integer", "null"], "description": "Each occurrence limit. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 100000000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "valid_to": { "type": "string", "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the insured vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insurer": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Insurance carrier.", "example": "Example Mutual" }, "policy_identifier": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Policy number.", "example": "GL-2027-0042" }, "valid_from": { "type": "string", "format": "date", "description": "First day of coverage.", "example": "2026-10-08" }, "document_uri": { "type": ["string", "null"], "format": "uri", "description": "Where the certificate document is stored.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "required": [ "coverage_type", "valid_to", "vendor_id", "insurer", "policy_identifier", "valid_from" ], "description": "Fields accepted when creating a InsuranceCertificate." }, "InsuranceCertificateUpdate": { "type": "object", "properties": { "coverage_type": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Coverage type.", "example": "General Liability" }, "coverage_limit_minor": { "type": ["integer", "null"], "description": "Each occurrence limit. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 100000000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "valid_to": { "type": "string", "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the insured vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insurer": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Insurance carrier.", "example": "Example Mutual" }, "policy_identifier": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Policy number.", "example": "GL-2027-0042" }, "valid_from": { "type": "string", "format": "date", "description": "First day of coverage.", "example": "2026-10-08" }, "document_uri": { "type": ["string", "null"], "format": "uri", "description": "Where the certificate document is stored.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "description": "Fields accepted when updating a InsuranceCertificate. Omitted fields are unchanged." }, "VendorScorecardPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VendorScorecard" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "VendorScorecard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor scorecard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Internal notes.", "example": "On time; one damaged deck." }, "period_end": { "type": "string", "format": "date", "description": "Last day of the period scored.", "example": "2026-10-08" }, "quality_score": { "type": ["integer", "null"], "minimum": 1, "description": "Quality, 1 to 5; null when not scored.", "example": 4 }, "delivery_score": { "type": ["integer", "null"], "minimum": 1, "description": "On-time delivery, 1 to 5; null when not scored.", "example": 4 }, "safety_score": { "type": ["integer", "null"], "minimum": 1, "description": "Safety, 1 to 5; null when not scored.", "example": 4 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "vendor_id", "project_id", "note", "period_end", "quality_score", "delivery_score", "safety_score" ], "description": "A vendor scorecard for an engagement or project." }, "VendorScorecardCreate": { "type": "object", "properties": { "vendor_id": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Internal notes.", "example": "On time; one damaged deck." }, "period_end": { "type": "string", "format": "date", "description": "Last day of the period scored.", "example": "2026-10-08" }, "quality_score": { "type": ["integer", "null"], "minimum": 1, "description": "Quality, 1 to 5; null when not scored.", "example": 4 }, "delivery_score": { "type": ["integer", "null"], "minimum": 1, "description": "On-time delivery, 1 to 5; null when not scored.", "example": 4 }, "safety_score": { "type": ["integer", "null"], "minimum": 1, "description": "Safety, 1 to 5; null when not scored.", "example": 4 } }, "required": ["vendor_id", "period_end"], "description": "Fields accepted when creating a VendorScorecard." }, "VendorScorecardUpdate": { "type": "object", "properties": { "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Internal notes.", "example": "On time; one damaged deck." }, "period_end": { "type": "string", "format": "date", "description": "Last day of the period scored.", "example": "2026-10-08" }, "quality_score": { "type": ["integer", "null"], "minimum": 1, "description": "Quality, 1 to 5; null when not scored.", "example": 4 }, "delivery_score": { "type": ["integer", "null"], "minimum": 1, "description": "On-time delivery, 1 to 5; null when not scored.", "example": 4 }, "safety_score": { "type": ["integer", "null"], "minimum": 1, "description": "Safety, 1 to 5; null when not scored.", "example": 4 } }, "description": "Fields accepted when updating a VendorScorecard. Omitted fields are unchanged." }, "SponsorEntitlementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SponsorEntitlement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SponsorEntitlement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor entitlement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The entitlement.", "example": "Logo on the main stage scrims." }, "quantity": { "type": ["number", "null"], "description": "Committed quantity.", "example": 12 }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project the entitlement is delivered on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "due_on": { "type": ["string", "null"], "format": "date", "description": "When the entitlement is owed.", "example": "2026-10-08" }, "fulfilled_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was delivered; null while owed.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "description", "quantity", "project_id", "counterparty_id", "due_on", "fulfilled_at" ], "description": "A sponsor entitlement with fulfillment tracking." }, "SponsorEntitlementCreate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The entitlement.", "example": "Logo on the main stage scrims." }, "quantity": { "type": ["number", "null"], "description": "Committed quantity.", "example": 12 }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project the entitlement is delivered on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "due_on": { "type": ["string", "null"], "format": "date", "description": "When the entitlement is owed.", "example": "2026-10-08" } }, "required": ["description", "project_id", "counterparty_id"], "description": "Fields accepted when creating a SponsorEntitlement." }, "SponsorEntitlementUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The entitlement.", "example": "Logo on the main stage scrims." }, "quantity": { "type": ["number", "null"], "description": "Committed quantity.", "example": 12 }, "counterparty_id": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor counterparty.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "due_on": { "type": ["string", "null"], "format": "date", "description": "When the entitlement is owed.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a SponsorEntitlement. Omitted fields are unchanged." }, "InspectionTemplatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InspectionTemplate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InspectionTemplate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Template name.", "example": "Daily Stage Walk" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name" ], "description": "A template for an inspection walk." }, "InspectionTemplateCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Template name.", "example": "Daily Stage Walk" } }, "required": ["name"], "description": "Fields accepted when creating a InspectionTemplate." }, "InspectionTemplateUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Template name.", "example": "Daily Stage Walk" } }, "description": "Fields accepted when updating a InspectionTemplate. Omitted fields are unchanged." }, "InspectionItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InspectionItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InspectionItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspection_template_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Item order.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What to check.", "example": "Guardrails secured on all stage edges" }, "is_critical": { "type": "boolean", "description": "Whether a failure of this item stops use.", "example": true } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "inspection_template_id", "position", "prompt", "is_critical" ], "description": "An item of an inspection template." }, "InspectionItemCreate": { "type": "object", "properties": { "inspection_template_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Item order.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What to check.", "example": "Guardrails secured on all stage edges" }, "is_critical": { "type": "boolean", "description": "Whether a failure of this item stops use.", "example": true } }, "required": ["inspection_template_id", "position", "prompt"], "description": "Fields accepted when creating a InspectionItem." }, "InspectionItemUpdate": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "description": "Item order.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What to check.", "example": "Guardrails secured on all stage edges" }, "is_critical": { "type": "boolean", "description": "Whether a failure of this item stops use.", "example": true } }, "description": "Fields accepted when updating a InspectionItem. Omitted fields are unchanged." }, "InspectionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inspection" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Inspection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspection_template_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspector_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the inspector, from the session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "signed_off_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who signed off.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "signed_off_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was signed off.", "example": "2026-10-08T14:30:00Z" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Inspection record of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspected_at": { "type": "string", "format": "date-time", "description": "When the inspection took place.", "example": "2026-10-08T14:30:00Z" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "inspection_template_id", "inspector_person_id", "signed_off_by", "signed_off_at", "record_id", "inspected_at", "urid" ], "description": "An inspection performed from a template, with sign-off." }, "InspectionCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspection_template_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Inspection record of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspected_at": { "type": "string", "format": "date-time", "description": "When the inspection took place.", "example": "2026-10-08T14:30:00Z" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] } }, "required": ["project_id", "inspection_template_id"], "description": "Fields accepted when creating a Inspection." }, "InspectionUpdate": { "type": "object", "properties": { "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Inspection record of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] } }, "description": "Fields accepted when updating a Inspection. Omitted fields are unchanged." }, "InspectionResultPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InspectionResult" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InspectionResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection result.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspection_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspection_item_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes.", "example": "Left rail tightened on site." }, "result_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Row of the canon Inspection Result enumeration, for example ENM-084 (Failed).", "example": "ENM-084" }, "photo_uri": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Object name of the finding's photo in the field-media bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project, from the inspection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "inspection_id", "inspection_item_id", "note", "result_enum_id", "photo_uri", "project_id" ], "description": "Pass or fail for one inspection item." }, "InspectionResultCreate": { "type": "object", "properties": { "inspection_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "inspection_item_id": { "type": "string", "format": "uuid", "description": "Identifier of the inspection item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes.", "example": "Left rail tightened on site." }, "result_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Row of the canon Inspection Result enumeration, for example ENM-084 (Failed).", "example": "ENM-084" }, "photo_uri": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Object name of the finding's photo in the field-media bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg" } }, "required": ["inspection_id", "inspection_item_id", "result_enum_id"], "description": "Fields accepted when creating a InspectionResult." }, "InspectionResultUpdate": { "type": "object", "properties": { "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes.", "example": "Left rail tightened on site." }, "result_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Row of the canon Inspection Result enumeration, for example ENM-084 (Failed).", "example": "ENM-084" }, "photo_uri": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Object name of the finding's photo in the field-media bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg" } }, "description": "Fields accepted when updating a InspectionResult. Omitted fields are unchanged." }, "PermitRequirementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PermitRequirement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PermitRequirement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the permit requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Canon permit rule that triggered it.", "example": "Assembly occupancy" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "permit": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Permit required.", "example": "Certificate of occupancy" }, "ahj": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Authority having jurisdiction.", "example": "City Building and Fire" }, "permit_state": { "type": ["string", "null"], "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Permit state. A Title Case value from the lifecycle's database enum.", "example": "Proposed" }, "lead_time": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Lead time as canon states it.", "example": "4-6 wks" }, "trigger_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "What triggers the canon rule: threshold, project, element or condition.", "example": "project" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Permit record tracking the requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "rule", "jurisdiction_id", "permit", "ahj", "permit_state", "lead_time", "trigger_type", "record_id" ], "description": "A permit requirement generated by the jurisdiction permit engine. An unpopulated jurisdiction returns no answer." }, "PermitEngineRequest": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["project_id"] }, "PermitTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "The state the caller believes the row is in (compare-and-set).", "example": "Proposed" }, "to_state": { "type": "string", "pattern": "^[A-Z][A-Za-z]*( [A-Z][A-Za-z]*)*$", "description": "Target state.", "example": "Active" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "PermitTrackRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Record title; defaults to the canon permit text.", "example": "Special Events Permit" } } }, "IncidentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Incident": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short description.", "example": "Guest Fall Near North Bar" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When it happened.", "example": "2026-10-08T14:30:00Z" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 }, "severity_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Severity: a row of the canon Incident Severity enumeration.", "example": "ENM-097" }, "incident_number": { "type": "integer", "minimum": 1, "description": "Number from the project's display key sequence.", "example": 142 }, "incident_state": { "type": "string", "enum": ["Reported", "Dispatched", "Contained", "Closed"], "description": "Incident state.", "example": "Reported" }, "reported_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the reporter, from the session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "closed_signed_off_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who signed off the closure.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "accuracy_m": { "type": ["number", "null"], "description": "Horizontal accuracy of the location in meters.", "example": 8 }, "device_reported_at": { "type": ["string", "null"], "format": "date-time", "description": "When the reporter filed it on the device, for a report queued offline.", "example": "2026-10-08T14:30:00Z" }, "closed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the incident moved to Closed, from its transition ledger.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "title", "occurred_at", "zone_id", "latitude", "longitude", "severity_enum_id", "incident_number", "incident_state", "reported_by", "closed_signed_off_by", "accuracy_m", "device_reported_at", "closed_at" ], "description": "An incident with dispatch. A critical incident cannot be relabeled and closed in one statement; closing requires sign-off." }, "IncidentCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short description.", "example": "Guest Fall Near North Bar" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When it happened.", "example": "2026-10-08T14:30:00Z" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 }, "severity_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Severity: a row of the canon Incident Severity enumeration.", "example": "ENM-097" }, "accuracy_m": { "type": ["number", "null"], "description": "Horizontal accuracy of the location in meters.", "example": 8 }, "device_reported_at": { "type": ["string", "null"], "format": "date-time", "description": "When the reporter filed it on the device, for a report queued offline.", "example": "2026-10-08T14:30:00Z" } }, "required": ["project_id", "title", "occurred_at", "severity_enum_id"], "description": "Fields accepted when creating a Incident." }, "IncidentUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short description.", "example": "Guest Fall Near North Bar" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When it happened.", "example": "2026-10-08T14:30:00Z" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 }, "severity_enum_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Severity: a row of the canon Incident Severity enumeration.", "example": "ENM-097" }, "accuracy_m": { "type": ["number", "null"], "description": "Horizontal accuracy of the location in meters.", "example": 8 }, "device_reported_at": { "type": ["string", "null"], "format": "date-time", "description": "When the reporter filed it on the device, for a report queued offline.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a Incident. Omitted fields are unchanged." }, "IncidentTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Reported", "Dispatched", "Contained"], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Reported" }, "to_state": { "type": "string", "enum": ["Reported", "Dispatched", "Contained"], "description": "Target state.", "example": "Dispatched" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "IncidentCloseRequest": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Sign-off note.", "example": "Area inspected and safe." } }, "required": ["note"], "description": "Request to close an incident with sign-off." }, "IncidentPartyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentParty" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "IncidentParty": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the incident party.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the involved person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Role in the incident, or a description of an unknown person.", "example": "Witness" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "incident_id", "person_id", "description" ], "description": "A person involved in an incident." }, "IncidentPartyCreate": { "type": "object", "properties": { "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the involved person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Role in the incident, or a description of an unknown person.", "example": "Witness" } }, "required": ["incident_id", "description"], "description": "Fields accepted when creating a IncidentParty." }, "IncidentPartyUpdate": { "type": "object", "properties": { "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the involved person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Role in the incident, or a description of an unknown person.", "example": "Witness" } }, "description": "Fields accepted when updating a IncidentParty. Omitted fields are unchanged." }, "IncidentMediaPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentMedia" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "IncidentMedia": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the incident media.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "media_uri": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Where the photo or video is stored.", "example": "org/incidents/gate.jpg" }, "captured_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was captured.", "example": "2026-10-08T14:30:00Z" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project of the incident, copied from it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "incident_id", "media_uri", "captured_at", "project_id" ], "description": "A photo or file attached to an incident." }, "IncidentMediaCreate": { "type": "object", "properties": { "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "media_uri": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Where the photo or video is stored.", "example": "org/incidents/gate.jpg" }, "captured_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was captured.", "example": "2026-10-08T14:30:00Z" } }, "required": ["incident_id", "media_uri"], "description": "Fields accepted when creating a IncidentMedia." }, "DispatchAssignmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DispatchAssignment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DispatchAssignment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the dispatch assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "dispatched_at": { "type": "string", "format": "date-time", "description": "When the responder was dispatched.", "example": "2026-10-08T14:30:00Z" }, "arrived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the responder arrived.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the responder's membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "incident_id", "dispatched_at", "arrived_at", "membership_id" ], "description": "A responder dispatched to an incident." }, "DispatchAssignmentCreate": { "type": "object", "properties": { "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "arrived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the responder arrived.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the responder's membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["incident_id", "membership_id"], "description": "Fields accepted when creating a DispatchAssignment." }, "DispatchAssignmentUpdate": { "type": "object", "properties": { "arrived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the responder arrived.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a DispatchAssignment. Omitted fields are unchanged." }, "MedicalEncounterPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MedicalEncounter" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MedicalEncounter": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the medical encounter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "patient_description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Who was treated, without identifying medical detail.", "example": "Guest, adult" }, "treatment_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Treatment given. Restricted.", "example": "Abrasion to the left knee, cleaned and dressed." }, "disposition": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Outcome, such as released or transported.", "example": "Released" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "incident_id", "patient_description", "treatment_notes", "disposition" ], "description": "A medical encounter. Notes are Restricted, encrypted and never sent to a model." }, "MedicalEncounterCreate": { "type": "object", "properties": { "incident_id": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "patient_description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Who was treated, without identifying medical detail.", "example": "Guest, adult" }, "treatment_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Treatment given. Restricted.", "example": "Abrasion to the left knee, cleaned and dressed." }, "disposition": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Outcome, such as released or transported.", "example": "Released" } }, "required": ["incident_id", "patient_description"], "description": "Fields accepted when creating a MedicalEncounter." }, "MedicalEncounterUpdate": { "type": "object", "properties": { "patient_description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Who was treated, without identifying medical detail.", "example": "Guest, adult" }, "treatment_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Treatment given. Restricted.", "example": "Abrasion to the left knee, cleaned and dressed." }, "disposition": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Outcome, such as released or transported.", "example": "Released" } }, "description": "Fields accepted when updating a MedicalEncounter. Omitted fields are unchanged." }, "CrisisAlertPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrisisAlert" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CrisisAlert": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the crisis alert.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Alert message.", "example": "Weather hold: clear the north lawn." }, "issued_at": { "type": "string", "format": "date-time", "description": "When the alert was issued.", "example": "2026-10-08T14:30:00Z" }, "ended_at": { "type": ["string", "null"], "format": "date-time", "description": "When the alert was cleared.", "example": "2026-10-08T14:30:00Z" }, "emergency_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon emergency code announced.", "example": "CODE_RED" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "message", "issued_at", "ended_at", "emergency_code" ], "description": "A crisis alert broadcast to a project." }, "CrisisAlertCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Alert message.", "example": "Weather hold: clear the north lawn." }, "ended_at": { "type": ["string", "null"], "format": "date-time", "description": "When the alert was cleared.", "example": "2026-10-08T14:30:00Z" }, "emergency_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon emergency code announced.", "example": "CODE_RED" } }, "required": ["project_id", "message", "emergency_code"], "description": "Fields accepted when creating a CrisisAlert." }, "EmergencyCodePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmergencyCode" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EmergencyCode": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Code token.", "example": "CODE_RED" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Code word.", "example": "Code Red" }, "emergency": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The emergency the code announces.", "example": "Fire Emergency" }, "swatch": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Design token of the swatch.", "example": "ecode-red" }, "sort_order": { "type": "integer", "minimum": 1, "description": "Canon order.", "example": 1 } }, "required": ["code", "label", "emergency", "swatch", "sort_order"], "description": "An org emergency code, seeded from the Standard Library and listed in numeric order." }, "RadioChannelPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RadioChannel" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RadioChannel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the radio channel.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "channel_number": { "type": "integer", "minimum": 1, "description": "Channel number.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Channel name.", "example": "Production" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the channel covers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "channel_number", "name", "project_id", "zone_id" ], "description": "A radio channel in the org radio plan, listed in numeric order." }, "RadioChannelCreate": { "type": "object", "properties": { "channel_number": { "type": "integer", "minimum": 1, "description": "Channel number.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Channel name.", "example": "Production" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the channel covers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["channel_number", "name", "project_id"], "description": "Fields accepted when creating a RadioChannel." }, "RadioChannelUpdate": { "type": "object", "properties": { "channel_number": { "type": "integer", "minimum": 1, "description": "Channel number.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Channel name.", "example": "Production" }, "zone_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the zone the channel covers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a RadioChannel. Omitted fields are unchanged." }, "OpportunityPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Opportunity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "requisition_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the approved requisition the opportunity is published from; required to publish Contractor, Crew and Staff opportunities and fixed once published.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Opportunity title, Title Case.", "example": "Stagehands for Harborfront Load-In" }, "role_type": { "$ref": "#/components/schemas/ExternalRoleType" }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "cat_urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Description.", "example": "Six stagehands for a two-day load-in." }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_type": { "anyOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": "null" }] }, "visibility": { "$ref": "#/components/schemas/OpportunityVisibility" }, "opportunity_state": { "$ref": "#/components/schemas/OpportunityState" }, "jurisdiction_id": { "anyOf": [{ "$ref": "#/components/schemas/JurisdictionId" }, { "type": "null" }] }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work.", "example": "2026-10-08" }, "pay_min_minor": { "type": ["integer", "null"], "description": "Lower end of the posted pay range; null when not posted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 3500, "format": "int64" }, "pay_max_minor": { "type": ["integer", "null"], "description": "Upper end of the posted pay range; null when not posted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the posted pay.", "example": "USD" }, "deadline_at": { "type": ["string", "null"], "format": "date-time", "description": "Deadline for applications and bids. Bids stay sealed until it passes.", "example": "2026-10-08T14:30:00Z" }, "minimum_age": { "type": ["integer", "null"], "minimum": 16, "description": "Minimum age for the work, 16 or older (Section 14.9).", "example": 18 }, "is_remote": { "type": "boolean", "description": "Whether the work can be done remotely.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "requisition_id", "project_id", "scope_node_id", "title", "role_type", "role_code", "cat_urid", "description", "venue_id", "rate_type", "visibility", "opportunity_state", "jurisdiction_id", "starts_on", "ends_on", "pay_min_minor", "pay_max_minor", "currency_code", "deadline_at", "minimum_age", "is_remote" ], "description": "An opportunity published from an approved requisition. Without posted compensation it shows Rate on Request, never zero." }, "OpportunityVisibility": { "type": "string", "enum": ["Invited", "Pool", "Network", "Public"], "description": "Who can see an opportunity.", "example": "Pool" }, "OpportunityState": { "type": "string", "enum": [ "Draft", "Pending Approval", "Published", "Paused", "Filled", "Closed", "Canceled" ], "description": "Opportunity lifecycle state.", "example": "Published" }, "OpportunityCreate": { "type": "object", "properties": { "requisition_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the approved requisition the opportunity is published from; required to publish Contractor, Crew and Staff opportunities and fixed once published.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Opportunity title, Title Case.", "example": "Stagehands for Harborfront Load-In" }, "role_type": { "$ref": "#/components/schemas/ExternalRoleType" }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "cat_urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Description.", "example": "Six stagehands for a two-day load-in." }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_type": { "anyOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": "null" }] }, "visibility": { "$ref": "#/components/schemas/OpportunityVisibility" }, "jurisdiction_id": { "anyOf": [{ "$ref": "#/components/schemas/JurisdictionId" }, { "type": "null" }] }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work.", "example": "2026-10-08" }, "pay_min_minor": { "type": ["integer", "null"], "description": "Lower end of the posted pay range; null when not posted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 3500, "format": "int64" }, "pay_max_minor": { "type": ["integer", "null"], "description": "Upper end of the posted pay range; null when not posted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the posted pay.", "example": "USD" }, "deadline_at": { "type": ["string", "null"], "format": "date-time", "description": "Deadline for applications and bids. Bids stay sealed until it passes.", "example": "2026-10-08T14:30:00Z" }, "minimum_age": { "type": ["integer", "null"], "minimum": 16, "description": "Minimum age for the work, 16 or older (Section 14.9).", "example": 18 }, "is_remote": { "type": "boolean", "description": "Whether the work can be done remotely.", "example": false } }, "required": ["project_id", "title", "role_type"], "description": "Fields accepted when creating a Opportunity." }, "OpportunityUpdate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Opportunity title, Title Case.", "example": "Stagehands for Harborfront Load-In" }, "role_type": { "$ref": "#/components/schemas/ExternalRoleType" }, "role_code": { "allOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": ["string", "null"] }] }, "cat_urid": { "$ref": "#/components/schemas/UridAtAnyGrain" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Description.", "example": "Six stagehands for a two-day load-in." }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rate_type": { "allOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": ["string", "null"] }] }, "visibility": { "$ref": "#/components/schemas/OpportunityVisibility" }, "requisition_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the approved requisition the opportunity is published from; required to publish Contractor, Crew and Staff opportunities and fixed once published.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "jurisdiction_id": { "anyOf": [{ "$ref": "#/components/schemas/JurisdictionId" }, { "type": "null" }] }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work.", "example": "2026-10-08" }, "pay_min_minor": { "type": ["integer", "null"], "description": "Lower end of the posted pay range; null when not posted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 3500, "format": "int64" }, "pay_max_minor": { "type": ["integer", "null"], "description": "Upper end of the posted pay range; null when not posted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the posted pay.", "example": "USD" }, "deadline_at": { "type": ["string", "null"], "format": "date-time", "description": "Deadline for applications and bids. Bids stay sealed until it passes.", "example": "2026-10-08T14:30:00Z" }, "minimum_age": { "type": ["integer", "null"], "minimum": 16, "description": "Minimum age for the work, 16 or older (Section 14.9).", "example": 18 }, "is_remote": { "type": "boolean", "description": "Whether the work can be done remotely.", "example": false } }, "description": "Fields accepted when updating a Opportunity. Omitted fields are unchanged." }, "OpportunityTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": [ "Draft", "Pending Approval", "Published", "Paused", "Filled", "Closed", "Canceled" ], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Draft" }, "to_state": { "type": "string", "enum": [ "Draft", "Pending Approval", "Published", "Paused", "Filled", "Closed", "Canceled" ], "description": "Target state.", "example": "Pending Approval" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "OpportunityPositionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityPosition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OpportunityPosition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity position.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Position label, for example Rigger 2.", "example": "Rigger 2" }, "call_at": { "type": ["string", "null"], "format": "date-time", "description": "Call time.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "When the position's work ends.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "opportunity_id", "label", "call_at", "ends_at" ], "description": "A position within an opportunity." }, "OpportunityPositionCreate": { "type": "object", "properties": { "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Position label, for example Rigger 2.", "example": "Rigger 2" }, "call_at": { "type": ["string", "null"], "format": "date-time", "description": "Call time.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "When the position's work ends.", "example": "2026-10-08T14:30:00Z" } }, "required": ["opportunity_id", "label"], "description": "Fields accepted when creating a OpportunityPosition." }, "OpportunityPositionUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Position label, for example Rigger 2.", "example": "Rigger 2" }, "call_at": { "type": ["string", "null"], "format": "date-time", "description": "Call time.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": ["string", "null"], "format": "date-time", "description": "When the position's work ends.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a OpportunityPosition. Omitted fields are unchanged." }, "OpportunityRequirementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityRequirement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OpportunityRequirement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "certification_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insurance_minimum_minor": { "type": ["integer", "null"], "description": "Insurance minimum, when the requirement is insurance. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 100000000, "format": "int64" }, "requirement_kind": { "type": "string", "enum": ["Certification", "Insurance", "Equipment"], "description": "Kind of requirement.", "example": "Certification" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is required.", "example": "Rigging certification, current." }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the insurance minimum.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "opportunity_id", "certification_id", "insurance_minimum_minor", "requirement_kind", "description", "currency_code" ], "description": "A requirement of an opportunity: a certification through a canon compliance tag, insurance or equipment." }, "OpportunityRequirementCreate": { "type": "object", "properties": { "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "certification_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insurance_minimum_minor": { "type": ["integer", "null"], "description": "Insurance minimum, when the requirement is insurance. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 100000000, "format": "int64" }, "requirement_kind": { "type": "string", "enum": ["Certification", "Insurance", "Equipment"], "description": "Kind of requirement.", "example": "Certification" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is required.", "example": "Rigging certification, current." }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the insurance minimum.", "example": "USD" } }, "required": ["opportunity_id", "requirement_kind", "description"], "description": "Fields accepted when creating a OpportunityRequirement." }, "OpportunityRequirementUpdate": { "type": "object", "properties": { "certification_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insurance_minimum_minor": { "type": ["integer", "null"], "description": "Insurance minimum, when the requirement is insurance. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 100000000, "format": "int64" }, "requirement_kind": { "type": "string", "enum": ["Certification", "Insurance", "Equipment"], "description": "Kind of requirement.", "example": "Certification" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What is required.", "example": "Rigging certification, current." }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the insurance minimum.", "example": "USD" } }, "description": "Fields accepted when updating a OpportunityRequirement. Omitted fields are unchanged." }, "OpportunityQuestionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityQuestion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OpportunityQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Question order.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Question.", "example": "Have you worked a festival load-in before?" }, "required": { "type": "boolean", "description": "Whether an answer is required.", "example": true } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "opportunity_id", "position", "prompt", "required" ], "description": "An application question." }, "OpportunityQuestionCreate": { "type": "object", "properties": { "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Question order.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Question.", "example": "Have you worked a festival load-in before?" }, "required": { "type": "boolean", "description": "Whether an answer is required.", "example": true } }, "required": ["opportunity_id", "position", "prompt", "required"], "description": "Fields accepted when creating a OpportunityQuestion." }, "OpportunityQuestionUpdate": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "description": "Question order.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Question.", "example": "Have you worked a festival load-in before?" }, "required": { "type": "boolean", "description": "Whether an answer is required.", "example": true } }, "description": "Fields accepted when updating a OpportunityQuestion. Omitted fields are unchanged." }, "PayTransparencyRulePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayTransparencyRule" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PayTransparencyRule": { "type": "object", "properties": { "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "range_required": { "type": "boolean", "description": "Whether a pay range is required.", "example": true }, "effective_from": { "type": "string", "format": "date", "description": "First day the rule applies.", "example": "2026-10-08" } }, "required": ["jurisdiction_id", "range_required", "effective_from"], "description": "Where a pay range is legally required in a posting." }, "ApplicationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Application" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Application": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "profile_share_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the consented profile snapshot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "availability_confirmed": { "type": "boolean", "description": "Whether the applicant confirmed availability.", "example": true }, "application_state": { "$ref": "#/components/schemas/ApplicationState" }, "applicant_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the applying person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "applicant_organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the applying external account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "submitted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who submitted, set from the session: the applicant, their representative or an account administrator.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "cover_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the applicant.", "example": "Available for both show days." }, "proposed_fee_minor": { "type": ["integer", "null"], "description": "Fee the applicant proposes instead of the posted one (artists). Integer minor units of the resource currency; null means unpriced, never zero.", "example": 250000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the proposed fee.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "opportunity_id", "profile_share_id", "availability_confirmed", "application_state", "applicant_person_id", "applicant_organization_id", "submitted_by", "cover_note", "proposed_fee_minor", "currency_code" ], "description": "An application to an opportunity, with a consented profile snapshot." }, "ApplicationState": { "type": "string", "enum": [ "Submitted", "In Review", "Shortlisted", "Offered", "Accepted", "Declined", "Withdrawn", "Not Selected" ], "description": "Application lifecycle state.", "example": "Submitted" }, "ApplicationCreate": { "type": "object", "properties": { "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "profile_share_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the consented profile snapshot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "availability_confirmed": { "type": "boolean", "description": "Whether the applicant confirmed availability.", "example": true }, "applicant_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the applying person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "applicant_organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the applying external account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "cover_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the applicant.", "example": "Available for both show days." }, "proposed_fee_minor": { "type": ["integer", "null"], "description": "Fee the applicant proposes instead of the posted one (artists). Integer minor units of the resource currency; null means unpriced, never zero.", "example": 250000, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the proposed fee.", "example": "USD" } }, "required": ["opportunity_id"], "description": "Fields accepted when creating a Application." }, "ApplicationTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": [ "Submitted", "In Review", "Shortlisted", "Offered", "Accepted", "Declined", "Withdrawn", "Not Selected" ], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Submitted" }, "to_state": { "type": "string", "enum": [ "Submitted", "In Review", "Shortlisted", "Offered", "Accepted", "Declined", "Withdrawn", "Not Selected" ], "description": "Target state.", "example": "In Review" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "ApplicationAnswerPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnswer" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ApplicationAnswer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the application answer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_question_id": { "type": "string", "format": "uuid", "description": "Identifier of the question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "answer": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Answer.", "example": "Yes, three seasons of festival load-ins." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "application_id", "opportunity_question_id", "answer" ], "description": "An answer to an application question." }, "ApplicationAnswerCreate": { "type": "object", "properties": { "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_question_id": { "type": "string", "format": "uuid", "description": "Identifier of the question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "answer": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Answer.", "example": "Yes, three seasons of festival load-ins." } }, "required": ["application_id", "opportunity_question_id", "answer"], "description": "Fields accepted when creating a ApplicationAnswer." }, "BidPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bid" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Bid": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "total": { "$ref": "#/components/schemas/MoneyTotal" }, "sealed": { "type": "boolean", "description": "Whether the bid is still sealed.", "example": true }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of every line.", "example": "USD" }, "valid_until": { "type": ["string", "null"], "format": "date", "description": "Last day the bid holds.", "example": "2026-10-08" }, "submitted_at": { "type": "string", "format": "date-time", "description": "When the bid was submitted, set by the database.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "application_id", "total", "sealed", "currency_code", "valid_until", "submitted_at" ], "description": "A sealed line-item bid. A bidder never sees another bidder, and the org sees bids only after the deadline unless it holds `procurement.bid.unseal`." }, "BidCreate": { "type": "object", "properties": { "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of every line.", "example": "USD" }, "valid_until": { "type": ["string", "null"], "format": "date", "description": "Last day the bid holds.", "example": "2026-10-08" } }, "required": ["application_id", "currency_code"], "description": "Fields accepted when creating a Bid." }, "BidUpdate": { "type": "object", "properties": { "valid_until": { "type": ["string", "null"], "format": "date", "description": "Last day the bid holds.", "example": "2026-10-08" } }, "description": "Fields accepted when updating a Bid. Omitted fields are unchanged." }, "BidLinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BidLine" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "BidLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the bid line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "bid_id": { "type": "string", "format": "uuid", "description": "Identifier of the bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Line array rental" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Quantity; defaults to 1.", "example": 2 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1800000, "format": "int64" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "bid_id", "description", "quantity", "unit_price_minor", "currency" ], "description": "A line of a sealed bid." }, "BidLineCreate": { "type": "object", "properties": { "bid_id": { "type": "string", "format": "uuid", "description": "Identifier of the bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Line array rental" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Quantity; defaults to 1.", "example": 2 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1800000, "format": "int64" } }, "required": ["bid_id", "description"], "description": "Fields accepted when creating a BidLine." }, "BidLineUpdate": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Line description.", "example": "Line array rental" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Quantity; defaults to 1.", "example": 2 }, "unit_price_minor": { "type": ["integer", "null"], "description": "Unit price. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1800000, "format": "int64" } }, "description": "Fields accepted when updating a BidLine. Omitted fields are unchanged." }, "AgencySlatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgencySlate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AgencySlate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the agency slate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the agency application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the slated staff member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "application_id", "person_id" ], "description": "A named staff member on a staffing agency's slate." }, "AgencySlateCreate": { "type": "object", "properties": { "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the agency application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the slated staff member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["application_id", "person_id"], "description": "Fields accepted when creating a AgencySlate." }, "ShortlistPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shortlist" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Shortlist": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the shortlist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rank": { "type": ["integer", "null"], "minimum": 1, "description": "Rank on the shortlist.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "opportunity_id", "application_id", "rank" ], "description": "An application placed on the opportunity shortlist." }, "ShortlistCreate": { "type": "object", "properties": { "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rank": { "type": ["integer", "null"], "minimum": 1, "description": "Rank on the shortlist.", "example": 1 } }, "required": ["opportunity_id", "application_id"], "description": "Fields accepted when creating a Shortlist." }, "ShortlistUpdate": { "type": "object", "properties": { "rank": { "type": ["integer", "null"], "minimum": 1, "description": "Rank on the shortlist.", "example": 1 } }, "description": "Fields accepted when updating a Shortlist. Omitted fields are unchanged." }, "InterviewPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Interview" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Interview": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the interview.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "When it is scheduled.", "example": "2026-10-08T14:30:00Z" }, "interview_kind": { "type": "string", "enum": ["Interview", "Audition"], "description": "Interview or Audition.", "example": "Interview" }, "duration_minutes": { "type": "integer", "minimum": 1, "description": "Length in minutes.", "example": 30 }, "location_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Place or meeting link.", "example": "Production office, Hall B" }, "internal_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Internal note. Never visible externally.", "example": "Strong rigging resume." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "application_id", "scheduled_at", "interview_kind", "duration_minutes", "location_text", "internal_note" ], "description": "An interview or audition for an application." }, "InterviewCreate": { "type": "object", "properties": { "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "When it is scheduled.", "example": "2026-10-08T14:30:00Z" }, "interview_kind": { "type": "string", "enum": ["Interview", "Audition"], "description": "Interview or Audition.", "example": "Interview" }, "duration_minutes": { "type": "integer", "minimum": 1, "description": "Length in minutes.", "example": 30 }, "location_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Place or meeting link.", "example": "Production office, Hall B" }, "internal_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Internal note. Never visible externally.", "example": "Strong rigging resume." } }, "required": ["application_id", "scheduled_at", "interview_kind", "duration_minutes"], "description": "Fields accepted when creating a Interview." }, "InterviewUpdate": { "type": "object", "properties": { "scheduled_at": { "type": "string", "format": "date-time", "description": "When it is scheduled.", "example": "2026-10-08T14:30:00Z" }, "interview_kind": { "type": "string", "enum": ["Interview", "Audition"], "description": "Interview or Audition.", "example": "Interview" }, "duration_minutes": { "type": "integer", "minimum": 1, "description": "Length in minutes.", "example": 30 }, "location_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Place or meeting link.", "example": "Production office, Hall B" }, "internal_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Internal note. Never visible externally.", "example": "Strong rigging resume." } }, "description": "Fields accepted when updating a Interview. Omitted fields are unchanged." }, "EngagementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Engagement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Engagement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engaged person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engaged external account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "offer_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the accepted offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_type": { "$ref": "#/components/schemas/ExternalRoleType" }, "engagement_state": { "$ref": "#/components/schemas/EngagementState" }, "activated_at": { "type": ["string", "null"], "format": "date-time", "description": "When it became Active.", "example": "2026-10-08T14:30:00Z" }, "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "When it became Complete.", "example": "2026-10-08T14:30:00Z" }, "application_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the accepted application the engagement came from.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "worker_classification": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification, from xpms.worker_classification; null for Client and Sponsor engagements.", "example": "INDEPENDENT_CONTRACTOR" }, "pay_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pay basis; with the arrangement a permitted canon pair.", "example": "Day Rate" }, "arrangement": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Arrangement; with the pay basis a permitted canon pair.", "example": "Per Engagement" }, "start_date": { "type": "string", "format": "date", "description": "First day of the engagement; defaults to the offer's or the opportunity's.", "example": "2026-10-08" }, "end_date": { "type": ["string", "null"], "format": "date", "description": "Last day of the engagement; defaults to the offer's or the opportunity's.", "example": "2026-10-08" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the counterparty (vendor) the holder is engaged through; null when direct.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "person_id", "organization_id", "project_id", "offer_id", "role_type", "engagement_state", "activated_at", "completed_at", "application_id", "worker_classification", "pay_basis", "arrangement", "start_date", "end_date", "counterparty_id" ], "description": "An external relationship: a person or external account working for an org. It cannot become Active until every blocking onboarding item passes." }, "EngagementState": { "type": "string", "enum": ["Onboarding", "Blocked", "Active", "Closing", "Complete", "Canceled"], "description": "Engagement lifecycle state. Active requires every blocking onboarding item to pass.", "example": "Onboarding" }, "EngagementCreate": { "type": "object", "properties": { "application_id": { "type": "string", "format": "uuid", "description": "Identifier of the accepted application the engagement comes from.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "worker_classification": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Worker classification, from xpms.worker_classification.", "example": "INDEPENDENT_CONTRACTOR" }, "pay_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pay basis; with the arrangement a permitted canon pair.", "example": "Day Rate" }, "arrangement": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Arrangement; with the pay basis a permitted canon pair.", "example": "Per Engagement" }, "start_date": { "type": "string", "format": "date", "description": "First day of the engagement; defaults to the offer's or the opportunity's.", "example": "2026-10-08" }, "end_date": { "type": ["string", "null"], "format": "date", "description": "Last day of the engagement; defaults to the offer's or the opportunity's.", "example": "2026-10-08" } }, "required": ["application_id", "worker_classification"], "description": "Fields accepted when creating a Engagement." }, "EngagementTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Onboarding", "Blocked", "Active", "Closing", "Complete", "Canceled"], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Onboarding" }, "to_state": { "type": "string", "enum": ["Onboarding", "Blocked", "Active", "Closing", "Complete", "Canceled"], "description": "Target state.", "example": "Active" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "EngagementDocumentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EngagementDocument" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EngagementDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Statement of Work" }, "engagement_document_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Engagement-Document lifecycle state. A Title Case value from the lifecycle's database enum.", "example": "Proposed" }, "document_kind": { "type": "string", "enum": [ "Offer", "Agreement", "Statement of Work", "Non-Disclosure Agreement", "Rider", "Advance Packet", "Insurance Certificate", "Lien Waiver", "Settlement", "Proof of Performance", "Content Consent" ], "description": "Kind of document.", "example": "Offer" }, "expires_on": { "type": ["string", "null"], "format": "date", "description": "Last day the document is valid, for documents that expire.", "example": "2026-10-08" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_id", "document_id", "title", "engagement_document_state", "document_kind", "expires_on" ], "description": "A document in an engagement, under the canon Engagement-Document lifecycle." }, "EngagementDocumentCreate": { "type": "object", "properties": { "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Document title.", "example": "Statement of Work" }, "document_kind": { "type": "string", "enum": [ "Offer", "Agreement", "Statement of Work", "Non-Disclosure Agreement", "Rider", "Advance Packet", "Insurance Certificate", "Lien Waiver", "Settlement", "Proof of Performance", "Content Consent" ], "description": "Kind of document.", "example": "Offer" }, "expires_on": { "type": ["string", "null"], "format": "date", "description": "Last day the document is valid, for documents that expire.", "example": "2026-10-08" } }, "required": ["engagement_id", "title", "document_kind"], "description": "Fields accepted when creating a EngagementDocument." }, "EngagementDocumentTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "minLength": 1, "description": "The state the caller believes the row is in (compare-and-set).", "example": "Proposed" }, "to_state": { "type": "string", "minLength": 1, "description": "Target state.", "example": "Active" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "OnboardingRequirementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingRequirement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OnboardingRequirement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_type": { "anyOf": [{ "$ref": "#/components/schemas/ExternalRoleType" }, { "type": "null" }] }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "verification_method": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Verification method. A Title Case value from the lifecycle's database enum.", "example": "Reviewer" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Requirement name, for example Certificate of Insurance.", "example": "Certificate of Insurance" }, "item_kind": { "type": "string", "enum": [ "Document Upload", "Electronic Signature", "Form", "Certification", "Training", "Acknowledgment", "Background Check", "Tax Form", "Payout Details" ], "description": "Kind of onboarding item.", "example": "Document Upload" }, "is_blocking": { "type": "boolean", "description": "True when the engagement cannot become Active until the item passes.", "example": true }, "valid_for_days": { "type": ["integer", "null"], "minimum": 1, "description": "Days a verification stays valid; null when it does not expire.", "example": 365 }, "remind_days_before": { "type": ["integer", "null"], "minimum": 1, "description": "Days before expiry the party is reminded.", "example": 30 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "role_type", "jurisdiction_id", "verification_method", "name", "item_kind", "is_blocking", "valid_for_days", "remind_days_before" ], "description": "A requirement of the onboarding packet, by role type and jurisdiction." }, "OnboardingRequirementCreate": { "type": "object", "properties": { "role_type": { "anyOf": [{ "$ref": "#/components/schemas/ExternalRoleType" }, { "type": "null" }] }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "verification_method": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Verification method. A Title Case value from the lifecycle's database enum.", "example": "Reviewer" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Requirement name, for example Certificate of Insurance.", "example": "Certificate of Insurance" }, "item_kind": { "type": "string", "enum": [ "Document Upload", "Electronic Signature", "Form", "Certification", "Training", "Acknowledgment", "Background Check", "Tax Form", "Payout Details" ], "description": "Kind of onboarding item.", "example": "Document Upload" }, "is_blocking": { "type": "boolean", "description": "True when the engagement cannot become Active until the item passes.", "example": true }, "valid_for_days": { "type": ["integer", "null"], "minimum": 1, "description": "Days a verification stays valid; null when it does not expire.", "example": 365 }, "remind_days_before": { "type": ["integer", "null"], "minimum": 1, "description": "Days before expiry the party is reminded.", "example": 30 } }, "required": ["verification_method", "name", "item_kind"], "description": "Fields accepted when creating a OnboardingRequirement." }, "OnboardingRequirementUpdate": { "type": "object", "properties": { "role_type": { "anyOf": [{ "$ref": "#/components/schemas/ExternalRoleType" }, { "type": "null" }] }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "verification_method": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Verification method. A Title Case value from the lifecycle's database enum.", "example": "Reviewer" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Requirement name, for example Certificate of Insurance.", "example": "Certificate of Insurance" }, "item_kind": { "type": "string", "enum": [ "Document Upload", "Electronic Signature", "Form", "Certification", "Training", "Acknowledgment", "Background Check", "Tax Form", "Payout Details" ], "description": "Kind of onboarding item.", "example": "Document Upload" }, "is_blocking": { "type": "boolean", "description": "True when the engagement cannot become Active until the item passes.", "example": true }, "valid_for_days": { "type": ["integer", "null"], "minimum": 1, "description": "Days a verification stays valid; null when it does not expire.", "example": 365 }, "remind_days_before": { "type": ["integer", "null"], "minimum": 1, "description": "Days before expiry the party is reminded.", "example": 30 } }, "description": "Fields accepted when updating a OnboardingRequirement. Omitted fields are unchanged." }, "OnboardingItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OnboardingItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "onboarding_requirement_id": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the submitted document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "onboarding_item_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Item state. A Title Case value from the lifecycle's database enum.", "example": "In Review" }, "expires_on": { "type": ["string", "null"], "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "carried_over": { "type": "boolean", "description": "Whether a verified item carried over from an earlier engagement.", "example": false }, "submitted_at": { "type": ["string", "null"], "format": "date-time", "description": "When the engaged party submitted the item.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_id", "onboarding_requirement_id", "document_id", "onboarding_item_state", "expires_on", "carried_over", "submitted_at" ], "description": "One onboarding requirement instantiated for an engagement." }, "OnboardingItemCreate": { "type": "object", "properties": { "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "onboarding_requirement_id": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["engagement_id", "onboarding_requirement_id"], "description": "Fields accepted when creating a OnboardingItem." }, "OnboardingItemSubmitRequest": { "type": "object", "properties": { "document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the document of the org submitted for the item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "The document submitted with the item, if any." }, "OnboardingVerificationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingVerification" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OnboardingVerification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding verification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "onboarding_item_id": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "passed": { "type": "boolean", "description": "Whether the item passed.", "example": true }, "verified_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the verifier.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "verified_at": { "type": "string", "format": "date-time", "description": "When it was verified.", "example": "2026-10-08T14:30:00Z" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reviewer notes.", "example": "Name matches the tax form." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "onboarding_item_id", "passed", "verified_by", "verified_at", "notes" ], "description": "A verification decision on an onboarding item." }, "OnboardingVerificationCreate": { "type": "object", "properties": { "onboarding_item_id": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "passed": { "type": "boolean", "description": "Whether the item passed.", "example": true }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reviewer notes.", "example": "Name matches the tax form." } }, "required": ["onboarding_item_id", "passed"], "description": "Fields accepted when creating a OnboardingVerification." }, "TalentPoolPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TalentPool" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TalentPool": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the talent pool.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pool name.", "example": "Preferred Riggers" }, "pool_kind": { "type": "string", "enum": ["Talent", "Vendor"], "description": "Talent (people) or Vendor (external accounts).", "example": "Talent" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "pool_kind" ], "description": "A talent or vendor pool." }, "TalentPoolCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pool name.", "example": "Preferred Riggers" }, "pool_kind": { "type": "string", "enum": ["Talent", "Vendor"], "description": "Talent (people) or Vendor (external accounts).", "example": "Talent" } }, "required": ["name", "pool_kind"], "description": "Fields accepted when creating a TalentPool." }, "TalentPoolUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Pool name.", "example": "Preferred Riggers" } }, "description": "Fields accepted when updating a TalentPool. Omitted fields are unchanged." }, "PoolMemberPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoolMember" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PoolMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the pool member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "talent_pool_id": { "type": "string", "format": "uuid", "description": "Identifier of the pool.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "level": { "$ref": "#/components/schemas/PoolLevel" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reason, required for Do Not Engage.", "example": "Repeated no-shows." }, "review_on": { "type": ["string", "null"], "format": "date", "description": "Review date, required for Do Not Engage.", "example": "2026-10-08" }, "rehire_eligible": { "type": "boolean", "description": "Rehire eligibility.", "example": true } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "talent_pool_id", "person_id", "organization_id", "level", "reason", "review_on", "rehire_eligible" ], "description": "A pool member. Do Not Engage needs a reason and a review date and is never visible externally." }, "PoolLevel": { "type": "string", "enum": ["Preferred", "Approved", "Do Not Engage"], "description": "Talent or vendor pool level. Do Not Engage is internal only and needs a reason and review date.", "example": "Preferred" }, "PoolMemberCreate": { "type": "object", "properties": { "talent_pool_id": { "type": "string", "format": "uuid", "description": "Identifier of the pool.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "level": { "$ref": "#/components/schemas/PoolLevel" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reason, required for Do Not Engage.", "example": "Repeated no-shows." }, "review_on": { "type": ["string", "null"], "format": "date", "description": "Review date, required for Do Not Engage.", "example": "2026-10-08" }, "rehire_eligible": { "type": "boolean", "description": "Rehire eligibility.", "example": true } }, "required": ["talent_pool_id", "level", "rehire_eligible"], "description": "Fields accepted when creating a PoolMember." }, "PoolMemberUpdate": { "type": "object", "properties": { "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "level": { "$ref": "#/components/schemas/PoolLevel" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reason, required for Do Not Engage.", "example": "Repeated no-shows." }, "review_on": { "type": ["string", "null"], "format": "date", "description": "Review date, required for Do Not Engage.", "example": "2026-10-08" }, "rehire_eligible": { "type": "boolean", "description": "Rehire eligibility.", "example": true } }, "description": "Fields accepted when updating a PoolMember. Omitted fields are unchanged." }, "RatingPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rating" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Rating": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rating.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the completed engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rater_side": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Which side rated.", "example": "org" }, "score": { "type": "integer", "minimum": 1, "description": "Score from 1 to 5.", "example": 5 }, "comment": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Public comment.", "example": "Prepared, punctual and safe." }, "released_at": { "type": ["string", "null"], "format": "date-time", "description": "When both ratings were released.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_id", "rater_side", "score", "comment", "released_at" ], "description": "A two-sided rating from a completed engagement, released together or after 14 days." }, "RatingCreate": { "type": "object", "properties": { "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the completed engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rater_side": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Which side rated.", "example": "org" }, "score": { "type": "integer", "minimum": 1, "description": "Score from 1 to 5.", "example": 5 }, "comment": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Public comment.", "example": "Prepared, punctual and safe." } }, "required": ["engagement_id", "rater_side", "score"], "description": "Fields accepted when creating a Rating." }, "RatingReplyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RatingReply" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RatingReply": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the rating reply.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rating_id": { "type": "string", "format": "uuid", "description": "Identifier of the rating.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Reply.", "example": "Thank you, glad to work the series again." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "rating_id", "body" ], "description": "A public reply from the rated party." }, "RatingReplyCreate": { "type": "object", "properties": { "rating_id": { "type": "string", "format": "uuid", "description": "Identifier of the rating.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Reply.", "example": "Thank you, glad to work the series again." } }, "required": ["rating_id", "body"], "description": "Fields accepted when creating a RatingReply." }, "MarketplaceListingPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceListing" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MarketplaceListing": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the posting organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Opportunity title.", "example": "Stagehands for Harborfront Load-In" }, "role_type": { "$ref": "#/components/schemas/ExternalRoleType" }, "role_code": { "allOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": ["string", "null"] }] }, "venue_locality": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "City.", "example": "Miami" }, "rate_type": { "anyOf": [{ "$ref": "#/components/schemas/RateType" }, { "type": "null" }] }, "pay_min_minor": { "type": ["integer", "null"], "description": "Lowest posted rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 32000, "format": "int64" }, "pay_max_minor": { "type": ["integer", "null"], "description": "Highest posted rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 38000, "format": "int64" }, "distance_km": { "type": ["number", "null"], "description": "Distance from the search location.", "example": 12.4 }, "org_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Posting organization name.", "example": "Northwind Live" }, "org_verified": { "type": "boolean", "description": "True when the posting organization is verified.", "example": true }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Description of the work.", "example": "Load-in and show calls for six weekends." }, "cat_urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] }, "venue_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Venue name.", "example": "Harbor Lawn" }, "jurisdiction_id": { "anyOf": [{ "$ref": "#/components/schemas/JurisdictionId" }, { "type": "null" }] }, "starts_on": { "type": ["string", "null"], "format": "date", "description": "First day of the work.", "example": "2026-10-08" }, "ends_on": { "type": ["string", "null"], "format": "date", "description": "Last day of the work.", "example": "2026-10-08" }, "visibility": { "$ref": "#/components/schemas/OpportunityVisibility" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the posted pay; null when unposted.", "example": "USD" }, "rate_on_request": { "type": "boolean", "description": "True when no pay is posted: the listing shows Rate on Request.", "example": false }, "deadline_at": { "type": ["string", "null"], "format": "date-time", "description": "Deadline for applications and bids.", "example": "2026-10-08T14:30:00Z" }, "minimum_age": { "type": ["integer", "null"], "minimum": 16, "description": "Minimum age for the work.", "example": 18 }, "opportunity_state": { "$ref": "#/components/schemas/OpportunityState" }, "position_count": { "type": "integer", "minimum": 0, "description": "Number of open positions.", "example": 4 } }, "required": [ "id", "org_id", "title", "role_type", "role_code", "venue_locality", "rate_type", "pay_min_minor", "pay_max_minor", "distance_km", "org_name", "org_verified", "description", "cat_urid", "venue_name", "jurisdiction_id", "starts_on", "ends_on", "visibility", "currency_code", "rate_on_request", "deadline_at", "minimum_age", "opportunity_state", "position_count" ], "description": "A marketplace view of an opportunity the caller may see. Internal columns never appear. Unposted compensation reads Rate on Request." }, "SavedSearchPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedSearch" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SavedSearch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the saved search.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Search name.", "example": "Miami Rigging Calls" }, "alerts_enabled": { "type": "boolean", "description": "Whether alerts are sent by email and push.", "example": true }, "role_type": { "anyOf": [{ "$ref": "#/components/schemas/ExternalRoleType" }, { "type": "null" }] }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "cat_urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] }, "jurisdiction_id": { "anyOf": [{ "$ref": "#/components/schemas/JurisdictionId" }, { "type": "null" }] }, "starts_after": { "type": ["string", "null"], "format": "date", "description": "Earliest start date.", "example": "2026-10-08" }, "ends_before": { "type": ["string", "null"], "format": "date", "description": "Latest end date.", "example": "2026-10-08" }, "min_rate_minor": { "type": ["integer", "null"], "description": "Minimum posted pay. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 3500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the minimum pay.", "example": "USD" } }, "required": [ "id", "created_at", "updated_at", "person_id", "name", "alerts_enabled", "role_type", "role_code", "cat_urid", "jurisdiction_id", "starts_after", "ends_before", "min_rate_minor", "currency_code" ], "description": "A saved marketplace search that sends alerts." }, "SavedSearchCreate": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Search name.", "example": "Miami Rigging Calls" }, "alerts_enabled": { "type": "boolean", "description": "Whether alerts are sent by email and push.", "example": true }, "role_type": { "anyOf": [{ "$ref": "#/components/schemas/ExternalRoleType" }, { "type": "null" }] }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "cat_urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] }, "jurisdiction_id": { "anyOf": [{ "$ref": "#/components/schemas/JurisdictionId" }, { "type": "null" }] }, "starts_after": { "type": ["string", "null"], "format": "date", "description": "Earliest start date.", "example": "2026-10-08" }, "ends_before": { "type": ["string", "null"], "format": "date", "description": "Latest end date.", "example": "2026-10-08" }, "min_rate_minor": { "type": ["integer", "null"], "description": "Minimum posted pay. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 3500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the minimum pay.", "example": "USD" } }, "required": ["person_id", "name"], "description": "Fields accepted when creating a SavedSearch." }, "SavedSearchUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Search name.", "example": "Miami Rigging Calls" }, "alerts_enabled": { "type": "boolean", "description": "Whether alerts are sent by email and push.", "example": true }, "role_type": { "anyOf": [{ "$ref": "#/components/schemas/ExternalRoleType" }, { "type": "null" }] }, "role_code": { "anyOf": [{ "$ref": "#/components/schemas/RoleCode" }, { "type": "null" }] }, "cat_urid": { "anyOf": [{ "$ref": "#/components/schemas/UridAtAnyGrain" }, { "type": "null" }] }, "jurisdiction_id": { "anyOf": [{ "$ref": "#/components/schemas/JurisdictionId" }, { "type": "null" }] }, "starts_after": { "type": ["string", "null"], "format": "date", "description": "Earliest start date.", "example": "2026-10-08" }, "ends_before": { "type": ["string", "null"], "format": "date", "description": "Latest end date.", "example": "2026-10-08" }, "min_rate_minor": { "type": ["integer", "null"], "description": "Minimum posted pay. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 3500, "format": "int64" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the minimum pay.", "example": "USD" } }, "description": "Fields accepted when updating a SavedSearch. Omitted fields are unchanged." }, "OpportunityAlertPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityAlert" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OpportunityAlert": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity alert.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "saved_search_id": { "type": "string", "format": "uuid", "description": "Identifier of the saved search.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "delivered_at": { "type": ["string", "null"], "format": "date-time", "description": "When the alert was sent.", "example": "2026-10-08T14:30:00Z" }, "matched_at": { "type": "string", "format": "date-time", "description": "When the match was found.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "created_at", "updated_at", "saved_search_id", "opportunity_id", "delivered_at", "matched_at" ], "description": "An alert raised for a saved search." }, "ListingReportPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListingReport" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ListingReport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the listing report.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "reason": { "type": "string", "enum": [ "Illegal Content", "Discrimination", "Fraud", "Misleading Information", "Missing Pay Range", "Safety" ], "description": "Ground for the report.", "example": "Illegal Content" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the reported opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reporter_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person who reported, set from the session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "details": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the reporter saw.", "example": "The listing asks for an upfront fee." }, "reported_at": { "type": "string", "format": "date-time", "description": "When the report was made, set by the database.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "created_at", "updated_at", "reason", "opportunity_id", "reporter_person_id", "details", "reported_at" ], "description": "A report against a listing or profile, handled through notice and action." }, "ListingReportCreate": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "Illegal Content", "Discrimination", "Fraud", "Misleading Information", "Missing Pay Range", "Safety" ], "description": "Ground for the report.", "example": "Illegal Content" }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the reported opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "details": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the reporter saw.", "example": "The listing asks for an upfront fee." } }, "required": ["reason", "opportunity_id"], "description": "Fields accepted when creating a ListingReport." }, "ModerationActionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModerationAction" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ModerationAction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the moderation action.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "listing_report_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the listing report.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "action": { "type": "string", "enum": ["Removed", "Restricted", "Restored", "No Action"], "description": "Decision taken.", "example": "Removed" }, "statement_of_reasons": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Statement of reasons.", "example": "The listing requested a fee from applicants." }, "opportunity_id": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity decided on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_at": { "type": "string", "format": "date-time", "description": "When the decision was made.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "created_at", "updated_at", "listing_report_id", "action", "statement_of_reasons", "opportunity_id", "decided_at" ], "description": "A moderation decision with a statement of reasons sent to the affected party." }, "ProfileSharePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileShare" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProfileShare": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the profile share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the sharing person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external account sharing its company profile; null when a person shares their own.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shared_fields": { "type": "array", "items": { "type": "object", "properties": { "field_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "description": "Profile field key.", "example": "headline" }, "field_value": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Value shared; null when shared empty.", "example": "Head Rigger" } }, "required": ["field_key", "field_value"] }, "minItems": 1, "description": "Each shared field with the value at the time of sharing." }, "shared_at": { "type": "string", "format": "date-time", "description": "When the snapshot was taken.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When consent was revoked.", "example": "2026-10-08T14:30:00Z" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement the share serves; live updates flow only while it is open.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "created_at", "updated_at", "person_id", "organization_id", "shared_fields", "shared_at", "revoked_at", "engagement_id" ], "description": "A consent snapshot of profile fields shared with one org. Live updates stop on revoke after close." }, "ProfileShareCreate": { "type": "object", "properties": { "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the external account sharing its company profile; null when a person shares their own.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shared_fields": { "type": "array", "items": { "type": "object", "properties": { "field_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$", "description": "Profile field key.", "example": "headline" }, "field_value": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Value shared; null when shared empty.", "example": "Head Rigger" } }, "required": ["field_key", "field_value"] }, "minItems": 1, "description": "Each shared field with the value at the time of sharing." }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement the share serves; live updates flow only while it is open.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["shared_fields"], "description": "Fields accepted when creating a ProfileShare." }, "AvailabilityCalendarPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityCalendar" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AvailabilityCalendar": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the availability calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "visibility": { "type": "string", "enum": ["Private", "Shared on Application", "Public"], "description": "Who reads the calendar.", "example": "Private" } }, "required": ["id", "created_at", "updated_at", "person_id", "time_zone", "visibility"], "description": "A person's availability calendar." }, "AvailabilityCalendarCreate": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "visibility": { "type": "string", "enum": ["Private", "Shared on Application", "Public"], "description": "Who reads the calendar.", "example": "Private" } }, "required": ["person_id", "time_zone"], "description": "Fields accepted when creating a AvailabilityCalendar." }, "AvailabilityCalendarUpdate": { "type": "object", "properties": { "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "visibility": { "type": "string", "enum": ["Private", "Shared on Application", "Public"], "description": "Who reads the calendar.", "example": "Private" } }, "description": "Fields accepted when updating a AvailabilityCalendar. Omitted fields are unchanged." }, "AvailabilityBlockPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityBlock" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AvailabilityBlock": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the availability block.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "availability_calendar_id": { "type": "string", "format": "uuid", "description": "Identifier of the availability calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Block start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Block end.", "example": "2026-10-08T14:30:00Z" }, "availability_kind": { "type": "string", "enum": ["Available", "Unavailable", "Tentative"], "description": "Kind of block.", "example": "Available" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Private note of the owner.", "example": "Holding for a tour." } }, "required": [ "id", "created_at", "updated_at", "availability_calendar_id", "starts_at", "ends_at", "availability_kind", "note" ], "description": "A block of availability or unavailability." }, "AvailabilityBlockCreate": { "type": "object", "properties": { "availability_calendar_id": { "type": "string", "format": "uuid", "description": "Identifier of the availability calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Block start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Block end.", "example": "2026-10-08T14:30:00Z" }, "availability_kind": { "type": "string", "enum": ["Available", "Unavailable", "Tentative"], "description": "Kind of block.", "example": "Available" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Private note of the owner.", "example": "Holding for a tour." } }, "required": ["availability_calendar_id", "starts_at", "ends_at", "availability_kind"], "description": "Fields accepted when creating a AvailabilityBlock." }, "AvailabilityBlockUpdate": { "type": "object", "properties": { "starts_at": { "type": "string", "format": "date-time", "description": "Block start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "Block end.", "example": "2026-10-08T14:30:00Z" }, "availability_kind": { "type": "string", "enum": ["Available", "Unavailable", "Tentative"], "description": "Kind of block.", "example": "Available" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Private note of the owner.", "example": "Holding for a tour." } }, "description": "Fields accepted when updating a AvailabilityBlock. Omitted fields are unchanged." }, "EngagementThreadPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EngagementThread" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EngagementThread": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Thread subject.", "example": "Parking for Load-In" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_id", "subject" ], "description": "A message thread inside an engagement." }, "EngagementThreadCreate": { "type": "object", "properties": { "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Thread subject.", "example": "Parking for Load-In" } }, "required": ["engagement_id", "subject"], "description": "Fields accepted when creating a EngagementThread." }, "EngagementThreadUpdate": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Thread subject.", "example": "Parking for Load-In" } }, "description": "Fields accepted when updating a EngagementThread. Omitted fields are unchanged." }, "EngagementMessagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EngagementMessage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EngagementMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_thread_id": { "type": "string", "format": "uuid", "description": "Identifier of the thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Message body.", "example": "Use the north lot; passes are at the gate." }, "author_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the sender.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "sent_at": { "type": "string", "format": "date-time", "description": "When it was sent.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_thread_id", "body", "author_person_id", "sent_at" ], "description": "A message in an engagement thread." }, "EngagementMessageCreate": { "type": "object", "properties": { "engagement_thread_id": { "type": "string", "format": "uuid", "description": "Identifier of the thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Message body.", "example": "Use the north lot; passes are at the gate." } }, "required": ["engagement_thread_id", "body"], "description": "Fields accepted when creating a EngagementMessage." }, "TaxFormPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxForm" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TaxForm": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the tax form.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tin_last4": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Last four digits of the tax identifier.", "example": "6789" }, "foreign_performer_withholding": { "type": "boolean", "description": "Foreign performer withholding flag.", "example": false }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the payee person, set from the session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the payee external account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "form_kind": { "type": "string", "enum": ["W-9", "W-8BEN", "W-8BEN-E"], "description": "Tax form.", "example": "W-9" }, "signed_at": { "type": "string", "format": "date-time", "description": "When the payee signed the form, set by the database.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "tin_last4", "foreign_performer_withholding", "person_id", "organization_id", "form_kind", "signed_at" ], "description": "A tax form. Restricted and encrypted; only the last four digits of the identifier are ever displayed." }, "TaxFormCreate": { "type": "object", "properties": { "foreign_performer_withholding": { "type": "boolean", "description": "Foreign performer withholding flag.", "example": false }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the payee external account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "form_kind": { "type": "string", "enum": ["W-9", "W-8BEN", "W-8BEN-E"], "description": "Tax form.", "example": "W-9" }, "tax_identifier": { "type": "string", "minLength": 4, "maxLength": 64, "description": "Tax identifier. Write-only: it is encrypted and never returned.", "example": "123456789" } }, "required": ["form_kind", "tax_identifier"], "description": "Fields accepted when creating a TaxForm." }, "PayoutAccountPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutAccount" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PayoutAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the payout account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the payee person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the payee organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provider": { "type": "string", "enum": ["Stripe Connect", "Accounting System"], "description": "Payment provider.", "example": "Stripe Connect" }, "provider_account_reference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Provider account reference.", "example": "acct_1PqRsT" }, "account_last4": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Last four digits of the account.", "example": "4421" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "person_id", "organization_id", "provider", "provider_account_reference", "account_last4" ], "description": "Payout details held by the payment provider. XOS stores provider references only." }, "PayoutAccountCreate": { "type": "object", "properties": { "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the payee person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the payee organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provider": { "type": "string", "enum": ["Stripe Connect", "Accounting System"], "description": "Payment provider.", "example": "Stripe Connect" }, "provider_account_reference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Provider account reference.", "example": "acct_1PqRsT" } }, "required": ["provider", "provider_account_reference"], "description": "Fields accepted when creating a PayoutAccount." }, "BackgroundCheckPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackgroundCheck" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "BackgroundCheck": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the background check.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provider": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Background check provider.", "example": "checkr" }, "provider_reference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Provider reference.", "example": "chk_7c1a2b" }, "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the provider completed it.", "example": "2026-10-08T14:30:00Z" }, "result": { "type": "string", "enum": ["Pending", "Clear", "Consider", "Suspended", "Canceled"], "description": "Result as the provider reports it.", "example": "Pending" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_id", "provider", "provider_reference", "completed_at", "result" ], "description": "A background check result from the provider. The report itself is never stored." }, "BackgroundCheckCreate": { "type": "object", "properties": { "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provider": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Background check provider.", "example": "checkr" }, "provider_reference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Provider reference.", "example": "chk_7c1a2b" } }, "required": ["engagement_id", "provider_reference"], "description": "Fields accepted when creating a BackgroundCheck." }, "CanonDepartmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonDepartment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonDepartment": { "type": "object", "properties": { "dept_code": { "$ref": "#/components/schemas/DeptCode" }, "department": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Department name.", "example": "Environment" }, "source": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon source of the row.", "example": "canon" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Environment replaces the 3.0 label." }, "executive_lead": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Executive lead of the department.", "example": "Executive Producer" }, "core_function": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Core function of the department.", "example": "Governance, master project control & compliance" }, "scope": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Scope of the department.", "example": "Master operations & overall accountability" } }, "required": [ "dept_code", "department", "source", "note", "executive_lead", "core_function", "scope" ], "description": "A department class. Ten classes, always in numeric order." }, "DeptCode": { "type": "string", "pattern": "^[0-9]000$", "description": "Department class code from `xpms.dim_department` (Section 3.2).", "example": "4000" }, "CanonDisciplinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonDiscipline" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonDiscipline": { "type": "object", "properties": { "disc_code": { "$ref": "#/components/schemas/DiscCode" }, "dept_code": { "$ref": "#/components/schemas/DeptCode" }, "discipline": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Discipline name.", "example": "Executive Leadership & Strategy" }, "source": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon source of the row.", "example": "canon" } }, "required": ["disc_code", "dept_code", "discipline", "source"], "description": "A discipline within a department class." }, "DiscCode": { "type": "string", "pattern": "^[0-9]000\\.[0-9]{2}$", "description": "Discipline code `DDDD.DD` from `xpms.dim_discipline`. Canon holds .01 to .49; tenant extensions hold .50 to .99.", "example": "4000.01" }, "CanonCategoryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonCategory" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonCategory": { "type": "object", "properties": { "cat_urid": { "$ref": "#/components/schemas/Urid" }, "disc_code": { "$ref": "#/components/schemas/DiscCode" }, "category": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Category name.", "example": "Production Leadership" }, "source": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon source of the row.", "example": "canon" }, "xyz": { "anyOf": [{ "$ref": "#/components/schemas/Xyz" }, { "type": "null" }] } }, "required": ["cat_urid", "disc_code", "category", "source", "xyz"], "description": "A category, the finest URID grain." }, "CanonActPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonAct" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonAct": { "type": "object", "properties": { "ordinal": { "type": "integer", "minimum": 1, "description": "Act ordinal.", "example": 1 }, "act_code": { "$ref": "#/components/schemas/ActCode" }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, in sentence case.", "example": "Everything before money is committed." } }, "required": ["ordinal", "act_code", "definition"], "description": "An act: a presentation grouping of gates, never a control point." }, "ActCode": { "type": "string", "pattern": "^[A-Z]+$", "description": "Act from `xpms.dim_act`.", "example": "PLAN" }, "CanonPhasePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonPhase" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonPhase": { "type": "object", "properties": { "gate": { "type": "integer", "minimum": 1, "description": "Gate ordinal.", "example": 1 }, "phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "phase": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Phase name.", "example": "Scope" }, "act_code": { "$ref": "#/components/schemas/ActCode" }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, in sentence case.", "example": "What needs to happen." }, "gate_exit": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What must be true to pass the gate.", "example": "Go or no-go ratified." }, "is_redefined": { "type": "boolean", "description": "True when 4.0 kept the code but redefined the phase (Advance).", "example": false } }, "required": [ "gate", "phase_code", "phase", "act_code", "definition", "gate_exit", "is_redefined" ], "description": "A gated phase. Nine phases with fixed, append-only ordinals." }, "CanonGateCriterionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonGateCriterion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonGateCriterion": { "type": "object", "properties": { "gate": { "type": "integer", "minimum": 1, "description": "Gate ordinal.", "example": 1 }, "criterion_id": { "$ref": "#/components/schemas/CriterionId" }, "statement": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Criterion statement.", "example": "A budget envelope exists and is approved." }, "is_blocking": { "type": "boolean", "description": "Whether the criterion blocks the gate.", "example": true } }, "required": ["gate", "criterion_id", "statement", "is_blocking"], "description": "A gate criterion. Blocking criteria stop the gate transition in the database." }, "CanonTierPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonTier" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonTier": { "type": "object", "properties": { "tier_code": { "$ref": "#/components/schemas/TierCode" }, "tier": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Tier name.", "example": "Physical" } }, "required": ["tier_code", "tier"], "description": "A tier of experience. International is never a tier." }, "CanonTeamPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonTeam" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonTeam": { "type": "object", "properties": { "team_id": { "$ref": "#/components/schemas/TeamId" }, "team": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Team name.", "example": "Executive Leadership" }, "dept_code": { "$ref": "#/components/schemas/DeptCode" }, "workgroup_tag": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Workgroup tag.", "example": "FOH" }, "lead_role": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Lead role of the team.", "example": "Production Manager" }, "responsibilities": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "What the team is responsible for.", "example": "Front of house operations." } }, "required": [ "team_id", "team", "dept_code", "workgroup_tag", "lead_role", "responsibilities" ], "description": "A canon team: a tag that rolls up to a department, never a tree level." }, "CanonTagPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonTag" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonTag": { "type": "object", "properties": { "tag_id": { "$ref": "#/components/schemas/TagId" }, "tag_type": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Tag type.", "example": "Compliance" }, "tag": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Tag value.", "example": "OSHA" } }, "required": ["tag_id", "tag_type", "tag"], "description": "A sustainability or compliance tag." }, "TagId": { "type": "string", "pattern": "^TAG-[0-9]{3}$", "description": "Sustainability or compliance tag from `xpms.dim_tag`.", "example": "TAG-002" }, "CanonTouchpointPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonTouchpoint" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonTouchpoint": { "type": "object", "properties": { "touchpoint_id": { "$ref": "#/components/schemas/TouchpointId" }, "sense": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Sense the touchpoint addresses.", "example": "Architecture (Sight)" }, "brief_element": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Brief element.", "example": "Floor Plan" }, "category": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Touchpoint category.", "example": "Stage Configuration" }, "item": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Touchpoint item.", "example": "Ground-Level Stage" }, "base": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Base grade description.", "example": "Low-rise deck stage." }, "elevated": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Elevated grade description.", "example": "Deck stage with skirted fascia." }, "premium": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Premium grade description.", "example": "Custom-fabricated floor stage." }, "optional_upgrades": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Optional upgrades.", "example": "Stage-front lighting ribbon." } }, "required": [ "touchpoint_id", "sense", "brief_element", "category", "item", "base", "elevated", "premium", "optional_upgrades" ], "description": "A five-sense touchpoint with Base, Elevated and Premium grades." }, "TouchpointId": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{2}$", "description": "Five-sense touchpoint identifier from `xpms.dim_touchpoint`.", "example": "SGT-01" }, "CanonJurisdictionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonJurisdiction" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonJurisdiction": { "type": "object", "properties": { "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "level": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Jurisdiction level.", "example": "region" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "parent": { "$ref": "#/components/schemas/JurisdictionId" }, "unit_system": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Unit system.", "example": "imperial" }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "Default currency of the jurisdiction.", "example": "USD" }, "status": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Population status of the jurisdiction's rules.", "example": "populated" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Florida amendments to the model codes." } }, "required": [ "jurisdiction_id", "level", "country", "parent", "unit_system", "currency", "status", "note" ], "description": "A jurisdiction. An unpopulated jurisdiction returns no answer for permit and code questions." }, "CanonRegionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonRegion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonRegion": { "type": "object", "properties": { "region_code": { "$ref": "#/components/schemas/RegionCode" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Region name.", "example": "Miami and South Florida" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of the region.", "example": "USD" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Basis region." } }, "required": ["region_code", "name", "jurisdiction_id", "currency_code", "note"], "description": "A cost region. Only ratified multipliers answer; others refuse." }, "CanonRegionMultiplierPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonRegionMultiplier" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonRegionMultiplier": { "type": "object", "properties": { "region_code": { "$ref": "#/components/schemas/RegionCode" }, "cost_multiplier": { "type": "number", "description": "Cost multiplier.", "example": 1 }, "is_basis": { "type": "boolean", "description": "True for the basis region the price bands were sourced in.", "example": false } }, "required": ["region_code", "cost_multiplier", "is_basis"], "description": "A cost multiplier for a region, with its ratification." }, "CanonEscalationIndexPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonEscalationIndex" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonEscalationIndex": { "type": "object", "properties": { "index_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Index identifier.", "example": "BLS-CPI-U" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Index name.", "example": "US CPI-U, all items" }, "applies_to": { "$ref": "#/components/schemas/JurisdictionId" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Default escalation basis." } }, "required": ["index_id", "name", "applies_to", "note"], "description": "A price escalation index." }, "CanonStalenessPolicyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonStalenessPolicy" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonStalenessPolicy": { "type": "object", "properties": { "age_months_gte": { "type": "integer", "minimum": 0, "description": "Age in months at which the action applies.", "example": 12 }, "action": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Action taken at that age.", "example": "degrade" }, "detail": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Detail of the action.", "example": "Degrade one step." } }, "required": ["age_months_gte", "action", "detail"], "description": "A staleness step: how a price band degrades with age." }, "CanonPermitRulePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonPermitRule" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonPermitRule": { "type": "object", "properties": { "rule": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Rule name.", "example": "Assembly occupancy" }, "trigger_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "What triggers the rule.", "example": "threshold" }, "condition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Trigger condition.", "example": "Occupant load of 50 or more." }, "permit": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Permit required.", "example": "Certificate of occupancy" }, "ahj": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Authority having jurisdiction.", "example": "City Building and Fire" }, "lead_time": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Typical lead time.", "example": "4-8 wks" }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Triggered by occupant load." } }, "required": [ "rule", "trigger_type", "condition", "permit", "ahj", "lead_time", "jurisdiction_id", "provenance", "note" ], "description": "A permit rule of the jurisdiction permit engine." }, "Provenance": { "type": "string", "pattern": "^[a-z]+$", "description": "Provenance from `xpms.dim_provenance` (Section 3.8); a lower rank never overwrites a higher one.", "example": "operator" }, "CanonMetricPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonMetric" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonMetric": { "type": "object", "properties": { "domain": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Metric domain.", "example": "capacity" }, "item": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Metric item.", "example": "Stage or performance area" }, "value_numeric": { "type": ["number", "null"], "description": "Metric value.", "example": 15 }, "qualifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Qualifier of the value: the code section or modelling note it follows.", "example": "IBC 1005.3.2 - 0.2 in per occupant" }, "source": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Source of the value.", "example": "IBC 1004.5" }, "is_code_derived": { "type": "boolean", "description": "Whether the value comes from a code.", "example": true }, "jurisdiction_id": { "$ref": "#/components/schemas/JurisdictionId" }, "is_jurisdiction_neutral": { "type": "boolean", "description": "Whether the value holds in every jurisdiction.", "example": false }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "value_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Value as text, when canon states it in words.", "example": "Per show day" } }, "required": [ "domain", "item", "value_numeric", "qualifier", "source", "is_code_derived", "jurisdiction_id", "is_jurisdiction_neutral", "provenance", "value_text" ], "description": "A metric, often code-derived and jurisdiction-bound." }, "CanonIdentifierClassPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonIdentifierClass" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonIdentifierClass": { "type": "object", "properties": { "class": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Identifier class.", "example": "identifier" }, "issued_by": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Who issues it.", "example": "An external authority" }, "scope": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Where it is unique.", "example": "Global" }, "is_mutable": { "type": "boolean", "description": "Whether it may change.", "example": false }, "rule": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Rule.", "example": "Recorded and validated, never minted." }, "examples": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Examples.", "example": "GTIN, MPN, UNSPSC" } }, "required": ["class", "issued_by", "scope", "is_mutable", "rule", "examples"], "description": "Identifier grammar: identifier, code or token (Section 3.6)." }, "CanonGrainPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonGrain" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonGrain": { "type": "object", "properties": { "grain": { "$ref": "#/components/schemas/GrainCode" }, "counts": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What it counts.", "example": "One physical thing" }, "identified_by": { "type": "string", "minLength": 1, "maxLength": 300, "description": "How it is identified.", "example": "Serial or asset tag" }, "answers": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What it answers.", "example": "Where is this one?" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Tracked individually." } }, "required": ["grain", "counts", "identified_by", "answers", "note"], "description": "Grain: class, unit or lot (Section 3.9)." }, "GrainCode": { "type": "string", "pattern": "^[a-z]+$", "description": "Grain from `xpms.dim_grain` (Section 3.9).", "example": "unit" }, "CanonProvenancePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonProvenance" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonProvenance": { "type": "object", "properties": { "provenance": { "$ref": "#/components/schemas/Provenance" }, "rank": { "type": "integer", "minimum": 0, "description": "Rank, higher wins.", "example": 80 }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, in sentence case.", "example": "A tenant human entering a fact." }, "may_overwrite": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What this provenance may overwrite.", "example": "Any field not canon-locked" }, "max_confidence": { "$ref": "#/components/schemas/AssertionLabel" } }, "required": ["provenance", "rank", "definition", "may_overwrite", "max_confidence"], "description": "A provenance rank. A lower rank never overwrites a populated higher-rank field." }, "AssertionLabel": { "type": "string", "pattern": "^[A-Z]+$", "description": "Assertion label from `xpms.dim_assertion_rank` (Section 3.8).", "example": "QUOTED" }, "CanonFacetPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonFacet" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonFacet": { "type": "object", "properties": { "facet": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Facet name.", "example": "Phase" }, "form": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Form of the facet.", "example": "Nine gated phases" }, "rolls_up_to": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "What the facet rolls up to.", "example": "Act" }, "since": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "Version that introduced it, as written in canon.", "example": "3.0" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Carried from canon." } }, "required": ["facet", "form", "rolls_up_to", "since", "note"], "description": "A facet carried from canon." }, "CanonAssertionRankPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonAssertionRank" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonAssertionRank": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 0, "description": "Assertion rank.", "example": 4 }, "meaning": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Meaning of the rank.", "example": "Attested by a named accountable party." }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "A vendor quote." } }, "required": ["rank", "meaning", "note"], "description": "An assertion rank, 4 down to 0, across economics, compliance and capability." }, "CanonRecordKindPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonRecordKind" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonRecordKind": { "type": "object", "properties": { "record_kind": { "$ref": "#/components/schemas/RecordKind" }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, in sentence case.", "example": "A unit of assigned work." }, "definition_of_done": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition of done.", "example": "Done against its acceptance." }, "record_class": { "$ref": "#/components/schemas/RecordClass" }, "title_grammar": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Title grammar validated on write.", "example": "Imperative verb first." } }, "required": [ "record_kind", "definition", "definition_of_done", "record_class", "title_grammar" ], "description": "A record kind with its class, definition of done and title grammar." }, "CanonRecordSubtypePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonRecordSubtype" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonRecordSubtype": { "type": "object", "properties": { "record_kind": { "$ref": "#/components/schemas/RecordKind" }, "record_subtype": { "$ref": "#/components/schemas/RecordSubtype" }, "unspsc_segment": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "UNSPSC segment code and name.", "example": "52160000 Audio and visual equipment and accessories" } }, "required": ["record_kind", "record_subtype", "unspsc_segment"], "description": "A kind-scoped record subtype." }, "CanonRecordStatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonRecordState" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonRecordState": { "type": "object", "properties": { "record_state": { "$ref": "#/components/schemas/RecordState" }, "meaning": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Meaning of the state.", "example": "Dated and resourced." } }, "required": ["record_state", "meaning"], "description": "A record state with its meaning, in lifecycle order." }, "CanonRolePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonRole" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonRole": { "type": "object", "properties": { "role_code": { "$ref": "#/components/schemas/RoleCode" }, "role": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Role function name.", "example": "Rigging lead" }, "dept_code": { "$ref": "#/components/schemas/DeptCode" }, "staffing_ratio": { "type": ["number", "null"], "minimum": 0, "description": "Staffing ratio from canon: how many people one role holder covers.", "example": 250 }, "ratio_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Basis of the ratio.", "example": "Guests" }, "kit_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Kit basis.", "example": "Per person" }, "job_title": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Job title.", "example": "Head Rigger" } }, "required": [ "role_code", "role", "dept_code", "staffing_ratio", "ratio_basis", "kit_basis", "job_title" ], "description": "A workforce role with its staffing ratio." }, "CanonCounterpartyTypePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonCounterpartyType" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonCounterpartyType": { "type": "object", "properties": { "counterparty_type": { "$ref": "#/components/schemas/CounterpartyType" }, "definition": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Definition, in sentence case.", "example": "Designs and installs audiovisual systems." }, "classification_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Classification code.", "example": "CP-AVINT" }, "vendor_class": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Vendor class.", "example": "Class B" }, "clearance_tier": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Clearance tier.", "example": "Tier 2 - Technical Lead" }, "default_account_code": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] } }, "required": [ "counterparty_type", "definition", "classification_code", "vendor_class", "clearance_tier", "default_account_code" ], "description": "A vendor counterparty type." }, "CanonGlAccountPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonGlAccount" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonGlAccount": { "type": "object", "properties": { "account_code": { "$ref": "#/components/schemas/GlAccountCode" }, "account_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Account name.", "example": "Environment" }, "account_type": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Account type.", "example": "Expense" }, "tax_type": { "$ref": "#/components/schemas/TaxType" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Account description.", "example": "Environment class costs." }, "normal_balance": { "type": ["string", "null"], "enum": ["Debit", "Credit", null], "description": "Normal balance of the account's type: Debit or Credit.", "example": "Debit" } }, "required": [ "account_code", "account_name", "account_type", "tax_type", "description", "normal_balance" ], "description": "A GL account in the fixed 23-account chart. Tenants cannot add accounts." }, "CanonCostCenterTemplatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonCostCenterTemplate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonCostCenterTemplate": { "type": "object", "properties": { "cost_center_id": { "$ref": "#/components/schemas/CostCenterCode" }, "cost_center": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Cost center name.", "example": "Venue Standing Operations" }, "kind": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Cost center kind.", "example": "Standing" }, "scope_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Scope code the cost center belongs to.", "example": "E01" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Note from the Bible.", "example": "Runs whether or not an event does." } }, "required": ["cost_center_id", "cost_center", "kind", "scope_code", "note"], "description": "A cost center template (GL dimension 1)." }, "CanonCategoryGlPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonCategoryGl" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonCategoryGl": { "type": "object", "properties": { "cat_urid": { "$ref": "#/components/schemas/Urid" }, "default_cost_center": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Default cost center (dimension 1) of the category.", "example": "Production" }, "account_code": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] } }, "required": ["cat_urid", "default_cost_center", "account_code"], "description": "The GL account each category posts to." }, "CanonUnitAliasPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonUnitAlias" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonUnitAlias": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Alias as written.", "example": "ea" }, "unit_code": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Unit the alias maps to.", "example": "ea" }, "dimension_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Dimension of the unit, once ratified.", "example": "length" } }, "required": ["alias", "unit_code", "dimension_code"], "description": "An alias of a controlled unit." }, "CanonUnitDimensionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonUnitDimension" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonUnitDimension": { "type": "object", "properties": { "dimension_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Dimension code.", "example": "length" }, "name": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Dimension name.", "example": "Length" } }, "required": ["dimension_code", "name"], "description": "A controlled unit and the dimension it measures." }, "CanonUrnNamespacePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonUrnNamespace" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonUrnNamespace": { "type": "object", "properties": { "kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URN kind.", "example": "category" }, "table_name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "xpms table holding the kind.", "example": "elements" }, "key_column": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Natural key column of that table.", "example": "element_id" }, "label_column": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Column holding the display label.", "example": "item" } }, "required": ["kind", "table_name", "key_column", "label_column"], "description": "A URN kind under `urn:xpms`." }, "CanonLocalePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonLocale" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonLocale": { "type": "object", "properties": { "locale_code": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$", "description": "BCP 47 locale tag.", "example": "en-US" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Locale name.", "example": "English (United States)" }, "is_source": { "type": "boolean", "description": "True for the source locale, en-US.", "example": true }, "release_stage": { "type": "string", "enum": ["general", "beta"], "description": "Release stage.", "example": "general" } }, "required": ["locale_code", "name", "is_source", "release_stage"], "description": "A supported locale." }, "CanonElementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonElement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonElement": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "urid": { "$ref": "#/components/schemas/Urid" }, "item": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Element name.", "example": "Ground Stage Deck" }, "common_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Common name.", "example": "Stage deck" }, "kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Element kind.", "example": "rental" }, "unit_basis": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Unit basis of the element.", "example": "ea" }, "xyz": { "$ref": "#/components/schemas/Xyz" }, "xyz_basis": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Basis for the XYZ tag.", "example": "Physical inventory" }, "grade": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Experience grade of the element: Standard, Base, Elevated or Premium.", "example": "Standard" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Description, sentence case.", "example": "Line array for outdoor stages." }, "specification": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Specification.", "example": "12 cabinets per side." }, "tier_code": { "$ref": "#/components/schemas/TierCode" }, "lead_time_hours": { "type": ["number", "null"], "description": "Lead time in hours.", "example": 48 }, "crew": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Crew the element needs.", "example": "2 audio technicians" }, "unspsc": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "UNSPSC identifier; recorded, never minted.", "example": "52161512" }, "lifecycle_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Lifecycle state from the shared vocabulary.", "example": "Active" }, "purchase_account": { "anyOf": [{ "$ref": "#/components/schemas/GlAccountCode" }, { "type": "null" }] }, "default_cost_center": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Default cost center (dimension 1) of the element.", "example": "CC-CORP" }, "external_ref": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "External reference of the element.", "example": "TECH-VIDO-CAMR-001 · 5000.050.00" } }, "required": [ "element_id", "urid", "item", "common_name", "kind", "unit_basis", "xyz", "xyz_basis", "grade", "description", "specification", "tier_code", "lead_time_hours", "crew", "unspsc", "lifecycle_state", "purchase_account", "default_cost_center", "external_ref" ], "description": "A catalog element, the unit of the catalog." }, "ElementResolution": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "urid": { "$ref": "#/components/schemas/Urid" }, "item": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Element name.", "example": "Ground Stage Deck" }, "match": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "How the element matched.", "example": "gtin" } }, "required": ["element_id", "urid", "item", "match"], "description": "An element resolved from a query or GTIN. No match returns a NO_ANSWER refusal." }, "CanonElementPriceBandPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonElementPriceBand" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonElementPriceBand": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "valid_from": { "type": ["string", "null"], "format": "date", "description": "First day the band is valid.", "example": "2026-10-08" }, "valid_to": { "type": ["string", "null"], "format": "date", "description": "Last day the band is valid.", "example": "2026-10-08" }, "grade_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Price grade.", "example": "standard" }, "amount_minor": { "type": ["integer", "null"], "description": "Amount per unit in the basis region. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 125000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the amount.", "example": "USD" }, "assertion_word": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Economics assertion word; null means canon states none and confidence resolves as no answer.", "example": "Quoted" } }, "required": [ "element_id", "valid_from", "valid_to", "grade_code", "amount_minor", "currency_code", "assertion_word" ], "description": "A price band for an element at one grade. Effective confidence is computed at read time from the staleness policy." }, "CanonElementGtinPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonElementGtin" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonElementGtin": { "type": "object", "properties": { "gtin": { "type": "string", "pattern": "^[0-9]{8,14}$", "description": "GTIN identifier.", "example": "00012345678905" }, "element_id": { "$ref": "#/components/schemas/ItemId" }, "confirmed_by": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Ratifier who confirmed the crosswalk.", "example": "Canon Ratifier" } }, "required": ["gtin", "element_id", "confirmed_by"], "description": "A GTIN mapped to an element. One GTIN maps to at most one element." }, "CanonElementPhasePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonElementPhase" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonElementPhase": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "phase_code": { "$ref": "#/components/schemas/PhaseCode" } }, "required": ["element_id", "phase_code"], "description": "Phase participation of an element (multi-valued)." }, "CanonElementTagPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonElementTag" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonElementTag": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "tag_id": { "$ref": "#/components/schemas/TagId" } }, "required": ["element_id", "tag_id"], "description": "A tag carried by an element." }, "CanonElementPermitPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonElementPermit" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonElementPermit": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "rule": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Permit rule name.", "example": "Tent or membrane" } }, "required": ["element_id", "rule"], "description": "A permit rule an element can trigger." }, "CanonElementMetricPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonElementMetric" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonElementMetric": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "item": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Metric item.", "example": "Stage or performance area" } }, "required": ["element_id", "item"], "description": "A metric that applies to an element." }, "CanonTouchpointDisciplinePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonTouchpointDiscipline" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonTouchpointDiscipline": { "type": "object", "properties": { "touchpoint_id": { "$ref": "#/components/schemas/TouchpointId" }, "disc_code": { "$ref": "#/components/schemas/DiscCode" } }, "required": ["touchpoint_id", "disc_code"], "description": "A discipline that delivers a touchpoint." }, "CanonDisciplineTeamPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonDisciplineTeam" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonDisciplineTeam": { "type": "object", "properties": { "disc_code": { "$ref": "#/components/schemas/DiscCode" }, "team_id": { "$ref": "#/components/schemas/TeamId" } }, "required": ["disc_code", "team_id"], "description": "A canon team that works in a discipline." }, "StdDocumentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdDocument" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdDocument": { "type": "object", "properties": { "record_id": { "$ref": "#/components/schemas/StdCode" }, "document_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Document name.", "example": "Venue Load-In Guide" }, "document_type": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Document type.", "example": "Guide" }, "reference_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Reference identifier.", "example": "DOC-004" }, "file_format": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "File format.", "example": "PDF" }, "version": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Version.", "example": "v2.0" }, "issue_date": { "type": ["string", "null"], "format": "date", "description": "Issue date.", "example": "2026-10-08" }, "expiration_date": { "type": ["string", "null"], "format": "date", "description": "Expiration date.", "example": "2026-10-08" }, "department": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Department as the sheet names it.", "example": "5000 Production" }, "category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Category code or name as the sheet gives it.", "example": "5000.05.02" }, "sub_category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Sub-category as the sheet names it.", "example": "Overhead Rigging" }, "status": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Row status in the sheet.", "example": "Active" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Primary life safety and incident response" }, "organization": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Organization as the sheet names it.", "example": "GHXSTSHIP" }, "project": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Project as the sheet names it.", "example": "CSMIA26" }, "file_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "File size as the sheet gives it.", "example": "48.5 MB" }, "storage_url": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Where the file is stored, as the sheet gives it.", "example": "https://files.example/doc-001.pdf" } }, "required": [ "record_id", "document_name", "document_type", "reference_id", "file_format", "version", "issue_date", "expiration_date", "department", "category", "sub_category", "status", "notes", "organization", "project", "file_size", "storage_url" ], "description": "A document and asset library entry. Standard Library row, copied into each new org as editable org data." }, "StdCode": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Natural code of a Standard Library row (Section 2.1).", "example": "SOP-001" }, "StdEmergencyCodePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdEmergencyCode" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdEmergencyCode": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/StdCode" }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Code name.", "example": "Medical Assist" }, "emergency": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Response procedure.", "example": "Dispatch the medical team to the location." }, "swatch": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Design token of the swatch.", "example": "ecode-red" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Order of first appearance in the Playbook.", "example": 1 } }, "required": ["code", "label", "emergency", "swatch", "sort_order"], "description": "An emergency code. Standard Library row, copied into each new org as editable org data." }, "StdEnumerationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdEnumeration" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdEnumeration": { "type": "object", "properties": { "record_id": { "$ref": "#/components/schemas/StdCode" }, "enum_domain": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Enumeration the value belongs to.", "example": "Incident Severity" }, "enum_code": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Code of the value.", "example": "SEV_L3_MODERATE" }, "enum_label": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Label of the value.", "example": "Level 3 - Moderate" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the value means.", "example": "Non-life-threatening medical case." }, "sort_order": { "type": ["number", "null"], "description": "Order within the enumeration.", "example": 3 }, "color_code": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "description": "Display color as the sheet stores it.", "example": "Amber" }, "target_entity": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Record the enumeration applies to.", "example": "Incident CAD Log" }, "is_default": { "type": ["boolean", "null"], "description": "Whether the value is the default.", "example": false }, "department": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Department as the sheet names it.", "example": "5000 Production" }, "category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Category code or name as the sheet gives it.", "example": "5000.05.02" }, "sub_category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Sub-category as the sheet names it.", "example": "Overhead Rigging" }, "status": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Row status in the sheet.", "example": "Active" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Primary life safety and incident response" } }, "required": [ "record_id", "enum_domain", "enum_code", "enum_label", "description", "sort_order", "color_code", "target_entity", "is_default", "department", "category", "sub_category", "status", "notes" ], "description": "A controlled enumeration value. Standard Library row, copied into each new org as editable org data." }, "StdLaborRateCardPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdLaborRateCard" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdLaborRateCard": { "type": "object", "properties": { "rate_card_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon rate card identifier.", "example": "LRC-001" }, "role_code": { "$ref": "#/components/schemas/RoleCode" }, "job_title": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Job title of the role.", "example": "Head Rigger" }, "class_code": { "$ref": "#/components/schemas/DeptCode" }, "department": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Department of the role.", "example": "Production" }, "worker_classification": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Worker classification label.", "example": "Employee" }, "pay_basis": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Pay basis.", "example": "Hourly" }, "arrangement": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Arrangement.", "example": "Per Engagement" }, "standard_rate_minor": { "type": ["integer", "null"], "description": "Standard rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4500, "format": "int64" }, "min_grade_rate_minor": { "type": ["integer", "null"], "description": "Lowest grade rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 3800, "format": "int64" }, "max_grade_rate_minor": { "type": ["integer", "null"], "description": "Highest grade rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 5200, "format": "int64" }, "per_diem_rate_minor": { "type": ["integer", "null"], "description": "Per diem rate. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 6500, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the rates.", "example": "USD" }, "overtime_rule_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon overtime rule.", "example": "OTR-001" }, "ot_multiplier": { "type": "number", "description": "Overtime multiplier.", "example": 1.5 }, "dt_multiplier": { "type": "number", "description": "Double time multiplier.", "example": 2 }, "gl_account": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "description": "Expense GL account of the role's department.", "example": "5400" }, "gl_account_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Name of that GL account.", "example": "Production Labor" } }, "required": [ "rate_card_id", "role_code", "job_title", "class_code", "department", "worker_classification", "pay_basis", "arrangement", "standard_rate_minor", "min_grade_rate_minor", "max_grade_rate_minor", "per_diem_rate_minor", "currency_code", "overtime_rule_id", "ot_multiplier", "dt_multiplier", "gl_account", "gl_account_name" ], "description": "A labor rate card line. Standard Library row, copied into each new org as editable org data." }, "StdRadioChannelPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdRadioChannel" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdRadioChannel": { "type": "object", "properties": { "record_id": { "$ref": "#/components/schemas/StdCode" }, "channel": { "type": ["number", "null"], "description": "Radio channel number.", "example": 1 }, "zone": { "type": ["number", "null"], "description": "Radio zone.", "example": 1 }, "assignment": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Who the channel is assigned to.", "example": "Emergency" }, "department": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Department as the sheet names it.", "example": "5000 Production" }, "category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Category code or name as the sheet gives it.", "example": "5000.05.02" }, "sub_category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Sub-category as the sheet names it.", "example": "Overhead Rigging" }, "status": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Row status in the sheet.", "example": "Active" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Primary life safety and incident response" } }, "required": [ "record_id", "channel", "zone", "assignment", "department", "category", "sub_category", "status", "notes" ], "description": "A radio channel plan entry. Standard Library row, copied into each new org as editable org data." }, "StdRolePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdRole" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdRole": { "type": "object", "properties": { "role_code": { "$ref": "#/components/schemas/RoleCode" }, "class_code": { "$ref": "#/components/schemas/DeptCode" }, "job_title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Job title; the one home of the title.", "example": "Head Rigger" }, "discipline": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Discipline.", "example": "Rigging" }, "rank": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Rank.", "example": "Lead" }, "job_summary": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Job summary.", "example": "Leads the rigging crew." }, "key_responsibilities": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Key responsibilities.", "example": "Plans and signs off every point." }, "qualifications": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Qualifications.", "example": "ETCP Certified Rigger." }, "physical_requirements": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Physical requirements.", "example": "Works at height." }, "required_certifications": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Required certifications.", "example": "ETCP" }, "default_clearance_tier": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Default clearance tier.", "example": "Tier 2" }, "default_radio_channel": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Default radio channel.", "example": "RCH-004" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Union call." } }, "required": [ "role_code", "class_code", "job_title", "discipline", "rank", "job_summary", "key_responsibilities", "qualifications", "physical_requirements", "required_certifications", "default_clearance_tier", "default_radio_channel", "notes" ], "description": "A Roles Library entry. Standard Library row, copied into each new org as editable org data." }, "StdSopPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdSop" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdSop": { "type": "object", "properties": { "sop_id": { "$ref": "#/components/schemas/StdCode" }, "title": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "SOP title.", "example": "Working at Height" }, "operational_domain": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Operational domain.", "example": "Structural & Rigging Safety" }, "revision": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Revision.", "example": "v2.0" }, "accountable_role_code": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Accountable role code.", "example": "5000.51.02" }, "required_ppe_compliance_tag": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Required PPE and compliance tags.", "example": "TAG-002 OSHA" }, "prerequisites_and_hazards": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Prerequisites and hazards.", "example": "Verify the drop zone." }, "procedure_step_1": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Procedure step 1.", "example": "Inspect every hoist." }, "procedure_step_2": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Procedure step 2.", "example": "Lift to trim." }, "procedure_step_3": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Procedure step 3.", "example": "Load test." }, "procedure_step_4": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Procedure step 4.", "example": "Sign off." }, "reference_doc_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Reference document.", "example": "DOC-004" }, "department": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Department as the sheet names it.", "example": "5000 Production" }, "category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Category code or name as the sheet gives it.", "example": "5000.05.02" }, "sub_category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Sub-category as the sheet names it.", "example": "Overhead Rigging" }, "status": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Row status in the sheet.", "example": "Active" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Primary life safety and incident response" }, "organization": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Organization as the sheet names it.", "example": "GHXSTSHIP" }, "project": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Project as the sheet names it.", "example": "CSMIA26" } }, "required": [ "sop_id", "title", "operational_domain", "revision", "accountable_role_code", "required_ppe_compliance_tag", "prerequisites_and_hazards", "procedure_step_1", "procedure_step_2", "procedure_step_3", "procedure_step_4", "reference_doc_id", "department", "category", "sub_category", "status", "notes", "organization", "project" ], "description": "A standard operating procedure. Standard Library row, copied into each new org as editable org data." }, "StdVendorClassPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdVendorClass" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdVendorClass": { "type": "object", "properties": { "record_id": { "$ref": "#/components/schemas/StdCode" }, "class": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Vendor class.", "example": "Staging Vendor" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the class covers.", "example": "Stages, decks and risers." }, "clearance_tier": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Clearance tier.", "example": "Tier 2" }, "department": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Department as the sheet names it.", "example": "5000 Production" }, "category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Category code or name as the sheet gives it.", "example": "5000.05.02" }, "sub_category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Sub-category as the sheet names it.", "example": "Overhead Rigging" }, "status": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Row status in the sheet.", "example": "Active" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Primary life safety and incident response" } }, "required": [ "record_id", "class", "description", "clearance_tier", "department", "category", "sub_category", "status", "notes" ], "description": "A vendor class. Standard Library row, copied into each new org as editable org data." }, "StdVendorEntitlementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdVendorEntitlement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdVendorEntitlement": { "type": "object", "properties": { "record_id": { "$ref": "#/components/schemas/StdCode" }, "vendor_class": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Vendor class the entitlement is for.", "example": "VCL-001" }, "module": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Module the class may use.", "example": "Advance" }, "permitted": { "type": ["boolean", "null"], "description": "Whether the class may use the module.", "example": true }, "status": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Row status in the sheet.", "example": "Active" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Primary life safety and incident response" } }, "required": ["record_id", "vendor_class", "module", "permitted", "status", "notes"], "description": "A vendor or sponsor entitlement. Standard Library row, copied into each new org as editable org data." }, "StdVerbiagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StdVerbiage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "StdVerbiage": { "type": "object", "properties": { "record_id": { "$ref": "#/components/schemas/StdCode" }, "verbiage": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Term.", "example": "Load-In" }, "title": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Title.", "example": "Load-In Announcement" }, "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Text.", "example": "All crew to the loading dock." }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "When the text is used.", "example": "Read at the start of load-in." }, "department": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Department as the sheet names it.", "example": "5000 Production" }, "category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Category code or name as the sheet gives it.", "example": "5000.05.02" }, "sub_category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Sub-category as the sheet names it.", "example": "Overhead Rigging" }, "status": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Row status in the sheet.", "example": "Active" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Notes in the sheet.", "example": "Primary life safety and incident response" } }, "required": [ "record_id", "verbiage", "title", "body", "description", "department", "category", "sub_category", "status", "notes" ], "description": "A controlled vocabulary term. Standard Library row, copied into each new org as editable org data." }, "CanonSupersessionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonSupersession" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonSupersession": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Code that was superseded.", "example": "DIS" }, "successor_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Code that supersedes it.", "example": "SCP" }, "domain": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Code domain, such as phase.", "example": "phase" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Label the superseded code carried.", "example": "Discovery" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the code was superseded.", "example": "Renamed in 4.0." } }, "required": ["code", "successor_code", "domain", "label", "reason"], "description": "A supersession edge. The graph stays acyclic." }, "CanonRatificationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonRatification" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonRatification": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What was ratified.", "example": "4.0 phase grammar" }, "ratifier": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Named ratifier.", "example": "Canon Ratifier" }, "ratified_at": { "type": "string", "format": "date-time", "description": "When it was ratified.", "example": "2026-10-08T14:30:00Z" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Ratification note.", "example": "Ratified at the canon review." } }, "required": ["subject", "ratifier", "ratified_at", "note"], "description": "A ratification record. 4.0 grammar is proposed until a named ratifier is recorded." }, "CanonVersionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonVersion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonVersion": { "type": "object", "properties": { "version_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon version.", "example": "4.0" }, "generation": { "type": "integer", "minimum": 1, "description": "Canon generation, incremented by every canon data migration.", "example": 1 }, "bible_generated_at": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Generation time stated in the Bible _generated tab: a wall-clock time without a zone.", "example": "2026-10-01 09:00:00" } }, "required": ["version_code", "generation", "bible_generated_at"], "description": "The current canon version and generation. Canon responses are cached by generation." }, "CoordinateMatrixCellPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CoordinateMatrixCell" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CoordinateMatrixCell": { "type": "object", "properties": { "dept_code": { "$ref": "#/components/schemas/DeptCode" }, "phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "element_count": { "type": "integer", "minimum": 0, "description": "Elements participating at the coordinate.", "example": 42 } }, "required": ["dept_code", "phase_code", "element_count"], "description": "One of 90 coordinates: a department by a phase, counting participation." }, "PhaseCoveragePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhaseCoverage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PhaseCoverage": { "type": "object", "properties": { "phase_code": { "$ref": "#/components/schemas/PhaseCode" }, "active_element_count": { "type": "integer", "minimum": 0, "description": "Active elements in the phase.", "example": 120 }, "declared_gap": { "type": "boolean", "description": "Whether the phase carries a declared gap.", "example": false }, "gate": { "type": ["integer", "null"], "minimum": 0, "description": "Gate ordinal.", "example": 3 }, "phase": { "type": ["string", "null"], "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Phase label.", "example": "Advance" }, "element_count": { "type": ["integer", "null"], "minimum": 0, "description": "Elements participating in the phase.", "example": 42 }, "category_count": { "type": ["integer", "null"], "minimum": 0, "description": "Distinct categories among participating elements.", "example": 7 }, "has_active_element": { "type": ["boolean", "null"], "description": "True when at least one participating element is Active.", "example": true }, "declared_gap_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Why the phase has no Active element, as its declared gap states it; null without one.", "example": null } }, "required": [ "phase_code", "active_element_count", "declared_gap", "gate", "phase", "element_count", "category_count", "has_active_element", "declared_gap_reason" ], "description": "Coverage of a phase: Active elements or a declared gap." }, "ElementEconomicsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ElementEconomics" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ElementEconomics": { "type": "object", "properties": { "element_id": { "$ref": "#/components/schemas/ItemId" }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the amount; null when unpriced.", "example": "USD" }, "effective_confidence": { "type": ["string", "null"], "pattern": "^[A-Z][A-Z_]*$", "description": "Confidence at read time from the staleness policy: an assertion label, or NO_ANSWER.", "example": "QUOTED" }, "item": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Item name.", "example": "Line Array" }, "urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "unit_basis": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "Unit basis of the amount.", "example": "day" }, "grade_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Price grade.", "example": "standard" }, "amount_minor": { "type": ["integer", "null"], "description": "Amount per unit. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 125000, "format": "int64" }, "assertion_word": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Stated economics assertion of the band.", "example": "Quoted" }, "valid_from": { "type": ["string", "null"], "format": "date", "description": "Date the band was sourced.", "example": "2026-10-08" }, "valid_to": { "type": ["string", "null"], "format": "date", "description": "Date the band stops applying.", "example": "2026-10-08" }, "is_unpriced": { "type": ["boolean", "null"], "description": "True when the element has no band at this grade.", "example": false } }, "required": [ "element_id", "currency_code", "effective_confidence", "item", "urid", "unit_basis", "grade_code", "amount_minor", "assertion_word", "valid_from", "valid_to", "is_unpriced" ], "description": "Element economics with effective confidence at read time." }, "CrosswalkCoveragePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrosswalkCoverage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CrosswalkCoverage": { "type": "object", "properties": { "cat_urid": { "anyOf": [{ "$ref": "#/components/schemas/Urid" }, { "type": "null" }] }, "element_count": { "type": "integer", "minimum": 0, "description": "Elements under the URID.", "example": 12 }, "category": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Category name.", "example": "Production Leadership" }, "unspsc_element_count": { "type": ["integer", "null"], "minimum": 0, "description": "Elements carrying an UNSPSC identifier.", "example": 12 }, "gtin_element_count": { "type": ["integer", "null"], "minimum": 0, "description": "Elements with at least one confirmed GTIN.", "example": 4 }, "gtin_count": { "type": ["integer", "null"], "minimum": 0, "description": "Confirmed GTINs bound to elements of the category.", "example": 9 } }, "required": [ "cat_urid", "element_count", "category", "unspsc_element_count", "gtin_element_count", "gtin_count" ], "description": "Crosswalk coverage from GTIN to GPC brick to UNSPSC to URID." }, "UrnResolution": { "type": "object", "properties": { "urn": { "$ref": "#/components/schemas/Urn" }, "kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URN kind.", "example": "category" }, "key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Natural key of the row.", "example": "4000.01.01" }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display label of the row.", "example": "Production Leadership" }, "resolved_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Key of the live row after following supersessions.", "example": "SCP" }, "is_superseded": { "type": "boolean", "description": "Whether the asked key was superseded.", "example": false } }, "required": ["urn", "kind", "key", "label", "resolved_key", "is_superseded"], "description": "A URN resolved to its canon row." }, "Urn": { "type": "string", "pattern": "^urn:xpms:[a-z_]+:.+$", "description": "URN in the `urn:xpms` namespace.", "example": "urn:xpms:category:4000.01.01" }, "CanonIntake": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the canon intake.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "proposed_kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "What kind of canon value is proposed.", "example": "category" }, "proposed_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Proposed code.", "example": "4000.01.50" }, "proposed_label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Proposed label.", "example": "Modular Stage Systems" }, "rationale": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why the addition is needed.", "example": "Several orgs track modular stage systems." }, "intake_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Intake state. A Title Case value from the lifecycle's database enum.", "example": "Proposed" } }, "required": [ "id", "created_at", "updated_at", "proposed_kind", "proposed_code", "proposed_label", "rationale", "intake_state" ], "description": "A proposed canon addition, staged for ratification." }, "CanonIntakeCreate": { "type": "object", "properties": { "proposed_kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "What kind of canon value is proposed.", "example": "category" }, "proposed_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Proposed code.", "example": "4000.01.50" }, "proposed_label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Proposed label.", "example": "Modular Stage Systems" }, "rationale": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why the addition is needed.", "example": "Several orgs track modular stage systems." } }, "required": ["proposed_kind", "proposed_code", "proposed_label", "rationale"], "description": "Fields accepted when creating a CanonIntake." }, "Me": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the calling person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "active_organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the organization the credential is bound to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_count": { "type": "integer", "minimum": 0, "description": "Internal memberships held.", "example": 2 }, "engagement_count": { "type": "integer", "minimum": 0, "description": "External engagements held.", "example": 5 } }, "required": ["person_id", "active_organization_id", "membership_count", "engagement_count"], "description": "The caller: person, memberships, engagements and the active context." }, "PersonPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Person" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Person": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "full_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Legal or full name.", "example": "Alex Rivera" }, "given_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Optional given name, as the person writes it.", "example": "Ivy" }, "family_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Optional family name, as the person writes it.", "example": "Marchetti" } }, "required": ["id", "created_at", "updated_at", "full_name", "given_name", "family_name"], "description": "One human, linked to one sign-in. Personal facts are owned by the person." }, "PersonUpdate": { "type": "object", "properties": { "full_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Legal or full name.", "example": "Alex Rivera" }, "given_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Optional given name, as the person writes it.", "example": "Ivy" }, "family_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Optional family name, as the person writes it.", "example": "Marchetti" } }, "description": "Fields accepted when updating a Person. Omitted fields are unchanged." }, "OrganizationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Trade name.", "example": "Northwind Live" }, "slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URL slug.", "example": "northwind-live" }, "parent_org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the partner organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_type": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Legal form from `xpms.organization_type` (decision D17): For-Profit, Nonprofit or Public Agency. It decides which worker classifications engagements may use.", "example": "For-Profit" } }, "required": [ "id", "created_at", "updated_at", "name", "slug", "parent_org_id", "organization_type" ], "description": "Every company on the platform: a tenant (with a subscription), an external account, or both. A partner org cannot have a parent partner." }, "OrganizationUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Trade name.", "example": "Northwind Live" }, "slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URL slug.", "example": "northwind-live" }, "parent_org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the partner organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_type": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Legal form from `xpms.organization_type` (decision D17): For-Profit, Nonprofit or Public Agency. It decides which worker classifications engagements may use.", "example": "For-Profit" } }, "description": "Fields accepted when updating a Organization. Omitted fields are unchanged." }, "CreateOrganizationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Organization name.", "example": "Northwind Live" }, "slug": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?$", "description": "URL slug; reserved and taken slugs are refused.", "example": "northwind-live" } }, "required": ["name", "slug"], "description": "Creates an organization on the Access plan with the caller as its Owner." }, "CreateClientOrganizationResult": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the client organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "invite_id": { "type": "string", "format": "uuid", "description": "Identifier of the Owner invite.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "invite_token": { "type": "string", "minLength": 1, "description": "Invite token from the invitation email. Sent in the body, never in a URL.", "example": "xinv_3f9a1c0d7e2b4a6f8c1d0e9b7a5c3f1e" } }, "required": ["org_id", "invite_id", "invite_token"], "description": "The created client org and its Owner invite. The token is shown once." }, "CreateClientOrganizationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Client organization name.", "example": "Harbor City Events" }, "slug": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?$", "description": "URL slug; reserved and taken slugs are refused.", "example": "northwind-live" }, "owner_email": { "type": "string", "format": "email", "description": "Email of the client's first Owner, who receives an invite.", "example": "alex.rivera@northwindlive.example" }, "plan_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Plan code from `plans.yaml`; defaults to access.", "example": "access" } }, "required": ["name", "slug", "owner_email"], "description": "Creates a client organization under the caller's partner organization (Section 4.6.1)." }, "LeavePartnerRequest": { "type": "object", "properties": { "confirm_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The org's name, typed exactly.", "example": "Tidewater Events" } }, "required": ["confirm_name"], "description": "Confirmation of leaving the partner." }, "MembershipPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Membership": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of membership.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of membership.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "person_id", "valid_from", "valid_to" ], "description": "A person in an organization as an internal member, with time-boxed validity." }, "MembershipRolePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MembershipRole" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MembershipRole": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the membership role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": "string", "format": "uuid", "description": "Identifier of the held role: a system role or a custom role of the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "granted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person accountable for the grant; null when the platform granted the first Owner of a new org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "membership_id", "role_id", "granted_by" ], "description": "A role held through a membership. A person may hold several; capabilities are the union. A person cannot grant themselves a role." }, "MembershipRoleCreate": { "type": "object", "properties": { "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": "string", "format": "uuid", "description": "Identifier of the held role: a system role or a custom role of the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["membership_id", "role_id"], "description": "Fields accepted when creating a MembershipRole." }, "ProjectAssignmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectAssignment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectAssignment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When the assignment starts.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "When the assignment ends; null while open.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the org membership of the person, in the project's org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_role": { "type": "string", "enum": ["Producer", "Department Head", "Coordinator", "Field Supervisor", "Field"], "description": "Project role.", "example": "Producer" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "valid_from", "valid_to", "membership_id", "project_role" ], "description": "A person on a project, with scope nodes and dates." }, "ProjectAssignmentCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When the assignment starts.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "When the assignment ends; null while open.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the org membership of the person, in the project's org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_role": { "type": "string", "enum": ["Producer", "Department Head", "Coordinator", "Field Supervisor", "Field"], "description": "Project role.", "example": "Producer" } }, "required": ["project_id", "membership_id", "project_role"], "description": "Fields accepted when creating a ProjectAssignment." }, "ProjectAssignmentUpdate": { "type": "object", "properties": { "valid_from": { "type": "string", "format": "date-time", "description": "When the assignment starts.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "When the assignment ends; null while open.", "example": "2026-10-08T14:30:00Z" }, "project_role": { "type": "string", "enum": ["Producer", "Department Head", "Coordinator", "Field Supervisor", "Field"], "description": "Project role.", "example": "Producer" } }, "description": "Fields accepted when updating a ProjectAssignment. Omitted fields are unchanged." }, "ProjectAssignmentRolePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectAssignmentRole" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectAssignmentRole": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_member_id": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_role": { "$ref": "#/components/schemas/ProjectRole" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_member_id", "project_role" ], "description": "A project role held through a project assignment." }, "ProjectRole": { "type": "string", "enum": ["Producer", "Department Head", "Coordinator", "Field Supervisor", "Field"], "description": "Project role (Section 8).", "example": "Producer" }, "ProjectAssignmentRoleCreate": { "type": "object", "properties": { "project_member_id": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_role": { "$ref": "#/components/schemas/ProjectRole" } }, "required": ["project_member_id", "project_role"], "description": "Fields accepted when creating a ProjectAssignmentRole." }, "AccountMembershipPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountMembership" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AccountMembership": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the account membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of account membership.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of account membership.", "example": "2026-10-08T14:30:00Z" } }, "required": ["id", "created_at", "updated_at", "person_id", "valid_from", "valid_to"], "description": "A person in an external organization's account." }, "AccountMembershipCreate": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_role": { "$ref": "#/components/schemas/AccountRole" } }, "required": ["person_id", "account_role"], "description": "Fields accepted when creating a AccountMembership." }, "AccountRole": { "type": "string", "enum": ["Account Owner", "Account Admin", "Account Finance", "Account Member"], "description": "Role inside an external account.", "example": "Account Finance" }, "AccountMembershipRolePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountMembershipRole" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AccountMembershipRole": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the account membership role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "account_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the account membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_role": { "$ref": "#/components/schemas/AccountRole" }, "granted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who granted the role; null for the creator's own Account Owner role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "created_at", "updated_at", "account_membership_id", "account_role", "granted_by" ], "description": "An account role held through an account membership." }, "AccountMembershipRoleCreate": { "type": "object", "properties": { "account_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the account membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_role": { "$ref": "#/components/schemas/AccountRole" } }, "required": ["account_membership_id", "account_role"], "description": "Fields accepted when creating a AccountMembershipRole." }, "OrganizationRelationshipPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationRelationship" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrganizationRelationship": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the organization relationship.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the related organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_type": { "anyOf": [{ "$ref": "#/components/schemas/CounterpartyType" }, { "type": "null" }] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "organization_id", "counterparty_type" ], "description": "One organization's relationship to another, with the org-owned facts. Never visible to another org." }, "OrganizationRelationshipCreate": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the related organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_type": { "anyOf": [{ "$ref": "#/components/schemas/CounterpartyType" }, { "type": "null" }] } }, "required": ["organization_id"], "description": "Fields accepted when creating a OrganizationRelationship." }, "OrganizationRelationshipUpdate": { "type": "object", "properties": { "counterparty_type": { "allOf": [ { "$ref": "#/components/schemas/CounterpartyType" }, { "type": ["string", "null"] } ] } }, "description": "Fields accepted when updating a OrganizationRelationship. Omitted fields are unchanged." }, "RepresentationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Representation" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Representation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the representation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "representative_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the representative.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "artist_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the represented artist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentationScope" }, "description": "Delegated scopes, stored as junction rows.", "example": ["Offers", "Advance"] }, "expires_on": { "type": "string", "format": "date", "description": "Expiry.", "example": "2026-10-08" }, "accepted_at": { "type": ["string", "null"], "format": "date-time", "description": "When the artist accepted.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the artist or the account revoked it.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "created_at", "updated_at", "representative_person_id", "artist_person_id", "scopes", "expires_on", "accepted_at", "revoked_at" ], "description": "One party acting for another, with scopes and expiry. The artist accepts it." }, "RepresentationScope": { "type": "string", "enum": ["Offers", "Advance", "Settlement", "Documents"], "description": "Scope a representation delegates.", "example": "Advance" }, "RepresentationCreate": { "type": "object", "properties": { "representative_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the representative.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "artist_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the represented artist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/RepresentationScope" }, "description": "Delegated scopes, stored as junction rows.", "example": ["Offers", "Advance"] }, "expires_on": { "type": "string", "format": "date", "description": "Expiry.", "example": "2026-10-08" } }, "required": ["artist_person_id", "scopes", "expires_on"], "description": "Fields accepted when creating a Representation." }, "JoinRequestPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JoinRequest" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "JoinRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the join request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the requesting person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Message to the admins.", "example": "I run audio for the summer series." }, "join_request_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Request state. A Title Case value from the lifecycle's database enum.", "example": "Proposed" }, "decided_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the deciding admin.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "person_id", "message", "join_request_state", "decided_by" ], "description": "A request to join an org, approved by an Admin." }, "JoinRequestCreate": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the requesting person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Message to the admins.", "example": "I run audio for the summer series." } }, "required": ["person_id"], "description": "Fields accepted when creating a JoinRequest." }, "InvitationLinkPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationLink" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InvitationLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the invitation link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role": { "anyOf": [{ "$ref": "#/components/schemas/OrgRole" }, { "type": "null" }] }, "expires_at": { "type": "string", "format": "date-time", "description": "When the link expires.", "example": "2026-10-08T14:30:00Z" }, "max_uses": { "type": ["integer", "null"], "minimum": 1, "description": "Maximum uses.", "example": 10 }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the link was revoked.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "role", "expires_at", "max_uses", "revoked_at" ], "description": "An invitation link with a role and an expiry. The token is shown once." }, "OrgRole": { "type": "string", "enum": ["Owner", "Admin", "Manager", "Member", "Collaborator", "Field", "Viewer"], "description": "Platform role in band order (Section 8).", "example": "Manager" }, "InvitationLinkCreate": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/OrgRole" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the link expires.", "example": "2026-10-08T14:30:00Z" }, "max_uses": { "type": ["integer", "null"], "minimum": 1, "description": "Maximum uses.", "example": 10 } }, "required": ["role", "expires_at"], "description": "Fields accepted when creating a InvitationLink." }, "InvitePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Invite": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the invite.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "email": { "type": "string", "format": "email", "description": "Invitee email.", "example": "alex.rivera@northwindlive.example" }, "role_id": { "type": "string", "format": "uuid", "description": "Identifier of the role offered.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the invite expires.", "example": "2026-10-08T14:30:00Z" }, "invited_by": { "type": "string", "format": "uuid", "description": "Identifier of the inviting person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "accepted_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was accepted.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was revoked or replaced.", "example": "2026-10-08T14:30:00Z" }, "partner_bootstrap": { "type": "boolean", "description": "True for the first Owner invite a partner issues when it creates a client org (Section 4.6.1).", "example": false }, "accepted_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who accepted.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "email", "role_id", "expires_at", "invited_by", "accepted_at", "revoked_at", "partner_bootstrap", "accepted_person_id" ], "description": "An email invitation to join an org. Created through `invites.create` (the `app.invite_member` RPC); the token is never stored or returned again." }, "InviteMemberResult": { "type": "object", "properties": { "invite_id": { "type": "string", "format": "uuid", "description": "Identifier of the invite.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "invite_token": { "type": "string", "minLength": 1, "description": "Invite token from the invitation email. Sent in the body, never in a URL.", "example": "xinv_3f9a1c0d7e2b4a6f8c1d0e9b7a5c3f1e" } }, "required": ["invite_id", "invite_token"], "description": "The created invite. The token is shown once; only its hash is stored." }, "InviteMemberRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Invitee email.", "example": "alex.rivera@northwindlive.example" }, "role_id": { "type": "string", "format": "uuid", "description": "Identifier of the role offered, at or below the inviter's band.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_for_hours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "Hours until the invite expires, from 1 to 720. Default 336 (14 days).", "example": 336 } }, "required": ["email", "role_id"], "description": "Invites an email to the caller's organization, replacing any pending invite for it." }, "InvitePreview": { "type": "object", "properties": { "org_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Organization the invite joins.", "example": "Northwind Live" }, "role_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Offered role code.", "example": "member" }, "role_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Offered role name.", "example": "Member" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the invite expires.", "example": "2026-10-08T14:30:00Z" } }, "required": ["org_name", "role_code", "role_name", "expires_at"], "description": "What an invite offers, shown only to its confirmed recipient." }, "InviteTokenRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Invite token from the invitation email. Sent in the body, never in a URL.", "example": "xinv_3f9a1c0d7e2b4a6f8c1d0e9b7a5c3f1e" } }, "required": ["token"], "description": "An invite token presented by its recipient." }, "AcceptInviteResult": { "type": "object", "properties": { "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership joined or reused.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["membership_id"], "description": "The membership the accepted invite joined." }, "VerifiedDomainPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VerifiedDomain" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "VerifiedDomain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the verified domain.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Lowercase host name, for example gateway.northwindlive.example.", "example": "gateway.northwindlive.example" }, "purpose": { "type": "string", "enum": ["Atlas", "Gateway", "Email Sending", "Verified Domain"], "description": "What the domain is for.", "example": "Atlas" }, "verification_state": { "type": "string", "enum": ["Pending", "Verified", "Failed"], "description": "DNS verification state; changed only by app.record_domain_verification.", "example": "Pending" }, "verification_token": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Value the org publishes in a DNS TXT record to prove control.", "example": "xos-verify=6f1c2d" }, "last_checked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the verification service last checked DNS.", "example": "2026-10-08T14:30:00Z" }, "auto_join_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role a person with a confirmed address at this verified domain receives on joining automatically; null turns automatic join off.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provisioning_status": { "type": "string", "enum": ["Not Started", "Requested", "Pending DNS", "Active", "Failed", "Released"], "description": "Where the domain stands at its provider.", "example": "Pending DNS" }, "dns_records": { "type": "array", "items": { "$ref": "#/components/schemas/DomainDnsRecord" }, "description": "DNS records to publish for the provider." }, "tls_ready": { "type": "boolean", "description": "True once the provider issued the TLS certificate.", "example": false }, "provisioning_error": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Why the latest provisioning step failed.", "example": "Vercel returned 400" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "hostname", "purpose", "verification_state", "verification_token", "last_checked_at", "auto_join_role_id", "provisioning_status", "dns_records", "tls_ready", "provisioning_error" ], "description": "A verified email domain with automatic join and a default role." }, "DomainDnsRecord": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 10, "description": "DNS record type.", "example": "CNAME" }, "name": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Host the record is published at.", "example": "atlas.northwindlive.example" }, "value": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Record value.", "example": "cname.vercel-dns.com" }, "purpose": { "type": "string", "minLength": 1, "maxLength": 20, "description": "What the record is for: routing, verification, spf, dkim, dmarc or receiving.", "example": "routing" } }, "required": ["type", "name", "value", "purpose"], "description": "A DNS record the org publishes for a custom domain's provider." }, "VerifiedDomainCreate": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Lowercase host name, for example gateway.northwindlive.example.", "example": "gateway.northwindlive.example" }, "purpose": { "type": "string", "enum": ["Atlas", "Gateway", "Email Sending", "Verified Domain"], "description": "What the domain is for.", "example": "Atlas" }, "auto_join_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role a person with a confirmed address at this verified domain receives on joining automatically; null turns automatic join off.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["hostname", "purpose"], "description": "Fields accepted when creating a VerifiedDomain." }, "VerifiedDomainUpdate": { "type": "object", "properties": { "auto_join_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role a person with a confirmed address at this verified domain receives on joining automatically; null turns automatic join off.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a VerifiedDomain. Omitted fields are unchanged." }, "OffboardingChecklistPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OffboardingChecklist" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OffboardingChecklist": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the offboarding checklist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the ending membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reassign_to_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the default reassignee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "open_record_count": { "type": "integer", "minimum": 0, "description": "Open records still assigned.", "example": 4 }, "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "When offboarding completed.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "membership_id", "reassign_to_person_id", "open_record_count", "completed_at" ], "description": "The checklist that reassigns a departing member's open records." }, "OffboardingChecklistUpdate": { "type": "object", "properties": { "reassign_to_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the default reassignee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a OffboardingChecklist. Omitted fields are unchanged." }, "PersonProfilePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonProfile" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PersonProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the person profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "headline": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Headline.", "example": "Head Rigger, Festivals and Arenas" }, "bio": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Bio.", "example": "Fifteen years rigging touring shows." }, "pronouns": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pronouns, optional.", "example": "they/them" }, "locality": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "City.", "example": "Miami" }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility" }, "search_indexing": { "type": "boolean", "description": "Whether search engines may index a public profile.", "example": false }, "handle": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{1,38}[a-z0-9])$", "description": "Unique handle for /u/{handle} or /c/{handle}: 3 to 40 lowercase letters, digits and single hyphens. Changeable once every 30 days; the old handle redirects for 90 days.", "example": "northwind-live" }, "handle_changed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the handle last changed; null until the first change. Set by the database.", "example": "2026-10-08T14:30:00Z" }, "preferred_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Name the person goes by.", "example": "Alex" } }, "required": [ "id", "created_at", "updated_at", "person_id", "headline", "bio", "pronouns", "locality", "country", "visibility", "search_indexing", "handle", "handle_changed_at", "preferred_name" ], "description": "A person's profile page, owned by the person. New profiles start Private." }, "ProfileVisibility": { "type": "string", "enum": ["Public", "Network", "Private"], "description": "Profile visibility. Sections and fields may be set lower than the profile, never higher.", "example": "Private" }, "PersonProfileCreate": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "headline": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Headline.", "example": "Head Rigger, Festivals and Arenas" }, "bio": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Bio.", "example": "Fifteen years rigging touring shows." }, "pronouns": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pronouns, optional.", "example": "they/them" }, "locality": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "City.", "example": "Miami" }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility" }, "search_indexing": { "type": "boolean", "description": "Whether search engines may index a public profile.", "example": false } }, "required": ["person_id", "visibility", "search_indexing"], "description": "Fields accepted when creating a PersonProfile." }, "PersonProfileUpdate": { "type": "object", "properties": { "headline": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Headline.", "example": "Head Rigger, Festivals and Arenas" }, "bio": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Bio.", "example": "Fifteen years rigging touring shows." }, "pronouns": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Pronouns, optional.", "example": "they/them" }, "locality": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "City.", "example": "Miami" }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility" }, "search_indexing": { "type": "boolean", "description": "Whether search engines may index a public profile.", "example": false }, "handle": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{1,38}[a-z0-9])$", "description": "Unique handle for /u/{handle} or /c/{handle}: 3 to 40 lowercase letters, digits and single hyphens. Changeable once every 30 days; the old handle redirects for 90 days.", "example": "northwind-live" }, "preferred_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Name the person goes by.", "example": "Alex" } }, "description": "Fields accepted when updating a PersonProfile. Omitted fields are unchanged." }, "OrganizationProfilePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationProfile" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrganizationProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the organization profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "about": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "About.", "example": "Live event production for waterfront venues." }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility" }, "search_indexing": { "type": "boolean", "description": "Whether search engines may index a public profile.", "example": false }, "handle": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{1,38}[a-z0-9])$", "description": "Unique handle for /u/{handle} or /c/{handle}: 3 to 40 lowercase letters, digits and single hyphens. Changeable once every 30 days; the old handle redirects for 90 days.", "example": "northwind-live" }, "handle_changed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the handle last changed; null until the first change. Set by the database.", "example": "2026-10-08T14:30:00Z" }, "website_url": { "type": ["string", "null"], "format": "uri", "description": "Website of the organization; https only.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "contact_email": { "type": ["string", "null"], "format": "email", "description": "Contact email of the organization, stored in lowercase.", "example": "alex.rivera@northwindlive.example" } }, "required": [ "id", "created_at", "updated_at", "organization_id", "about", "visibility", "search_indexing", "handle", "handle_changed_at", "website_url", "contact_email" ], "description": "An organization's profile page. New organizations start Network." }, "OrganizationProfileCreate": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "about": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "About.", "example": "Live event production for waterfront venues." }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility" }, "search_indexing": { "type": "boolean", "description": "Whether search engines may index a public profile.", "example": false } }, "required": ["organization_id", "visibility", "search_indexing"], "description": "Fields accepted when creating a OrganizationProfile." }, "OrganizationProfileUpdate": { "type": "object", "properties": { "about": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "About.", "example": "Live event production for waterfront venues." }, "visibility": { "$ref": "#/components/schemas/ProfileVisibility" }, "search_indexing": { "type": "boolean", "description": "Whether search engines may index a public profile.", "example": false }, "handle": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{1,38}[a-z0-9])$", "description": "Unique handle for /u/{handle} or /c/{handle}: 3 to 40 lowercase letters, digits and single hyphens. Changeable once every 30 days; the old handle redirects for 90 days.", "example": "northwind-live" }, "website_url": { "type": ["string", "null"], "format": "uri", "description": "Website of the organization; https only.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "contact_email": { "type": ["string", "null"], "format": "email", "description": "Contact email of the organization, stored in lowercase.", "example": "alex.rivera@northwindlive.example" } }, "description": "Fields accepted when updating a OrganizationProfile. Omitted fields are unchanged." }, "ProfileVisibilityRulePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileVisibilityRule" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProfileVisibilityRule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the profile visibility rule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the profile owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "section": { "type": "string", "enum": [ "photo", "pronouns", "headline", "bio", "location", "skills", "certifications", "portfolio", "rates", "availability", "languages", "references", "links", "organizations" ], "description": "Profile section.", "example": "photo" }, "visibility": { "type": "string", "enum": ["Private", "Network", "Public"], "description": "Visibility chosen for the section.", "example": "Private" } }, "required": ["id", "created_at", "updated_at", "person_id", "section", "visibility"], "description": "Visibility of one profile section or field. It can be lower than the profile, never higher." }, "ProfileVisibilityRuleCreate": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the profile owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "section": { "type": "string", "enum": [ "photo", "pronouns", "headline", "bio", "location", "skills", "certifications", "portfolio", "rates", "availability", "languages", "references", "links", "organizations" ], "description": "Profile section.", "example": "photo" }, "visibility": { "type": "string", "enum": ["Private", "Network", "Public"], "description": "Visibility chosen for the section.", "example": "Private" } }, "required": ["person_id", "section", "visibility"], "description": "Fields accepted when creating a ProfileVisibilityRule." }, "ProfileVisibilityRuleUpdate": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["Private", "Network", "Public"], "description": "Visibility chosen for the section.", "example": "Private" } }, "description": "Fields accepted when updating a ProfileVisibilityRule. Omitted fields are unchanged." }, "VerificationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Verification" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Verification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the verification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "verified_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was verified.", "example": "2026-10-08T14:30:00Z" }, "method": { "type": "string", "enum": ["Stripe Identity", "Business Registry"], "description": "How the organization was verified.", "example": "Stripe Identity" }, "provider_reference": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The provider's verification or registry record reference.", "example": "vs_1Pq2Rs3Tu4" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the verification lapses; null when it does not.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the platform revoked it.", "example": "2026-10-08T14:30:00Z" }, "revocation_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Why it was revoked.", "example": "The registry record lapsed." } }, "required": [ "id", "created_at", "updated_at", "verified_at", "method", "provider_reference", "expires_at", "revoked_at", "revocation_reason" ], "description": "A verification badge, shown only after the platform or a provider checks the claim." }, "BlockPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Block" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Block": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the block.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "blocked_urn": { "type": "string", "minLength": 1, "maxLength": 300, "description": "URN of the blocked person (urn:xpms:person:{id}) or organization (urn:xpms:organization:{id}).", "example": "urn:xpms:person:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["id", "created_at", "updated_at", "blocked_urn"], "description": "A person's block of another person or an organization (Section 4.5.6 Profile Privacy). It hides the blocker's profile from the blocked person and from every member of a blocked organization, and the blocked profile from the blocker. Memberships and engagements are not affected." }, "BlockCreate": { "type": "object", "properties": { "blocked_urn": { "type": "string", "minLength": 1, "maxLength": 300, "description": "URN of the blocked person (urn:xpms:person:{id}) or organization (urn:xpms:organization:{id}).", "example": "urn:xpms:person:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["blocked_urn"], "description": "Fields accepted when creating a Block." }, "SubscriptionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the subscription.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "plan_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Plan code from `plans.yaml`.", "example": "pro" }, "subscription_state": { "type": "string", "enum": ["trialing", "active", "past_due", "read_only", "canceled"], "description": "Subscription status as Stripe reports it; read_only after the grace period.", "example": "trialing" }, "trial_ends_at": { "type": ["string", "null"], "format": "date-time", "description": "When the subscription's trial ends; null when it never had one.", "example": "2026-10-08T14:30:00Z" }, "extra_seats": { "type": "integer", "minimum": 0, "description": "Seats bought above the plan's seat allowance.", "example": 3 }, "seats_grandfathered": { "type": "boolean", "description": "True when the subscription keeps unlimited seats from before plans had seat limits, until its plan changes.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "plan_code", "subscription_state", "trial_ends_at", "extra_seats", "seats_grandfathered" ], "description": "Present only when an organization uses Atlas: plan, billing and tenant settings." }, "PlanPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Plan": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Plan code.", "example": "pro" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Plan order from the free plan upward.", "example": 1 } }, "required": ["code", "sort_order"], "description": "A plan generated from `plans.yaml`." }, "WorkspacePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Workspace name.", "example": "Festivals" }, "slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URL slug.", "example": "festivals" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "slug" ], "description": "A workspace inside an organization." }, "WorkspaceCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Workspace name.", "example": "Festivals" }, "slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URL slug.", "example": "festivals" } }, "required": ["name", "slug"], "description": "Fields accepted when creating a Workspace." }, "WorkspaceUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Workspace name.", "example": "Festivals" }, "slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URL slug.", "example": "festivals" } }, "description": "Fields accepted when updating a Workspace. Omitted fields are unchanged." }, "WorkspaceMemberPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMember" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkspaceMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the workspace member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "workspace_id": { "type": "string", "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership assigned to the workspace, in the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "workspace_id", "membership_id" ], "description": "A member of a workspace." }, "WorkspaceMemberCreate": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership assigned to the workspace, in the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["workspace_id", "membership_id"], "description": "Fields accepted when creating a WorkspaceMember." }, "TeamPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Team": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Team name.", "example": "Show Control" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name" ], "description": "A working group, distinct from canon teams." }, "TeamCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Team name.", "example": "Show Control" } }, "required": ["name"], "description": "Fields accepted when creating a Team." }, "TeamUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Team name.", "example": "Show Control" } }, "description": "Fields accepted when updating a Team. Omitted fields are unchanged." }, "TeamMemberPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TeamMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the team member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member of the team, in the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "team_id", "membership_id" ], "description": "A member of a team." }, "TeamMemberCreate": { "type": "object", "properties": { "team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member of the team, in the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["team_id", "membership_id"], "description": "Fields accepted when creating a TeamMember." }, "OrgBrandingPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgBranding" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrgBranding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the org branding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "display_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Brand display name.", "example": "Northwind Live" }, "logo_light_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Logo for light themes: object path in the org-brand bucket, starting with the org id.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "logo_dark_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Logo for dark themes: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "favicon_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Favicon: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "app_icon_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "App icon: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "accent_hex": { "type": ["string", "null"], "pattern": "^#[0-9A-F]{6}$", "description": "Accent color as uppercase #RRGGBB, replacing accent-default in every theme; null keeps the platform accent.", "example": "#1F6FEB" }, "neutral_tint_hex": { "type": ["string", "null"], "pattern": "^#[0-9A-F]{6}$", "description": "Optional neutral tint as uppercase #RRGGBB.", "example": "#1F6FEB" }, "font_family": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Font family from the approved list; null keeps the platform font.", "example": "Inter" }, "radius_scale": { "type": "string", "enum": ["Compact", "Default", "Rounded"], "description": "Corner radius scale.", "example": "Compact" }, "email_sender_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Sender name on emails sent for the org.", "example": "Northwind Live" }, "support_email": { "type": ["string", "null"], "format": "email", "description": "Support address shown on branded surfaces.", "example": "alex.rivera@northwindlive.example" }, "legal_entity_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Legal entity named on generated documents and emails.", "example": "Northwind Live LLC" }, "suppress_powered_by": { "type": "boolean", "description": "True hides Powered by XOS; it takes effect only while the plan includes white label.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "display_name", "logo_light_path", "logo_dark_path", "favicon_path", "app_icon_path", "accent_hex", "neutral_tint_hex", "font_family", "radius_scale", "email_sender_name", "support_email", "legal_entity_name", "suppress_powered_by" ], "description": "White label brand settings for Atlas, Gateway, email and Compass." }, "OrgBrandingCreate": { "type": "object", "properties": { "display_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Brand display name.", "example": "Northwind Live" }, "logo_light_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Logo for light themes: object path in the org-brand bucket, starting with the org id.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "logo_dark_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Logo for dark themes: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "favicon_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Favicon: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "app_icon_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "App icon: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "accent_hex": { "type": ["string", "null"], "pattern": "^#[0-9A-F]{6}$", "description": "Accent color as uppercase #RRGGBB, replacing accent-default in every theme; null keeps the platform accent.", "example": "#1F6FEB" }, "neutral_tint_hex": { "type": ["string", "null"], "pattern": "^#[0-9A-F]{6}$", "description": "Optional neutral tint as uppercase #RRGGBB.", "example": "#1F6FEB" }, "font_family": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Font family from the approved list; null keeps the platform font.", "example": "Inter" }, "radius_scale": { "type": "string", "enum": ["Compact", "Default", "Rounded"], "description": "Corner radius scale.", "example": "Compact" }, "email_sender_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Sender name on emails sent for the org.", "example": "Northwind Live" }, "support_email": { "type": ["string", "null"], "format": "email", "description": "Support address shown on branded surfaces.", "example": "alex.rivera@northwindlive.example" }, "legal_entity_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Legal entity named on generated documents and emails.", "example": "Northwind Live LLC" }, "suppress_powered_by": { "type": "boolean", "description": "True hides Powered by XOS; it takes effect only while the plan includes white label.", "example": false } }, "description": "Fields accepted when creating a OrgBranding." }, "OrgBrandingUpdate": { "type": "object", "properties": { "display_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Brand display name.", "example": "Northwind Live" }, "logo_light_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Logo for light themes: object path in the org-brand bucket, starting with the org id.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "logo_dark_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Logo for dark themes: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "favicon_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Favicon: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "app_icon_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "App icon: object path in the org-brand bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg" }, "accent_hex": { "type": ["string", "null"], "pattern": "^#[0-9A-F]{6}$", "description": "Accent color as uppercase #RRGGBB, replacing accent-default in every theme; null keeps the platform accent.", "example": "#1F6FEB" }, "neutral_tint_hex": { "type": ["string", "null"], "pattern": "^#[0-9A-F]{6}$", "description": "Optional neutral tint as uppercase #RRGGBB.", "example": "#1F6FEB" }, "font_family": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Font family from the approved list; null keeps the platform font.", "example": "Inter" }, "radius_scale": { "type": "string", "enum": ["Compact", "Default", "Rounded"], "description": "Corner radius scale.", "example": "Compact" }, "email_sender_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Sender name on emails sent for the org.", "example": "Northwind Live" }, "support_email": { "type": ["string", "null"], "format": "email", "description": "Support address shown on branded surfaces.", "example": "alex.rivera@northwindlive.example" }, "legal_entity_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Legal entity named on generated documents and emails.", "example": "Northwind Live LLC" }, "suppress_powered_by": { "type": "boolean", "description": "True hides Powered by XOS; it takes effect only while the plan includes white label.", "example": false } }, "description": "Fields accepted when updating a OrgBranding. Omitted fields are unchanged." }, "OrgLegalEntityPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgLegalEntity" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrgLegalEntity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the org legal entity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "legal_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Legal name.", "example": "Northwind Live LLC" }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "tax_identifier": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Tax identifier.", "example": "123456789" }, { "$ref": "#/components/schemas/Masked" }, { "type": "null" } ] }, "fiscal_year_start_month": { "type": "integer", "minimum": 1, "description": "Fiscal year start month.", "example": 1 }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Base currency.", "example": "USD" }, "is_primary": { "type": "boolean", "description": "True for the org's primary entity, printed on generated documents. The first entity is primary; marking another moves the mark.", "example": true }, "tax_identifier_last4": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Last four characters of the tax identifier.", "example": "6789" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "legal_name", "country_code", "tax_identifier", "fiscal_year_start_month", "base_currency", "is_primary", "tax_identifier_last4" ], "description": "A legal entity of the organization with its fiscal settings." }, "OrgLegalEntityCreate": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Legal name.", "example": "Northwind Live LLC" }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "tax_identifier": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Tax identifier.", "example": "123456789" }, "fiscal_year_start_month": { "type": "integer", "minimum": 1, "description": "Fiscal year start month.", "example": 1 }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Base currency.", "example": "USD" }, "is_primary": { "type": "boolean", "description": "True for the org's primary entity, printed on generated documents. The first entity is primary; marking another moves the mark.", "example": true } }, "required": ["legal_name", "country_code", "fiscal_year_start_month", "base_currency"], "description": "Fields accepted when creating a OrgLegalEntity." }, "OrgLegalEntityUpdate": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Legal name.", "example": "Northwind Live LLC" }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "tax_identifier": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Tax identifier.", "example": "123456789" }, "fiscal_year_start_month": { "type": "integer", "minimum": 1, "description": "Fiscal year start month.", "example": 1 }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Base currency.", "example": "USD" }, "is_primary": { "type": "boolean", "description": "True for the org's primary entity, printed on generated documents. The first entity is primary; marking another moves the mark.", "example": true } }, "description": "Fields accepted when updating a OrgLegalEntity. Omitted fields are unchanged." }, "OrgIpAllowlistEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgIpAllowlistEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrgIpAllowlistEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the org ip allowlist entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "cidr": { "type": "string", "minLength": 1, "maxLength": 300, "description": "CIDR block.", "example": "203.0.113.0/24" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Label.", "example": "Office" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "cidr", "label" ], "description": "An allowed network for Atlas and the API." }, "OrgIpAllowlistEntryCreate": { "type": "object", "properties": { "cidr": { "type": "string", "minLength": 1, "maxLength": 300, "description": "CIDR block.", "example": "203.0.113.0/24" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Label.", "example": "Office" } }, "required": ["cidr", "label"], "description": "Fields accepted when creating a OrgIpAllowlistEntry." }, "OrgIpAllowlistEntryUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Label.", "example": "Office" } }, "description": "Fields accepted when updating a OrgIpAllowlistEntry. Omitted fields are unchanged." }, "RolePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Role" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Role": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Role name.", "example": "Finance Approver" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the role is for.", "example": "Approves purchase orders up to the spend limit." }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Role code. System role labels come from the i18n catalogs keyed by it; custom role codes never reuse a system code.", "example": "site_lead" }, "band": { "type": "integer", "minimum": 1, "description": "Band in Section 8 order, 1 Owner to 7 Viewer. Custom roles take 2 to 7, and a person assigns only roles at or below their own band.", "example": 4 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "description", "code", "band" ], "description": "A role: a platform role or an org custom role built from the capability set." }, "RoleCreate": { "type": "object", "properties": { "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Role name.", "example": "Finance Approver" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the role is for.", "example": "Approves purchase orders up to the spend limit." }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Role code. System role labels come from the i18n catalogs keyed by it; custom role codes never reuse a system code.", "example": "site_lead" }, "band": { "type": "integer", "minimum": 1, "description": "Band in Section 8 order, 1 Owner to 7 Viewer. Custom roles take 2 to 7, and a person assigns only roles at or below their own band.", "example": 4 } }, "required": ["code", "band"], "description": "Fields accepted when creating a Role." }, "RoleUpdate": { "type": "object", "properties": { "name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Role name.", "example": "Finance Approver" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the role is for.", "example": "Approves purchase orders up to the spend limit." }, "band": { "type": "integer", "minimum": 1, "description": "Band in Section 8 order, 1 Owner to 7 Viewer. Custom roles take 2 to 7, and a person assigns only roles at or below their own band.", "example": 4 } }, "description": "Fields accepted when updating a Role. Omitted fields are unchanged." }, "CapabilityPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Capability": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "finance.po.approve" }, "module_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability group; OAuth scopes map one to one to groups.", "example": "finance" }, "capability_class": { "type": "string", "enum": ["read", "write", "approve", "manage", "export"], "description": "Kind of act the capability authorizes.", "example": "read" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What the capability allows, for documentation and the roles page.", "example": "Approve purchase orders within spend authority." }, "sort_order": { "type": "integer", "minimum": 0, "description": "Registry order, the default sort.", "example": 1 } }, "required": ["code", "module_code", "capability_class", "description", "sort_order"], "description": "A capability from `packages/schemas/capabilities.yaml`. Read-only." }, "RoleCapabilityPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoleCapability" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RoleCapability": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the role capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": "string", "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "finance.po.approve" }, "reach": { "type": "string", "enum": ["own", "assigned", "organization"], "description": "Own rows, assigned scopes or the whole org.", "example": "own" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "role_id", "capability_code", "reach" ], "description": "A capability granted to a role." }, "RoleCapabilityCreate": { "type": "object", "properties": { "role_id": { "type": "string", "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "finance.po.approve" }, "reach": { "type": "string", "enum": ["own", "assigned", "organization"], "description": "Own rows, assigned scopes or the whole org.", "example": "own" } }, "required": ["role_id", "capability_code", "reach"], "description": "Fields accepted when creating a RoleCapability." }, "UserCapabilityGrantPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserCapabilityGrant" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "UserCapabilityGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the user capability grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "crew.timesheet.approve" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of the grant.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the grant.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership that receives the capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_kind": { "type": ["string", "null"], "enum": ["organization", "workspace", "team", "project", "record", null], "description": "Kind of scope the grant is limited to; null for an org-wide grant.", "example": "organization" }, "scope_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the workspace, team, project or record the grant is limited to; null for an org-wide grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "granted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who granted it; never the grantee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the grant was made.", "example": "Covering approvals during the tour." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "capability_code", "valid_from", "valid_to", "membership_id", "scope_kind", "scope_id", "granted_by", "reason" ], "description": "A time-boxed capability grant to a person. A person cannot grant themselves a capability." }, "UserCapabilityGrantCreate": { "type": "object", "properties": { "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "crew.timesheet.approve" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start of the grant.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the grant.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership that receives the capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_kind": { "type": ["string", "null"], "enum": ["organization", "workspace", "team", "project", "record", null], "description": "Kind of scope the grant is limited to; null for an org-wide grant.", "example": "organization" }, "scope_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the workspace, team, project or record the grant is limited to; null for an org-wide grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the grant was made.", "example": "Covering approvals during the tour." } }, "required": ["capability_code", "membership_id", "reason"], "description": "Fields accepted when creating a UserCapabilityGrant." }, "UserCapabilityGrantUpdate": { "type": "object", "properties": { "valid_from": { "type": "string", "format": "date-time", "description": "Start of the grant.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the grant.", "example": "2026-10-08T14:30:00Z" }, "scope_kind": { "type": ["string", "null"], "enum": ["organization", "workspace", "team", "project", "record", null], "description": "Kind of scope the grant is limited to; null for an org-wide grant.", "example": "organization" }, "scope_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the workspace, team, project or record the grant is limited to; null for an org-wide grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the grant was made.", "example": "Covering approvals during the tour." } }, "description": "Fields accepted when updating a UserCapabilityGrant. Omitted fields are unchanged." }, "RecordGrantPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordGrant" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RecordGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the record grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "records.read" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the grant.", "example": "2026-10-08T14:30:00Z" }, "target_kind": { "type": "string", "enum": ["organization", "workspace", "team", "project", "record"], "description": "Kind of target.", "example": "organization" }, "target_id": { "type": "string", "format": "uuid", "description": "Identifier of the target row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grantee_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who receives access; null when an organization does.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grantee_org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the organization whose active members receive access; null when a person does.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When access starts.", "example": "2026-10-08T14:30:00Z" }, "granted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who granted it; never the grantee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the grant was made, for example the partner agreement clause.", "example": "Partner agreement, clause 4.2." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "capability_code", "valid_to", "target_kind", "target_id", "grantee_person_id", "grantee_org_id", "valid_from", "granted_by", "reason" ], "description": "A grant on specific records, with scope and expiry." }, "RecordGrantCreate": { "type": "object", "properties": { "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "records.read" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the grant.", "example": "2026-10-08T14:30:00Z" }, "target_kind": { "type": "string", "enum": ["organization", "workspace", "team", "project", "record"], "description": "Kind of target.", "example": "organization" }, "target_id": { "type": "string", "format": "uuid", "description": "Identifier of the target row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grantee_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who receives access; null when an organization does.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grantee_org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the organization whose active members receive access; null when a person does.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When access starts.", "example": "2026-10-08T14:30:00Z" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the grant was made, for example the partner agreement clause.", "example": "Partner agreement, clause 4.2." } }, "required": ["capability_code", "valid_to", "target_kind", "target_id", "reason"], "description": "Fields accepted when creating a RecordGrant." }, "RecordGrantUpdate": { "type": "object", "properties": { "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability verb.", "example": "records.read" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the grant.", "example": "2026-10-08T14:30:00Z" }, "grantee_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who receives access; null when an organization does.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grantee_org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the organization whose active members receive access; null when a person does.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When access starts.", "example": "2026-10-08T14:30:00Z" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the grant was made, for example the partner agreement clause.", "example": "Partner agreement, clause 4.2." } }, "description": "Fields accepted when updating a RecordGrant. Omitted fields are unchanged." }, "DelegationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delegation" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Delegation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the delegation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "Start.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": "string", "format": "date-time", "description": "End.", "example": "2026-10-08T14:30:00Z" }, "delegator_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who delegates.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "delegate_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who acts for the delegator; never the delegator.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z_]*(\\.[a-z][a-z_]*)+$", "description": "Delegated capability; null delegates every approve-class capability the delegator holds.", "example": "finance.po.approve" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the delegation exists.", "example": "Annual leave, 12 to 26 May." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "valid_from", "valid_to", "delegator_membership_id", "delegate_membership_id", "capability_code", "reason" ], "description": "A time-boxed delegation of approvals from one person to another." }, "DelegationCreate": { "type": "object", "properties": { "valid_from": { "type": "string", "format": "date-time", "description": "Start.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": "string", "format": "date-time", "description": "End.", "example": "2026-10-08T14:30:00Z" }, "delegator_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who delegates.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "delegate_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who acts for the delegator; never the delegator.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z_]*(\\.[a-z][a-z_]*)+$", "description": "Delegated capability; null delegates every approve-class capability the delegator holds.", "example": "finance.po.approve" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the delegation exists.", "example": "Annual leave, 12 to 26 May." } }, "required": [ "valid_from", "valid_to", "delegator_membership_id", "delegate_membership_id", "reason" ], "description": "Fields accepted when creating a Delegation." }, "DelegationUpdate": { "type": "object", "properties": { "valid_from": { "type": "string", "format": "date-time", "description": "Start.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": "string", "format": "date-time", "description": "End.", "example": "2026-10-08T14:30:00Z" }, "capability_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z_]*(\\.[a-z][a-z_]*)+$", "description": "Delegated capability; null delegates every approve-class capability the delegator holds.", "example": "finance.po.approve" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why the delegation exists.", "example": "Annual leave, 12 to 26 May." } }, "description": "Fields accepted when updating a Delegation. Omitted fields are unchanged." }, "SpendAuthorityPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpendAuthority" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SpendAuthority": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the spend authority.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "document_type": { "type": "string", "enum": [ "Purchase Order", "Change Order", "Expense", "Invoice Approval", "Contract", "Payroll Run", "Requisition" ], "description": "Document type the limit applies to.", "example": "Purchase Order" }, "limit_minor": { "type": ["integer", "null"], "description": "Single-approver limit in the org currency. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 2500000, "format": "int64" }, "dual_approval_above_minor": { "type": ["integer", "null"], "description": "Amount above which two approvers are required. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 10000000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the one person the limit applies to; null when it applies to a role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "GL account the limit is scoped to; null for every account.", "example": "5100" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center the limit is scoped to; null for every cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When the limit starts.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "When the limit ends; null while open-ended.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "role_id", "document_type", "limit_minor", "dual_approval_above_minor", "currency_code", "membership_id", "account_code", "cost_center_id", "valid_from", "valid_to" ], "description": "A spend limit by role or person and document type, enforced in the approval RPCs." }, "SpendAuthorityCreate": { "type": "object", "properties": { "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "document_type": { "type": "string", "enum": [ "Purchase Order", "Change Order", "Expense", "Invoice Approval", "Contract", "Payroll Run", "Requisition" ], "description": "Document type the limit applies to.", "example": "Purchase Order" }, "limit_minor": { "type": ["integer", "null"], "description": "Single-approver limit in the org currency. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 2500000, "format": "int64" }, "dual_approval_above_minor": { "type": ["integer", "null"], "description": "Amount above which two approvers are required. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 10000000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the one person the limit applies to; null when it applies to a role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "GL account the limit is scoped to; null for every account.", "example": "5100" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center the limit is scoped to; null for every cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When the limit starts.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "When the limit ends; null while open-ended.", "example": "2026-10-08T14:30:00Z" } }, "required": ["document_type", "limit_minor", "currency_code"], "description": "Fields accepted when creating a SpendAuthority." }, "SpendAuthorityUpdate": { "type": "object", "properties": { "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "document_type": { "type": "string", "enum": [ "Purchase Order", "Change Order", "Expense", "Invoice Approval", "Contract", "Payroll Run", "Requisition" ], "description": "Document type the limit applies to.", "example": "Purchase Order" }, "limit_minor": { "type": ["integer", "null"], "description": "Single-approver limit in the org currency. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 2500000, "format": "int64" }, "dual_approval_above_minor": { "type": ["integer", "null"], "description": "Amount above which two approvers are required. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 10000000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code of every money field.", "example": "USD" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership of the one person the limit applies to; null when it applies to a role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "account_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "GL account the limit is scoped to; null for every account.", "example": "5100" }, "cost_center_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the cost center the limit is scoped to; null for every cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_from": { "type": "string", "format": "date-time", "description": "When the limit starts.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "When the limit ends; null while open-ended.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a SpendAuthority. Omitted fields are unchanged." }, "SeparationOfDutiesRulePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeparationOfDutiesRule" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SeparationOfDutiesRule": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Rule code, the rule a refusal names.", "example": "sod_approval_requester" }, "enforced_on": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What the rule is enforced on.", "example": "Purchase orders" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What the rule forbids.", "example": "The requester of a spend document cannot approve it." } }, "required": ["code", "enforced_on", "description"], "description": "A separation of duties rule. Orgs may tighten defaults but never remove them." }, "ColumnClassificationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnClassification" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ColumnClassification": { "type": "object", "properties": { "table_name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Schema-qualified table.", "example": "app.pay_rates" }, "column_name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Column.", "example": "rate_minor" }, "classification": { "$ref": "#/components/schemas/Classification" }, "read_capability": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability that unmasks it.", "example": "data.restricted.read.payroll" } }, "required": ["table_name", "column_name", "classification", "read_capability"], "description": "The classification of one column in the column registry." }, "Classification": { "type": "string", "enum": ["Public", "Internal", "Confidential", "Restricted"], "description": "Column classification (Section 8.3).", "example": "Restricted" }, "AccessReviewCampaignPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccessReviewCampaign" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AccessReviewCampaign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the access review campaign.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Campaign name.", "example": "Q4 Access Review" }, "due_on": { "type": "string", "format": "date", "description": "Due date.", "example": "2026-10-08" }, "auto_remove_unreviewed": { "type": "boolean", "description": "Remove access left unreviewed after 14 days.", "example": false }, "campaign_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Campaign state. A Title Case value from the lifecycle's database enum.", "example": "Active" }, "opened_at": { "type": "string", "format": "date-time", "description": "When the campaign opened and its items were taken.", "example": "2026-10-08T14:30:00Z" }, "closed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the campaign completed or was canceled; null while Active.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "due_on", "auto_remove_unreviewed", "campaign_state", "opened_at", "closed_at" ], "description": "A quarterly access review campaign." }, "AccessReviewCampaignCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Campaign name.", "example": "Q4 Access Review" }, "due_on": { "type": "string", "format": "date", "description": "Due date.", "example": "2026-10-08" }, "auto_remove_unreviewed": { "type": "boolean", "description": "Remove access left unreviewed after 14 days.", "example": false } }, "required": ["name", "due_on"], "description": "Fields accepted when creating a AccessReviewCampaign." }, "AccessReviewCampaignUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Campaign name.", "example": "Q4 Access Review" }, "due_on": { "type": "string", "format": "date", "description": "Due date.", "example": "2026-10-08" }, "auto_remove_unreviewed": { "type": "boolean", "description": "Remove access left unreviewed after 14 days.", "example": false } }, "description": "Fields accepted when updating a AccessReviewCampaign. Omitted fields are unchanged." }, "AccessReviewItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccessReviewItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AccessReviewItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the access review item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "access_review_campaign_id": { "type": "string", "format": "uuid", "description": "Identifier of the campaign.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_role_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decision": { "type": ["string", "null"], "enum": ["Confirmed", "Removed", null], "description": "Confirmed keeps the role; Removed ends it at once. Null while unreviewed; final once set.", "example": "Confirmed" }, "decided_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the reviewer; null for an automatic removal.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_at": { "type": ["string", "null"], "format": "date-time", "description": "When the decision was recorded.", "example": "2026-10-08T14:30:00Z" }, "flagged_at": { "type": ["string", "null"], "format": "date-time", "description": "When the item was flagged as unreviewed after the grace period.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "access_review_campaign_id", "membership_role_id", "decision", "decided_by", "decided_at", "flagged_at" ], "description": "One membership role to confirm or remove." }, "AccessReviewItemUpdate": { "type": "object", "properties": { "decision": { "type": ["string", "null"], "enum": ["Confirmed", "Removed", null], "description": "Confirmed keeps the role; Removed ends it at once. Null while unreviewed; final once set.", "example": "Confirmed" } }, "description": "Fields accepted when updating a AccessReviewItem. Omitted fields are unchanged." }, "BreakGlassSessionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BreakGlassSession" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "BreakGlassSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the break glass session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the Owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 20, "maxLength": 2000, "description": "Written reason, 20 to 2000 characters.", "example": "Payroll export failed during show day and must run now." }, "started_at": { "type": "string", "format": "date-time", "description": "Start.", "example": "2026-10-08T14:30:00Z" }, "expires_at": { "type": "string", "format": "date-time", "description": "End, one hour after start.", "example": "2026-10-08T14:30:00Z" }, "ended_at": { "type": ["string", "null"], "format": "date-time", "description": "When the holder ended it early; null when it ran its hour.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "person_id", "reason", "started_at", "expires_at", "ended_at" ], "description": "One hour of emergency full access for an Owner. Requires MFA and a reason; every Admin is notified." }, "BreakGlassSessionCreate": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 20, "maxLength": 2000, "description": "Written reason, 20 to 2000 characters.", "example": "Payroll export failed during show day and must run now." } }, "required": ["reason"], "description": "Fields accepted when creating a BreakGlassSession." }, "ProjectSharePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectShare" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectShare": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "partner_organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the partner organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the share.", "example": "2026-10-08T14:30:00Z" }, "project_role": { "$ref": "#/components/schemas/ProjectRole" }, "scope_node_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Shared scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "maxItems": 200, "description": "Scope nodes the share opens, with everything under them; empty shares the whole scope tree." }, "valid_from": { "type": "string", "format": "date-time", "description": "When the share started.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "partner_organization_id", "valid_to", "project_role", "scope_node_ids", "valid_from" ], "description": "A project shared with a partner org, mapping its roles onto project roles." }, "ProjectShareCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "partner_organization_id": { "type": "string", "format": "uuid", "description": "Identifier of the partner organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the share.", "example": "2026-10-08T14:30:00Z" }, "project_role": { "$ref": "#/components/schemas/ProjectRole" }, "scope_node_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Shared scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "maxItems": 200, "description": "Scope nodes the share opens, with everything under them; empty shares the whole scope tree." } }, "required": ["project_id", "partner_organization_id"], "description": "Fields accepted when creating a ProjectShare." }, "ProjectShareUpdate": { "type": "object", "properties": { "valid_to": { "type": ["string", "null"], "format": "date-time", "description": "End of the share.", "example": "2026-10-08T14:30:00Z" }, "project_role": { "$ref": "#/components/schemas/ProjectRole" }, "scope_node_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Shared scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "maxItems": 200, "description": "Scope nodes the share opens, with everything under them; empty shares the whole scope tree." } }, "description": "Fields accepted when updating a ProjectShare. Omitted fields are unchanged." }, "ScimGroupMappingPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScimGroupMapping" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ScimGroupMapping": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the scim group mapping.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "idp_group": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Identity-provider group name.", "example": "event-finance" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "identity_provider_id": { "type": "string", "format": "uuid", "description": "Identifier of the identity provider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "idp_group", "role_id", "team_id", "identity_provider_id" ], "description": "An identity-provider group mapped to a role or team." }, "ScimGroupMappingCreate": { "type": "object", "properties": { "idp_group": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Identity-provider group name.", "example": "event-finance" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "identity_provider_id": { "type": "string", "format": "uuid", "description": "Identifier of the identity provider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["idp_group", "identity_provider_id"], "description": "Fields accepted when creating a ScimGroupMapping." }, "ScimGroupMappingUpdate": { "type": "object", "properties": { "idp_group": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Identity-provider group name.", "example": "event-finance" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a ScimGroupMapping. Omitted fields are unchanged." }, "ApiKeyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the api key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Key name.", "example": "Accounting Sync" }, "service_account_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the service account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Capability groups the key may use.", "example": ["finance"] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry.", "example": "2026-10-08T14:30:00Z" }, "prefix": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Visible key prefix.", "example": "xos_live_7Hq2" }, "last_used_at": { "type": ["string", "null"], "format": "date-time", "description": "Last use.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was revoked.", "example": "2026-10-08T14:30:00Z" }, "revoked_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who revoked the key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "service_account_id", "scopes", "expires_at", "prefix", "last_used_at", "revoked_at", "revoked_by" ], "description": "An org-scoped API key with capability scopes and expiry. The secret is shown once and stored hashed." }, "ApiKeyUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Key name.", "example": "Accounting Sync" }, "service_account_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the service account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Capability groups the key may use.", "example": ["finance"] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a ApiKey. Omitted fields are unchanged." }, "ApiKeySecret": { "type": "object", "properties": { "api_key_id": { "type": "string", "format": "uuid", "description": "Identifier of the API key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "secret": { "type": "string", "minLength": 1, "description": "The full key. Shown once; only its hash is stored.", "example": "xos_live_7Hq2wQ1nC8vL0pR4tY6u" } }, "required": ["api_key_id", "secret"], "description": "A newly created API key secret, shown once." }, "ApiKeyCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Key name.", "example": "Accounting Sync" }, "service_account_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the service account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Capability groups the key may use.", "example": ["finance"] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry.", "example": "2026-10-08T14:30:00Z" } }, "required": ["name", "scopes", "expires_at"], "description": "Fields accepted when creating a ApiKey." }, "ServiceAccountPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceAccount" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ServiceAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the service account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Service account name.", "example": "Ledger Export Bot" }, "owner_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "Expiry.", "example": "2026-10-08T14:30:00Z" }, "user_id": { "type": "string", "format": "uuid", "description": "Identifier of the sign-in of the service account, which never signs in interactively.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person row of the service account, the actor in audit columns.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership that carries the service account's role in the org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "owner_person_id", "expires_at", "user_id", "person_id", "membership_id" ], "description": "A non-human member with its own audit identity." }, "ServiceAccountCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Service account name.", "example": "Ledger Export Bot" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "Expiry.", "example": "2026-10-08T14:30:00Z" }, "role_id": { "type": "string", "format": "uuid", "description": "Identifier of the role the service account's membership holds.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name", "role_id"], "description": "Fields accepted when creating a ServiceAccount." }, "ServiceAccountUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Service account name.", "example": "Ledger Export Bot" }, "owner_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "Expiry.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a ServiceAccount. Omitted fields are unchanged." }, "OauthAppPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OauthApp" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OauthApp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the oauth app.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "App name.", "example": "Show Planner" }, "client_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "OAuth client identifier.", "example": "xos_client_31f9" }, "redirect_uri": { "type": "string", "format": "uri", "description": "Registered redirect URI.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "client_id", "redirect_uri" ], "description": "An OAuth 2.1 client using PKCE." }, "OauthAppCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "App name.", "example": "Show Planner" }, "redirect_uri": { "type": "string", "format": "uri", "description": "Registered redirect URI.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "required": ["name", "redirect_uri"], "description": "Fields accepted when creating a OauthApp." }, "OauthAppUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "App name.", "example": "Show Planner" }, "redirect_uri": { "type": "string", "format": "uri", "description": "Registered redirect URI.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "description": "Fields accepted when updating a OauthApp. Omitted fields are unchanged." }, "OauthGrantPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OauthGrant" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OauthGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the oauth grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "oauth_app_id": { "type": "string", "format": "uuid", "description": "Identifier of the OAuth app.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the granting person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Granted capability groups.", "example": ["records"] }, "granted_at": { "type": "string", "format": "date-time", "description": "When consent was given.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "oauth_app_id", "person_id", "scopes", "granted_at" ], "description": "A user's consent grant to an OAuth app. Revocable." }, "IntegrationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Integration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the integration.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "provider_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Provider.", "example": "xero" }, "last_synced_at": { "type": ["string", "null"], "format": "date-time", "description": "Last successful sync.", "example": "2026-10-08T14:30:00Z" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name the org gives the connection.", "example": "Northwind Xero" }, "external_account_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 255, "description": "Provider tenant, company or workspace id.", "example": "tenant-nwl" }, "connection_state": { "type": "string", "enum": ["Pending", "Connected", "Error", "Paused", "Disconnected"], "description": "Connection state; changes through the transitions action.", "example": "Connected" }, "credential_kind": { "type": ["string", "null"], "enum": ["OAuth Token", "API Key", "Service Account", null], "description": "Kind of the stored Vault credential.", "example": "OAuth Token" }, "credential_expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the stored credential expires.", "example": "2026-10-08T14:30:00Z" }, "last_error_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Rule code of the last connection error.", "example": "credential_refused" }, "last_error_message": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Provider message of the last connection error.", "example": "Xero refused the token." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "provider_code", "last_synced_at", "display_name", "external_account_id", "connection_state", "credential_kind", "credential_expires_at", "last_error_code", "last_error_message" ], "description": "An integration connection (Section 17). Credentials are stored in Supabase Vault through the credential action and never returned." }, "IntegrationCreate": { "type": "object", "properties": { "provider_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Provider.", "example": "xero" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name the org gives the connection.", "example": "Northwind Xero" }, "external_account_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 255, "description": "Provider tenant, company or workspace id.", "example": "tenant-nwl" } }, "required": ["provider_code", "display_name"], "description": "Fields accepted when creating a Integration." }, "IntegrationUpdate": { "type": "object", "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name the org gives the connection.", "example": "Northwind Xero" }, "external_account_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 255, "description": "Provider tenant, company or workspace id.", "example": "tenant-nwl" } }, "description": "Fields accepted when updating a Integration. Omitted fields are unchanged." }, "IntegrationTransition": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Pending", "Connected", "Error", "Paused", "Disconnected"], "description": "State the connection is in now (compare-and-set).", "example": "Connected" }, "next_state": { "type": "string", "enum": ["Pending", "Connected", "Error", "Paused", "Disconnected"], "description": "State to move to.", "example": "Connected" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the connection changes state.", "example": "Authorized in Xero." } }, "required": ["expected_state", "next_state", "reason"], "description": "A connection state change with compare-and-set." }, "IntegrationCredential": { "type": "object", "properties": { "secret": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "The provider secret or OAuth token set. Write-only: stored in Vault, never returned.", "example": "{\"access_token\":\"...\"}" }, "kind": { "type": "string", "enum": ["OAuth Token", "API Key", "Service Account"], "description": "Kind of secret.", "example": "OAuth Token" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the secret expires, when the provider says.", "example": "2026-10-08T14:30:00Z" } }, "required": ["secret", "kind"], "description": "A credential to store in Vault for a connection." }, "IntegrationSyncQueued": { "type": "object", "properties": { "sync_run_id": { "type": "string", "format": "uuid", "description": "Identifier of the sync run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["sync_run_id"], "description": "The queued sync run." }, "IntegrationSyncRequest": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "Ledger Export", "Payment Sync", "Calendar Sync", "File Import", "Notification Delivery", "Payroll Export", "Tracking Refresh", "Attendance Import" ], "description": "What to sync; must belong to the connection's category.", "example": "Ledger Export" }, "direction": { "type": "string", "enum": ["Inbound", "Outbound", "Two Way"], "description": "Direction of the sync.", "example": "Outbound" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["scope", "direction"], "description": "A sync run to queue. The Idempotency-Key makes queueing safe to repeat." }, "WebhookEndpointPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the webhook endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "events": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_]+\\.[a-z_]+$" }, "description": "Subscribed event names.", "example": ["record.state_changed", "po.approved"] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the endpoint is for.", "example": "Sync approved POs to the ERP." }, "disabled_at": { "type": ["string", "null"], "format": "date-time", "description": "When the endpoint was turned off; disabled endpoints get no new deliveries.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "url", "events", "description", "disabled_at" ], "description": "A webhook endpoint. Deliveries are signed with HMAC-SHA256 and retried for 72 hours." }, "WebhookEndpointUpdate": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "events": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_]+\\.[a-z_]+$" }, "description": "Subscribed event names.", "example": ["record.state_changed", "po.approved"] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the endpoint is for.", "example": "Sync approved POs to the ERP." }, "disabled_at": { "type": ["string", "null"], "format": "date-time", "description": "When the endpoint was turned off; disabled endpoints get no new deliveries.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a WebhookEndpoint. Omitted fields are unchanged." }, "WebhookEndpointSecret": { "type": "object", "properties": { "webhook_endpoint_id": { "type": "string", "format": "uuid", "description": "Identifier of the webhook endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "signing_secret": { "type": "string", "minLength": 1, "description": "The endpoint's signing secret. Shown once; it is stored in Vault and never read back.", "example": "whsec_5Jk2pQ8xL1nV7cR3" } }, "required": ["webhook_endpoint_id", "signing_secret"], "description": "A newly created webhook endpoint and its signing secret, shown once." }, "WebhookEndpointCreate": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "events": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_]+\\.[a-z_]+$" }, "description": "Subscribed event names.", "example": ["record.state_changed", "po.approved"] }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the endpoint is for.", "example": "Sync approved POs to the ERP." } }, "required": ["url", "events"], "description": "Fields accepted when creating a WebhookEndpoint." }, "WebhookDeliveryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the webhook delivery.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "webhook_endpoint_id": { "type": "string", "format": "uuid", "description": "Identifier of the endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "delivery_status": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Delivery status. A Title Case value from the lifecycle's database enum.", "example": "Delivered" }, "delivered_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was delivered.", "example": "2026-10-08T14:30:00Z" }, "domain_event_id": { "type": "string", "format": "uuid", "description": "Identifier of the domain event delivered; every attempt sends the same body built from it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "attempt_count": { "type": "integer", "minimum": 0, "description": "Attempts started.", "example": 1 }, "next_attempt_at": { "type": "string", "format": "date-time", "description": "When the dispatcher may try next.", "example": "2026-10-08T14:30:00Z" }, "last_attempt_at": { "type": ["string", "null"], "format": "date-time", "description": "When the latest attempt started.", "example": "2026-10-08T14:30:00Z" }, "last_response_status": { "type": ["integer", "null"], "minimum": 100, "description": "HTTP status of the latest response; null when no response arrived.", "example": 200 }, "last_error": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Network or HTTP error of the latest failed attempt.", "example": "Connection timed out." }, "replay_requested_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who replayed the event from Atlas.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "webhook_endpoint_id", "delivery_status", "delivered_at", "domain_event_id", "attempt_count", "next_attempt_at", "last_attempt_at", "last_response_status", "last_error", "replay_requested_by" ], "description": "A webhook delivery attempt, replayable from Atlas." }, "WebhookEventTypePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WebhookEventType": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Event name `{resource}.{event}`.", "example": "record.state_changed" }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "When it fires.", "example": "A record moved to another state." }, "subject": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Table whose rows the event describes.", "example": "purchase_orders" } }, "required": ["code", "description", "subject"], "description": "A webhook event from the domain event table." }, "SettingDefinitionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SettingDefinition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SettingDefinition": { "type": "object", "properties": { "setting_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Setting key.", "example": "finance.base_currency" }, "scope": { "$ref": "#/components/schemas/SettingScope" }, "value_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Value type.", "example": "string" }, "edit_capability": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Capability that edits it.", "example": "settings.finance.write" }, "overridable": { "type": "boolean", "description": "Whether a lower scope may override it.", "example": true } }, "required": ["setting_key", "scope", "value_type", "edit_capability", "overridable"], "description": "A setting generated from `settings.yaml`." }, "SettingScope": { "type": "string", "enum": ["Personal", "Project", "Team", "Workspace", "Organization", "Platform"], "description": "Scope a setting value applies to, most specific first (Section 4.5.6).", "example": "Organization" }, "SettingValuePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SettingValue" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SettingValue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the setting value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_type": { "$ref": "#/components/schemas/SettingScope" }, "scope_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "setting_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Setting key.", "example": "finance.base_currency" }, "value": { "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }], "description": "Typed value.", "example": "USD" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "scope_type", "scope_id", "setting_key", "value" ], "description": "A setting value at one scope. The most specific scope wins unless a lock applies." }, "SettingValueCreate": { "type": "object", "properties": { "scope_type": { "$ref": "#/components/schemas/SettingScope" }, "scope_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the scope row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "setting_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Setting key.", "example": "finance.base_currency" }, "value": { "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }], "description": "Typed value.", "example": "USD" } }, "required": ["scope_type", "setting_key", "value"], "description": "Fields accepted when creating a SettingValue." }, "SettingValueUpdate": { "type": "object", "properties": { "value": { "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }], "description": "Typed value.", "example": "USD" } }, "description": "Fields accepted when updating a SettingValue. Omitted fields are unchanged." }, "SettingLockPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SettingLock" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SettingLock": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the setting lock.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "setting_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Setting key.", "example": "security.mfa_required" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "setting_key" ], "description": "A lock that stops lower scopes from overriding a setting." }, "SettingLockCreate": { "type": "object", "properties": { "setting_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Setting key.", "example": "security.mfa_required" } }, "required": ["setting_key"], "description": "Fields accepted when creating a SettingLock." }, "AuditEventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the audit event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "action": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Action.", "example": "purchase_order.approved" }, "diff": { "type": "object", "additionalProperties": {}, "description": "Redacted audit diff.", "example": { "type": "doc" } }, "actor_kind": { "type": "string", "enum": ["Person", "Service", "System"], "description": "Who acted.", "example": "Person" }, "actor_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who acted, when a person acted.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject_table": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Table of the row acted on.", "example": "purchase_orders" }, "subject_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the row acted on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "actor_ip": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Client IP address of the request. Removed at redaction.", "example": "203.0.113.24" }, "user_agent": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Client user agent of the request. Removed at redaction.", "example": "Mozilla/5.0" }, "request_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "API request id, for correlating with logs.", "example": "req_01J9Z6" }, "redacted_at": { "type": ["string", "null"], "format": "date-time", "description": "When personal data in the event was redacted.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "action", "diff", "actor_kind", "actor_person_id", "subject_table", "subject_id", "actor_ip", "user_agent", "request_id", "redacted_at" ], "description": "An append-only compliance audit event, retained 7 years." }, "ConsentRecordPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentRecord" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ConsentRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the consent record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purpose_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Consent purpose.", "example": "marketing_email" }, "notice_version": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Version of the notice shown when consent was given.", "example": "2026-10-01" }, "source": { "type": "string", "enum": ["Web", "Mobile", "Email", "SMS", "Import", "Support"], "description": "Where consent was captured.", "example": "Web" }, "captured_at": { "type": "string", "format": "date-time", "description": "When consent was given, set by the database.", "example": "2026-10-08T14:30:00Z" }, "captured_ip": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Client IP address at capture, set by the database.", "example": "203.0.113.24" }, "withdrawn_at": { "type": ["string", "null"], "format": "date-time", "description": "When the person withdrew consent; null while it stands.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "created_at", "updated_at", "person_id", "purpose_code", "notice_version", "source", "captured_at", "captured_ip", "withdrawn_at" ], "description": "A consent given or withdrawn." }, "ConsentRecordCreate": { "type": "object", "properties": { "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purpose_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Consent purpose.", "example": "marketing_email" }, "notice_version": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Version of the notice shown when consent was given.", "example": "2026-10-01" }, "source": { "type": "string", "enum": ["Web", "Mobile", "Email", "SMS", "Import", "Support"], "description": "Where consent was captured.", "example": "Web" } }, "required": ["person_id", "purpose_code", "notice_version", "source"], "description": "Fields accepted when creating a ConsentRecord." }, "DsarRequestPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DsarRequest" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DsarRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the dsar request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "request_type": { "type": "string", "enum": [ "Access", "Rectification", "Erasure", "Restriction", "Portability", "Objection", "Opt Out of Sale" ], "description": "What the requester exercises.", "example": "Access" }, "dsar_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Request state. A Title Case value from the lifecycle's database enum.", "example": "In Review" }, "subject_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person the request is about, when they have an account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject_email": { "type": "string", "format": "email", "description": "Email the requester gave, used to verify identity and to reply.", "example": "alex.rivera@northwindlive.example" }, "details": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "What the requester asked for, in their words.", "example": "Send me my timesheets." }, "received_at": { "type": "string", "format": "date-time", "description": "When the request was received; the clock starts here.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "request_type", "dsar_state", "subject_person_id", "subject_email", "details", "received_at" ], "description": "A data subject access request." }, "DsarRequestCreate": { "type": "object", "properties": { "request_type": { "type": "string", "enum": [ "Access", "Rectification", "Erasure", "Restriction", "Portability", "Objection", "Opt Out of Sale" ], "description": "What the requester exercises.", "example": "Access" }, "subject_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person the request is about, when they have an account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject_email": { "type": "string", "format": "email", "description": "Email the requester gave, used to verify identity and to reply.", "example": "alex.rivera@northwindlive.example" }, "details": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "What the requester asked for, in their words.", "example": "Send me my timesheets." } }, "required": ["request_type", "subject_email"], "description": "Fields accepted when creating a DsarRequest." }, "RetentionPolicyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RetentionPolicy" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RetentionPolicy": { "type": "object", "properties": { "table_name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Table.", "example": "app.activity_events" }, "basis": { "type": ["string", "null"], "enum": ["Soft Deleted", "Age", null], "description": "What starts the retention clock.", "example": "Soft Deleted" }, "time_column": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Column that starts the clock.", "example": "deleted_at" }, "retention": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "How long rows are kept, as an interval.", "example": "7 years" }, "purge_method": { "type": ["string", "null"], "enum": ["Delete", "Drop Partition", "Account Lifecycle", null], "description": "How expired rows leave.", "example": "Delete" }, "redact_personal_data_after": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "When personal data in the table is redacted, if ever.", "example": "90 days" }, "rationale": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Why the period was chosen.", "example": "Tax records are kept seven years." } }, "required": [ "table_name", "basis", "time_column", "retention", "purge_method", "redact_personal_data_after", "rationale" ], "description": "Retention of soft-deleted rows per table." }, "OrgExportPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgExport" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrgExport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the org export.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "table_count": { "type": "integer", "minimum": 0, "description": "Tables in the archive.", "example": 412 }, "row_count": { "type": "integer", "minimum": 0, "description": "Rows across every table.", "example": 182340, "format": "int64" }, "file_count": { "type": "integer", "minimum": 0, "description": "Stored files included.", "example": 96 }, "manifest_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the archive's manifest.json, lowercase hex.", "example": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "table_count", "row_count", "file_count", "manifest_sha256" ], "description": "A full organization export." }, "OrgExportCreate": { "type": "object", "properties": { "table_count": { "type": "integer", "minimum": 0, "description": "Tables in the archive.", "example": 412 }, "row_count": { "type": "integer", "minimum": 0, "description": "Rows across every table.", "example": 182340, "format": "int64" }, "file_count": { "type": "integer", "minimum": 0, "description": "Stored files included.", "example": 96 }, "manifest_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the archive's manifest.json, lowercase hex.", "example": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } }, "required": ["table_count", "row_count", "file_count", "manifest_sha256"], "description": "Fields accepted when creating a OrgExport." }, "AiSettingsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiSettings" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AiSettings": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the ai settings.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "assistant_enabled": { "type": "boolean", "description": "Assistant.", "example": false }, "extraction_enabled": { "type": "boolean", "description": "Document extraction.", "example": false }, "drafting_enabled": { "type": "boolean", "description": "Drafting.", "example": false }, "plain_language_enabled": { "type": "boolean", "description": "Ask in plain language.", "example": false }, "summaries_enabled": { "type": "boolean", "description": "Summaries.", "example": false }, "mapping_enabled": { "type": "boolean", "description": "Mapping help.", "example": false } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "assistant_enabled", "extraction_enabled", "drafting_enabled", "plain_language_enabled", "summaries_enabled", "mapping_enabled" ], "description": "AI feature switches. Every feature is off until an Admin turns it on." }, "AiSettingsUpdate": { "type": "object", "properties": { "assistant_enabled": { "type": "boolean", "description": "Assistant.", "example": false }, "extraction_enabled": { "type": "boolean", "description": "Document extraction.", "example": false }, "drafting_enabled": { "type": "boolean", "description": "Drafting.", "example": false }, "plain_language_enabled": { "type": "boolean", "description": "Ask in plain language.", "example": false }, "summaries_enabled": { "type": "boolean", "description": "Summaries.", "example": false }, "mapping_enabled": { "type": "boolean", "description": "Mapping help.", "example": false } }, "description": "Fields accepted when updating a AiSettings. Omitted fields are unchanged." }, "AiSettingsSaveRequest": { "type": "object", "properties": { "assistant_enabled": { "type": "boolean", "description": "assistant switch.", "example": false }, "plain_language_enabled": { "type": "boolean", "description": "plain_language switch.", "example": false }, "extraction_enabled": { "type": "boolean", "description": "extraction switch.", "example": false }, "drafting_enabled": { "type": "boolean", "description": "drafting switch.", "example": false }, "summaries_enabled": { "type": "boolean", "description": "summaries switch.", "example": false }, "mapping_enabled": { "type": "boolean", "description": "mapping switch.", "example": false } }, "required": [ "assistant_enabled", "plain_language_enabled", "extraction_enabled", "drafting_enabled", "summaries_enabled", "mapping_enabled" ], "description": "Every AI feature switch." }, "ReportDefinitionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportDefinition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReportDefinition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Report name.", "example": "Labor by Department" }, "source_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Source.", "example": "crew" }, "chart": { "type": "string", "enum": ["Table", "Bar", "Line", "Area", "Pie", "Number"], "description": "Chart type.", "example": "Table" }, "group_by_field": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field the rows are grouped by.", "example": "dept_code" }, "shared": { "type": "boolean", "description": "Whether everyone who may read the source sees it.", "example": false }, "custom_object_type_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the custom object type, when the source is custom_object.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership that owns the report.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "source_code", "chart", "group_by_field", "shared", "custom_object_type_id", "membership_id" ], "description": "A report definition with NULL-aware aggregates. Reports respect RLS and masking." }, "ReportDefinitionCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Report name.", "example": "Labor by Department" }, "source_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Source.", "example": "crew" }, "chart": { "type": "string", "enum": ["Table", "Bar", "Line", "Area", "Pie", "Number"], "description": "Chart type.", "example": "Table" }, "group_by_field": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field the rows are grouped by.", "example": "dept_code" }, "shared": { "type": "boolean", "description": "Whether everyone who may read the source sees it.", "example": false }, "custom_object_type_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the custom object type, when the source is custom_object.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name", "source_code"], "description": "Fields accepted when creating a ReportDefinition." }, "ReportDefinitionUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Report name.", "example": "Labor by Department" }, "source_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Source.", "example": "crew" }, "chart": { "type": "string", "enum": ["Table", "Bar", "Line", "Area", "Pie", "Number"], "description": "Chart type.", "example": "Table" }, "group_by_field": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field the rows are grouped by.", "example": "dept_code" }, "shared": { "type": "boolean", "description": "Whether everyone who may read the source sees it.", "example": false }, "custom_object_type_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the custom object type, when the source is custom_object.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a ReportDefinition. Omitted fields are unchanged." }, "ReportRunPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportRun" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReportRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the report run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "report_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "export_format": { "$ref": "#/components/schemas/ExportFormat" }, "run_status": { "type": "string", "enum": ["Queued", "Running", "Succeeded", "Failed"], "description": "Run status.", "example": "Queued" }, "finished_at": { "type": ["string", "null"], "format": "date-time", "description": "When the run finished.", "example": "2026-10-08T14:30:00Z" }, "run_for_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership the run is for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "started_at": { "type": ["string", "null"], "format": "date-time", "description": "When the run started.", "example": "2026-10-08T14:30:00Z" }, "row_count": { "type": ["integer", "null"], "minimum": 0, "description": "Rows in the output.", "example": 42 }, "unpriced_count": { "type": ["integer", "null"], "minimum": 0, "description": "Unpriced inputs left out of the money totals.", "example": 2 }, "last_error": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Why the run failed.", "example": "The source was removed." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "report_definition_id", "export_format", "run_status", "finished_at", "run_for_membership_id", "started_at", "row_count", "unpriced_count", "last_error" ], "description": "A run of a report definition." }, "ExportFormat": { "type": "string", "enum": ["CSV", "XLSX", "PDF"], "description": "Export file format.", "example": "CSV" }, "ReportRunCreate": { "type": "object", "properties": { "report_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "export_format": { "$ref": "#/components/schemas/ExportFormat" } }, "required": ["report_definition_id", "export_format"], "description": "Fields accepted when creating a ReportRun." }, "ReportSchedulePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportSchedule" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReportSchedule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "report_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "cadence": { "type": "string", "enum": ["Daily", "Weekly", "Monthly"], "description": "How often the report is sent.", "example": "Daily" }, "local_hour": { "type": "integer", "minimum": 0, "description": "Local hour of delivery, 0 to 23.", "example": 8 }, "weekday": { "type": ["integer", "null"], "minimum": 1, "description": "ISO weekday (1 Monday) of a weekly delivery.", "example": 1 }, "month_day": { "type": ["integer", "null"], "minimum": 1, "description": "Day of the month (1 to 28) of a monthly delivery.", "example": 1 }, "export_format": { "type": "string", "enum": ["CSV", "XLSX", "PDF"], "description": "File format attached: CSV, XLSX or PDF.", "example": "CSV" }, "next_run_at": { "type": "string", "format": "date-time", "description": "Next delivery time, kept by the database.", "example": "2026-10-08T14:30:00Z" }, "paused_at": { "type": ["string", "null"], "format": "date-time", "description": "When the schedule was paused; null while it runs.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "report_definition_id", "time_zone", "cadence", "local_hour", "weekday", "month_day", "export_format", "next_run_at", "paused_at" ], "description": "A scheduled email delivery of a report to org members only." }, "ReportScheduleCreate": { "type": "object", "properties": { "report_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "cadence": { "type": "string", "enum": ["Daily", "Weekly", "Monthly"], "description": "How often the report is sent.", "example": "Daily" }, "local_hour": { "type": "integer", "minimum": 0, "description": "Local hour of delivery, 0 to 23.", "example": 8 }, "weekday": { "type": ["integer", "null"], "minimum": 1, "description": "ISO weekday (1 Monday) of a weekly delivery.", "example": 1 }, "month_day": { "type": ["integer", "null"], "minimum": 1, "description": "Day of the month (1 to 28) of a monthly delivery.", "example": 1 }, "export_format": { "type": "string", "enum": ["CSV", "XLSX", "PDF"], "description": "File format attached: CSV, XLSX or PDF.", "example": "CSV" }, "paused_at": { "type": ["string", "null"], "format": "date-time", "description": "When the schedule was paused; null while it runs.", "example": "2026-10-08T14:30:00Z" } }, "required": ["report_definition_id", "time_zone", "cadence", "local_hour", "export_format"], "description": "Fields accepted when creating a ReportSchedule." }, "ReportScheduleUpdate": { "type": "object", "properties": { "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone the local time was entered in.", "example": "America/New_York" }, "cadence": { "type": "string", "enum": ["Daily", "Weekly", "Monthly"], "description": "How often the report is sent.", "example": "Daily" }, "local_hour": { "type": "integer", "minimum": 0, "description": "Local hour of delivery, 0 to 23.", "example": 8 }, "weekday": { "type": ["integer", "null"], "minimum": 1, "description": "ISO weekday (1 Monday) of a weekly delivery.", "example": 1 }, "month_day": { "type": ["integer", "null"], "minimum": 1, "description": "Day of the month (1 to 28) of a monthly delivery.", "example": 1 }, "export_format": { "type": "string", "enum": ["CSV", "XLSX", "PDF"], "description": "File format attached: CSV, XLSX or PDF.", "example": "CSV" }, "paused_at": { "type": ["string", "null"], "format": "date-time", "description": "When the schedule was paused; null while it runs.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a ReportSchedule. Omitted fields are unchanged." }, "DashboardPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dashboard" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Dashboard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Dashboard name.", "example": "Show Week" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the membership that owns the dashboard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "team_id", "membership_id" ], "description": "A grid of report tiles, saved per user or per team." }, "DashboardCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Dashboard name.", "example": "Show Week" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name"], "description": "Fields accepted when creating a Dashboard." }, "DashboardUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Dashboard name.", "example": "Show Week" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a Dashboard. Omitted fields are unchanged." }, "DashboardTilePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardTile" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DashboardTile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard tile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "dashboard_id": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "report_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grid_column": { "type": "integer", "minimum": 1, "description": "Leftmost column, 1 to 12.", "example": 1 }, "grid_row": { "type": "integer", "minimum": 1, "description": "Top row, from 1.", "example": 1 }, "column_span": { "type": "integer", "minimum": 1, "description": "Columns spanned, 1 to 12.", "example": 6 }, "row_span": { "type": "integer", "minimum": 1, "description": "Rows spanned, 1 to 12.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "dashboard_id", "report_definition_id", "grid_column", "grid_row", "column_span", "row_span" ], "description": "A report tile on a dashboard." }, "DashboardTileCreate": { "type": "object", "properties": { "dashboard_id": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "report_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grid_column": { "type": "integer", "minimum": 1, "description": "Leftmost column, 1 to 12.", "example": 1 }, "grid_row": { "type": "integer", "minimum": 1, "description": "Top row, from 1.", "example": 1 }, "column_span": { "type": "integer", "minimum": 1, "description": "Columns spanned, 1 to 12.", "example": 6 }, "row_span": { "type": "integer", "minimum": 1, "description": "Rows spanned, 1 to 12.", "example": 1 } }, "required": [ "dashboard_id", "report_definition_id", "grid_column", "grid_row", "column_span", "row_span" ], "description": "Fields accepted when creating a DashboardTile." }, "DashboardTileUpdate": { "type": "object", "properties": { "report_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grid_column": { "type": "integer", "minimum": 1, "description": "Leftmost column, 1 to 12.", "example": 1 }, "grid_row": { "type": "integer", "minimum": 1, "description": "Top row, from 1.", "example": 1 }, "column_span": { "type": "integer", "minimum": 1, "description": "Columns spanned, 1 to 12.", "example": 6 }, "row_span": { "type": "integer", "minimum": 1, "description": "Rows spanned, 1 to 12.", "example": 1 } }, "description": "Fields accepted when updating a DashboardTile. Omitted fields are unchanged." }, "ReportRowPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportRow" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReportRow": { "type": "object", "properties": { "dimension": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Grouping value, such as a GL account or URID.", "example": "5400" }, "budget": { "$ref": "#/components/schemas/MoneyTotal" }, "actual": { "$ref": "#/components/schemas/MoneyTotal" } }, "required": ["dimension", "budget", "actual"], "description": "A row of a built-in analytics report. Money columns are NULL-aware totals." }, "ReportMetricRowPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportMetricRow" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReportMetricRow": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Grouping value: a project key, a project key and gate, or a severity.", "example": "NWL" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the row is about, when it is about one.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "measure": { "type": "string", "pattern": "^[a-z][a-z_]*$", "description": "What is measured: worked_hours, timesheets and open_entries (labor), incidents and open_incidents (incident rates), blocking_met, blocking_total, other_met, other_total and ready (gate readiness).", "example": "worked_hours" }, "unit": { "type": "string", "enum": ["Hours", "Count"], "description": "Unit of the value.", "example": "Hours" }, "value": { "type": "number", "description": "The measure: hours to two decimals, or a whole count (ready is 1 or 0).", "example": 312.5 } }, "required": ["dimension", "project_id", "measure", "unit", "value"], "description": "One measure of a built-in report row, in hours or a count. Reports that total money answer ReportRow instead." }, "CustomObjectTypePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomObjectType" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CustomObjectType": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object type.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "object_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Object key used in the route.", "example": "sponsor_activation" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Title Case label.", "example": "Sponsor Activation" }, "icon": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Icon name.", "example": "sparkles" }, "default_view": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Default view type.", "example": "table" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "object_key", "label", "icon", "default_view" ], "description": "A custom object type with its own API routes at `/objects/{objectKey}`." }, "CustomObjectTypeCreate": { "type": "object", "properties": { "object_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Object key used in the route.", "example": "sponsor_activation" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Title Case label.", "example": "Sponsor Activation" }, "icon": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Icon name.", "example": "sparkles" }, "default_view": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Default view type.", "example": "table" } }, "required": ["object_key", "label", "icon"], "description": "Fields accepted when creating a CustomObjectType." }, "CustomObjectTypeUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Title Case label.", "example": "Sponsor Activation" }, "icon": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Icon name.", "example": "sparkles" }, "default_view": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Default view type.", "example": "table" } }, "description": "Fields accepted when updating a CustomObjectType. Omitted fields are unchanged." }, "CustomObjectFieldPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomObjectField" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CustomObjectField": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object field.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "custom_object_type_id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object type.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "field_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field key.", "example": "activation_date" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Field label.", "example": "Activation Date" }, "data_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Data type.", "example": "date" }, "required": { "type": "boolean", "description": "Whether a value is required.", "example": false }, "filterable": { "type": "boolean", "description": "Whether the field gets a partial index.", "example": true }, "sort_order": { "type": "integer", "minimum": 0, "description": "Position in forms and tables.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "custom_object_type_id", "field_key", "label", "data_type", "required", "filterable", "sort_order" ], "description": "A typed field of a custom object type." }, "CustomObjectFieldCreate": { "type": "object", "properties": { "custom_object_type_id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object type.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "field_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field key.", "example": "activation_date" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Field label.", "example": "Activation Date" }, "data_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Data type.", "example": "date" }, "required": { "type": "boolean", "description": "Whether a value is required.", "example": false }, "filterable": { "type": "boolean", "description": "Whether the field gets a partial index.", "example": true }, "sort_order": { "type": "integer", "minimum": 0, "description": "Position in forms and tables.", "example": 1 } }, "required": ["custom_object_type_id", "field_key", "label", "data_type", "sort_order"], "description": "Fields accepted when creating a CustomObjectField." }, "CustomObjectFieldUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Field label.", "example": "Activation Date" }, "data_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Data type.", "example": "date" }, "required": { "type": "boolean", "description": "Whether a value is required.", "example": false }, "filterable": { "type": "boolean", "description": "Whether the field gets a partial index.", "example": true }, "sort_order": { "type": "integer", "minimum": 0, "description": "Position in forms and tables.", "example": 1 } }, "description": "Fields accepted when updating a CustomObjectField. Omitted fields are unchanged." }, "CustomObjectRecordPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomObjectRecord" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CustomObjectRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Record title.", "example": "Harbor Lounge Activation" }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Field values keyed by field key. Stored normalized in `custom_object_values`.", "example": { "activation_date": "2026-10-08" } }, "custom_object_type_id": { "type": "string", "format": "uuid", "description": "Identifier of the object type the record is an instance of.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "title", "values", "custom_object_type_id" ], "description": "A record of a custom object. Values are stored one row per field, never as JSON." }, "CustomObjectRecordCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Record title.", "example": "Harbor Lounge Activation" }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Field values keyed by field key. Stored normalized in `custom_object_values`.", "example": { "activation_date": "2026-10-08" } } }, "required": ["title", "values"], "description": "Fields accepted when creating a CustomObjectRecord." }, "CustomObjectRecordUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Record title.", "example": "Harbor Lounge Activation" }, "values": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Field values keyed by field key. Stored normalized in `custom_object_values`.", "example": { "activation_date": "2026-10-08" } } }, "description": "Fields accepted when updating a CustomObjectRecord. Omitted fields are unchanged." }, "CustomObjectRelationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomObjectRelation" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CustomObjectRelation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object relation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "from_record_id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object record the link starts from.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "relation_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Name of the relation, such as sponsor or venue.", "example": "sponsor" }, "to_custom_record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked custom object record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked counterparty organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "from_record_id", "relation_key", "to_custom_record_id", "to_record_id", "to_project_id", "to_counterparty_id", "to_person_id" ], "description": "A relation from a custom object record to another record." }, "CustomObjectRelationCreate": { "type": "object", "properties": { "from_record_id": { "type": "string", "format": "uuid", "description": "Identifier of the custom object record the link starts from.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "relation_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Name of the relation, such as sponsor or venue.", "example": "sponsor" }, "to_custom_record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked custom object record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked counterparty organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the linked person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["from_record_id", "relation_key"], "description": "Fields accepted when creating a CustomObjectRelation." }, "CustomFieldDefinitionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDefinition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CustomFieldDefinition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the custom field definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "target_table": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Table the field extends.", "example": "app.vendors" }, "field_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field key.", "example": "union_signatory" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Label.", "example": "Union Signatory" }, "data_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Data type.", "example": "boolean" }, "required": { "type": "boolean", "description": "True when forms require a value.", "example": false }, "filterable": { "type": "boolean", "description": "True when views filter on the field; it adds a partial index.", "example": false }, "sort_order": { "type": "integer", "minimum": 0, "description": "Position in forms.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "target_table", "field_key", "label", "data_type", "required", "filterable", "sort_order" ], "description": "A custom field on a built-in resource." }, "CustomFieldDefinitionCreate": { "type": "object", "properties": { "target_table": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Table the field extends.", "example": "app.vendors" }, "field_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field key.", "example": "union_signatory" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Label.", "example": "Union Signatory" }, "data_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Data type.", "example": "boolean" }, "required": { "type": "boolean", "description": "True when forms require a value.", "example": false }, "filterable": { "type": "boolean", "description": "True when views filter on the field; it adds a partial index.", "example": false }, "sort_order": { "type": "integer", "minimum": 0, "description": "Position in forms.", "example": 1 } }, "required": ["target_table", "field_key", "label", "data_type", "sort_order"], "description": "Fields accepted when creating a CustomFieldDefinition." }, "CustomFieldDefinitionUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Label.", "example": "Union Signatory" }, "data_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Data type.", "example": "boolean" }, "required": { "type": "boolean", "description": "True when forms require a value.", "example": false }, "filterable": { "type": "boolean", "description": "True when views filter on the field; it adds a partial index.", "example": false }, "sort_order": { "type": "integer", "minimum": 0, "description": "Position in forms.", "example": 1 } }, "description": "Fields accepted when updating a CustomFieldDefinition. Omitted fields are unchanged." }, "CustomFieldValuePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CustomFieldValue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the custom field value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "custom_field_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the custom field definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value_text": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Typed value.", "example": true }, "target_id": { "type": "string", "format": "uuid", "description": "Identifier of the row of the field's target table the value belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value_number": { "type": ["number", "null"], "description": "Number value.", "example": 12.5 }, "value_money_minor": { "type": ["integer", "null"], "description": "Money value in minor units of value_currency. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 250000, "format": "int64" }, "value_currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of a money value.", "example": "USD" }, "value_date": { "type": ["string", "null"], "format": "date", "description": "Date value.", "example": "2026-10-08" }, "value_timestamp": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp value.", "example": "2026-10-08T14:30:00Z" }, "value_boolean": { "type": ["boolean", "null"], "description": "Boolean value.", "example": true }, "value_choice_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the chosen option of the field.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "custom_field_definition_id", "value_text", "target_id", "value_number", "value_money_minor", "value_currency", "value_date", "value_timestamp", "value_boolean", "value_choice_id", "value_person_id" ], "description": "A custom field value for one row." }, "CustomFieldValueCreate": { "type": "object", "properties": { "custom_field_definition_id": { "type": "string", "format": "uuid", "description": "Identifier of the custom field definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value_text": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Typed value.", "example": true }, "target_id": { "type": "string", "format": "uuid", "description": "Identifier of the row of the field's target table the value belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value_number": { "type": ["number", "null"], "description": "Number value.", "example": 12.5 }, "value_money_minor": { "type": ["integer", "null"], "description": "Money value in minor units of value_currency. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 250000, "format": "int64" }, "value_currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of a money value.", "example": "USD" }, "value_date": { "type": ["string", "null"], "format": "date", "description": "Date value.", "example": "2026-10-08" }, "value_timestamp": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp value.", "example": "2026-10-08T14:30:00Z" }, "value_boolean": { "type": ["boolean", "null"], "description": "Boolean value.", "example": true }, "value_choice_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the chosen option of the field.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["custom_field_definition_id", "target_id"], "description": "Fields accepted when creating a CustomFieldValue." }, "CustomFieldValueUpdate": { "type": "object", "properties": { "value_text": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Typed value.", "example": true }, "value_number": { "type": ["number", "null"], "description": "Number value.", "example": 12.5 }, "value_money_minor": { "type": ["integer", "null"], "description": "Money value in minor units of value_currency. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 250000, "format": "int64" }, "value_currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of a money value.", "example": "USD" }, "value_date": { "type": ["string", "null"], "format": "date", "description": "Date value.", "example": "2026-10-08" }, "value_timestamp": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp value.", "example": "2026-10-08T14:30:00Z" }, "value_boolean": { "type": ["boolean", "null"], "description": "Boolean value.", "example": true }, "value_choice_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the chosen option of the field.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "value_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a CustomFieldValue. Omitted fields are unchanged." }, "OrgStateLabelPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgStateLabel" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrgStateLabel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the org state label.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Record state relabeled. A Title Case value from the lifecycle's database enum.", "example": "In Review" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Display label.", "example": "With Client" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "record_state", "label" ], "description": "An org's display relabel of a record state. It never mints a new lifecycle." }, "OrgStateLabelCreate": { "type": "object", "properties": { "record_state": { "type": "string", "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Record state relabeled. A Title Case value from the lifecycle's database enum.", "example": "In Review" }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Display label.", "example": "With Client" } }, "required": ["record_state", "label"], "description": "Fields accepted when creating a OrgStateLabel." }, "OrgStateLabelUpdate": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Display label.", "example": "With Client" } }, "description": "Fields accepted when updating a OrgStateLabel. Omitted fields are unchanged." }, "ImportJobPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJob" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ImportJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the import job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "import_mapping_profile_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the saved mapping profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "target_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Import target the rows are written to.", "example": "vendors" }, "source": { "type": "string", "enum": ["CSV", "XLSX", "XLS", "Google Sheets"], "description": "Source format.", "example": "CSV" }, "original_filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "File name as uploaded.", "example": "vendors-2026.xlsx" }, "storage_object_path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Object path of the uploaded file in the tenant import bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/imports/vendors-2026.xlsx" }, "import_status": { "type": "string", "enum": [ "Uploaded", "Detected", "Mapped", "Validated", "Committing", "Committed", "Undone", "Failed", "Canceled" ], "description": "Wizard progress.", "example": "Uploaded" }, "mapping_confirmed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the person confirmed every column mapping; nothing is validated before it.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "import_mapping_profile_id", "target_code", "source", "original_filename", "storage_object_path", "import_status", "mapping_confirmed_at" ], "description": "A spreadsheet import through detect, map, validate, deduplicate, dry run and commit." }, "ImportJobCreate": { "type": "object", "properties": { "import_mapping_profile_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the saved mapping profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "target_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Import target the rows are written to.", "example": "vendors" }, "source": { "type": "string", "enum": ["CSV", "XLSX", "XLS", "Google Sheets"], "description": "Source format.", "example": "CSV" }, "original_filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "File name as uploaded.", "example": "vendors-2026.xlsx" }, "storage_object_path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Object path of the uploaded file in the tenant import bucket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/imports/vendors-2026.xlsx" } }, "required": ["target_code", "source", "original_filename", "storage_object_path"], "description": "Fields accepted when creating a ImportJob." }, "ImportDryRun": { "type": "object", "properties": { "creates": { "type": "integer", "minimum": 0, "description": "Rows that will create a record.", "example": 12 }, "updates": { "type": "integer", "minimum": 0, "description": "Rows that will update the record their strong key matched.", "example": 3 }, "merges": { "type": "integer", "minimum": 0, "description": "Rows that will merge into a record a person chose.", "example": 1 }, "refusals": { "type": "integer", "minimum": 0, "description": "Rows that are Invalid or Refused.", "example": 2 }, "skipped": { "type": "integer", "minimum": 0, "description": "Rows skipped.", "example": 0 }, "pending_reviews": { "type": "integer", "minimum": 0, "description": "Possible duplicates still waiting for a person.", "example": 0 } }, "required": ["creates", "updates", "merges", "refusals", "skipped", "pending_reviews"], "description": "What committing an import would write (Section 4.6.2 step 6)." }, "ImportBatchPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImportBatch" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ImportBatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the import batch.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "import_job_id": { "type": "string", "format": "uuid", "description": "Identifier of the import job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "committed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the batch was committed.", "example": "2026-10-08T14:30:00Z" }, "undone_at": { "type": ["string", "null"], "format": "date-time", "description": "When the batch was undone.", "example": "2026-10-08T14:30:00Z" }, "undo_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Why the batch was undone.", "example": "Wrong sheet imported." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "import_job_id", "committed_at", "undone_at", "undo_reason" ], "description": "A committed import batch. It can be undone within 7 days unless later edits depend on it." }, "ImportRowResultPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImportRowResult" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ImportRowResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the import row result.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "import_job_id": { "type": "string", "format": "uuid", "description": "Identifier of the import job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "row_state": { "$ref": "#/components/schemas/ImportRowState" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Why the row is invalid or refused.", "example": "Unknown counterparty type." }, "import_batch_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the batch that wrote the row; set exactly when the row is written.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "sheet_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Source sheet.", "example": "Vendors" }, "row_number": { "type": "integer", "minimum": 1, "description": "One-based row number in the sheet, as the person sees it.", "example": 2 }, "target_table": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Table the row was written to.", "example": "records" }, "target_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the row written, created, updated or merged into.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "write_action": { "type": ["string", "null"], "enum": ["Created", "Updated", "Merged", null], "description": "What the write did.", "example": "Created" }, "before_image": { "type": ["object", "null"], "additionalProperties": {}, "description": "The columns an update or merge changed, as they were before the write; undo restores them.", "example": { "type": "doc" } }, "undo_outcome": { "type": ["string", "null"], "enum": ["Reverted", "Kept", null], "description": "Outcome when the batch was undone.", "example": "Reverted" }, "undo_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Why a row was kept: the later edit or the dependent row.", "example": "Edited after the import." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "import_job_id", "row_state", "reason", "import_batch_id", "sheet_name", "row_number", "target_table", "target_id", "write_action", "before_image", "undo_outcome", "undo_reason" ], "description": "The validation result of one imported row, with a reason per cell." }, "ImportRowState": { "type": "string", "enum": ["Valid", "Invalid", "Written", "Refused", "Skipped"], "description": "Import row result state.", "example": "Valid" }, "ImportMappingProfilePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImportMappingProfile" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ImportMappingProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the import mapping profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Profile name.", "example": "Vendor List From Accounting" }, "target_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Import target the profile maps onto.", "example": "vendors" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "target_code" ], "description": "A saved column-to-field mapping for one-click repeat imports." }, "ImportMappingProfileCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Profile name.", "example": "Vendor List From Accounting" }, "target_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Import target the profile maps onto.", "example": "vendors" } }, "required": ["name", "target_code"], "description": "Fields accepted when creating a ImportMappingProfile." }, "ImportMappingProfileUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Profile name.", "example": "Vendor List From Accounting" }, "target_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Import target the profile maps onto.", "example": "vendors" } }, "description": "Fields accepted when updating a ImportMappingProfile. Omitted fields are unchanged." }, "MergeReviewPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MergeReview" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MergeReview": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the merge review.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "similarity": { "type": "number", "description": "Similarity score, 0.85 or higher.", "example": 0.91 }, "decision": { "type": ["string", "null"], "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Reviewer decision. A Title Case value from the lifecycle's database enum.", "example": "Merge" }, "import_row_result_id": { "type": "string", "format": "uuid", "description": "Identifier of the import row that matched.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "candidate_table": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Table of the existing row.", "example": "records" }, "candidate_id": { "type": "string", "format": "uuid", "description": "Identifier of the existing row it may duplicate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who decided, set from the session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_at": { "type": ["string", "null"], "format": "date-time", "description": "When they decided, set by the database.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "similarity", "decision", "import_row_result_id", "candidate_table", "candidate_id", "decided_by", "decided_at" ], "description": "A fuzzy duplicate awaiting review. Fuzzy matches never merge automatically." }, "MergeReviewUpdate": { "type": "object", "properties": { "decision": { "type": ["string", "null"], "pattern": "^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$", "description": "Reviewer decision. A Title Case value from the lifecycle's database enum.", "example": "Merge" } }, "description": "Fields accepted when updating a MergeReview. Omitted fields are unchanged." }, "ExportJobPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportJob" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ExportJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the export job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "source_label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What is exported, as a saved view or report URN.", "example": "urn:xpms:saved_view:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "export_format": { "$ref": "#/components/schemas/ExportFormat" }, "classification": { "$ref": "#/components/schemas/Classification" }, "watermark": { "type": "boolean", "description": "True for Confidential and Restricted exports: PDFs and images carry the viewer email and time.", "example": false }, "export_status": { "type": "string", "enum": ["Queued", "Rendering", "Ready", "Failed", "Expired"], "description": "Export progress.", "example": "Queued" }, "storage_object_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 1024, "description": "Object path of the file once ready.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/exports/vendors.csv" }, "row_count": { "type": ["integer", "null"], "minimum": 0, "description": "Rows exported.", "example": 120 }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the download link stops working.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "source_label", "export_format", "classification", "watermark", "export_status", "storage_object_path", "row_count", "expires_at" ], "description": "An export of a list or report, subject to data loss prevention rules." }, "ExportJobCreate": { "type": "object", "properties": { "source_label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What is exported, as a saved view or report URN.", "example": "urn:xpms:saved_view:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "export_format": { "$ref": "#/components/schemas/ExportFormat" }, "columns": { "type": "array", "items": { "type": "string", "pattern": "^app\\.[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$", "description": "A column as app.table.column.", "example": "app.vendors.name" }, "minItems": 1, "description": "Columns the export contains, as app.table.column." } }, "required": ["source_label", "export_format", "columns"], "description": "Fields accepted when creating a ExportJob." }, "SavedViewPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedView" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SavedView": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the saved view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "View name.", "example": "Blocked Permits This Month" }, "view_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "View type from `views.yaml`.", "example": "table" }, "shared": { "type": "boolean", "description": "Whether the view is shared with the org.", "example": false }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who owns the view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "collection_key": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Collection the view shows, such as records or objects/sponsors.", "example": "records" }, "group_by_field": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field rows are grouped by, if any.", "example": "record_state" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "view_type", "shared", "membership_id", "collection_key", "group_by_field" ], "description": "A saved view of a collection: filters, sort, grouping and view type." }, "SavedViewCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "View name.", "example": "Blocked Permits This Month" }, "view_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "View type from `views.yaml`.", "example": "table" }, "shared": { "type": "boolean", "description": "Whether the view is shared with the org.", "example": false }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who owns the view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "collection_key": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Collection the view shows, such as records or objects/sponsors.", "example": "records" }, "group_by_field": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field rows are grouped by, if any.", "example": "record_state" } }, "required": ["name", "view_type", "membership_id", "collection_key"], "description": "Fields accepted when creating a SavedView." }, "SavedViewUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "View name.", "example": "Blocked Permits This Month" }, "view_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "View type from `views.yaml`.", "example": "table" }, "shared": { "type": "boolean", "description": "Whether the view is shared with the org.", "example": false }, "group_by_field": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Field rows are grouped by, if any.", "example": "record_state" } }, "description": "Fields accepted when updating a SavedView. Omitted fields are unchanged." }, "ApprovalPolicyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalPolicy" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ApprovalPolicy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Policy name.", "example": "PO Over Limit" }, "document_type": { "type": "string", "enum": [ "Purchase Order", "Change Order", "Expense", "Invoice Approval", "Payroll Run", "Requisition" ], "description": "Spend document type the policy gates.", "example": "Purchase Order" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the policy is for.", "example": "Every purchase order goes to finance." }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of applies_above_minor; null for every amount.", "example": "USD" }, "applies_above_minor": { "type": ["integer", "null"], "description": "The policy applies above this amount in currency_code, and to every amount in another currency; null for every document of the type. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1000000, "format": "int64" }, "policy_state": { "type": "string", "enum": ["Draft", "Active", "Retired"], "description": "Policy state.", "example": "Active" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "document_type", "description", "currency_code", "applies_above_minor", "policy_state" ], "description": "An approval policy with ordered steps." }, "ApprovalPolicyCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Policy name.", "example": "PO Over Limit" }, "document_type": { "type": "string", "enum": [ "Purchase Order", "Change Order", "Expense", "Invoice Approval", "Payroll Run", "Requisition" ], "description": "Spend document type the policy gates.", "example": "Purchase Order" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the policy is for.", "example": "Every purchase order goes to finance." }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of applies_above_minor; null for every amount.", "example": "USD" }, "applies_above_minor": { "type": ["integer", "null"], "description": "The policy applies above this amount in currency_code, and to every amount in another currency; null for every document of the type. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1000000, "format": "int64" } }, "required": ["name", "document_type"], "description": "Fields accepted when creating a ApprovalPolicy." }, "ApprovalPolicyUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Policy name.", "example": "PO Over Limit" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What the policy is for.", "example": "Every purchase order goes to finance." }, "currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of applies_above_minor; null for every amount.", "example": "USD" }, "applies_above_minor": { "type": ["integer", "null"], "description": "The policy applies above this amount in currency_code, and to every amount in another currency; null for every document of the type. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 1000000, "format": "int64" } }, "description": "Fields accepted when updating a ApprovalPolicy. Omitted fields are unchanged." }, "ApprovalPolicyTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Draft", "Active", "Retired"], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Draft" }, "to_state": { "type": "string", "enum": ["Draft", "Active", "Retired"], "description": "Target state.", "example": "Active" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "ApprovalInstancePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalInstance" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ApprovalInstance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the approval instance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approval_policy_id": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "requested_by": { "type": "string", "format": "uuid", "description": "Identifier of the requester.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approval_state": { "type": "string", "enum": ["In Review", "Approved", "Rejected", "Canceled"], "description": "Approval state.", "example": "In Review" }, "document_type": { "type": "string", "enum": [ "Purchase Order", "Change Order", "Expense", "Invoice Approval", "Payroll Run", "Requisition" ], "description": "Spend document type.", "example": "Purchase Order" }, "document_id": { "type": "string", "format": "uuid", "description": "Identifier of the spend document submitted for approval.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject_table": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Table of the document.", "example": "purchase_orders" }, "subject_reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "The document's own number or name.", "example": "17" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "amount_minor": { "type": ["integer", "null"], "description": "Amount submitted; the approval covers the document while its amount stays at or below it. Never null: an unpriced document is not submitted. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 4000000, "format": "int64" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the amount.", "example": "USD" }, "current_step": { "type": "integer", "minimum": 1, "description": "Step the approval waits on; the last step once decided.", "example": 1 }, "decided_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was approved, rejected or canceled.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "approval_policy_id", "requested_by", "approval_state", "document_type", "document_id", "subject_table", "subject_reference", "project_id", "amount_minor", "currency_code", "current_step", "decided_at" ], "description": "An approval in flight for one subject." }, "ApprovalInstanceCreate": { "type": "object", "properties": { "document_type": { "type": "string", "enum": [ "Purchase Order", "Change Order", "Expense", "Invoice Approval", "Payroll Run", "Requisition" ], "description": "Spend document type.", "example": "Purchase Order" }, "document_id": { "type": "string", "format": "uuid", "description": "Identifier of the spend document submitted for approval.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["document_type", "document_id"], "description": "Fields accepted when creating a ApprovalInstance." }, "ApprovalCancelRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the approval is withdrawn.", "example": "Submitted against the wrong order." } }, "required": ["reason"], "description": "Request to the approval is withdrawn." }, "ApprovalDecisionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalDecision" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ApprovalDecision": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the approval decision.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approval_instance_id": { "type": "string", "format": "uuid", "description": "Identifier of the approval instance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approved": { "type": "boolean", "description": "Whether the step is approved.", "example": true }, "comment": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Decision comment.", "example": "Within budget." }, "approver_id": { "type": "string", "format": "uuid", "description": "Identifier of the approver.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_at": { "type": "string", "format": "date-time", "description": "When it was decided.", "example": "2026-10-08T14:30:00Z" }, "step_order": { "type": "integer", "minimum": 1, "description": "Step decided.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "approval_instance_id", "approved", "comment", "approver_id", "decided_at", "step_order" ], "description": "A decision by an eligible approver, never the requester." }, "ApprovalDecisionCreate": { "type": "object", "properties": { "approval_instance_id": { "type": "string", "format": "uuid", "description": "Identifier of the approval instance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approved": { "type": "boolean", "description": "Whether the step is approved.", "example": true }, "comment": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Decision comment.", "example": "Within budget." } }, "required": ["approval_instance_id", "approved"], "description": "Fields accepted when creating a ApprovalDecision." }, "CommentThreadPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommentThread" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CommentThread": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the comment thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject_table": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Table of the subject, one of app.comment_subjects.", "example": "records" }, "subject_id": { "type": "string", "format": "uuid", "description": "Identifier of the row the thread is about.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "anchor": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Part of the subject the thread is anchored to; null for the main thread.", "example": "line:12" }, "resolved_at": { "type": ["string", "null"], "format": "date-time", "description": "When the thread was resolved; null while open.", "example": "2026-10-08T14:30:00Z" }, "resolved_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who resolved it, set from the session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "subject_table", "subject_id", "anchor", "resolved_at", "resolved_by" ], "description": "A comment thread on any record." }, "CommentThreadCreate": { "type": "object", "properties": { "subject_table": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Table of the subject, one of app.comment_subjects.", "example": "records" }, "subject_id": { "type": "string", "format": "uuid", "description": "Identifier of the row the thread is about.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "anchor": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Part of the subject the thread is anchored to; null for the main thread.", "example": "line:12" } }, "required": ["subject_table", "subject_id"], "description": "Fields accepted when creating a CommentThread." }, "CommentThreadUpdate": { "type": "object", "properties": { "anchor": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Part of the subject the thread is anchored to; null for the main thread.", "example": "line:12" }, "resolved_at": { "type": ["string", "null"], "format": "date-time", "description": "When the thread was resolved; null while open.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a CommentThread. Omitted fields are unchanged." }, "CommentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Comment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the comment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "comment_thread_id": { "type": "string", "format": "uuid", "description": "Identifier of the thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Comment text; mentions are recorded separately.", "example": "Load-in moved to 07:00." }, "author_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the author.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "source": { "type": "string", "enum": ["App", "Email", "API"], "description": "Where the comment came from.", "example": "App" }, "edited_at": { "type": ["string", "null"], "format": "date-time", "description": "When the text was last edited.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "comment_thread_id", "body", "author_person_id", "source", "edited_at" ], "description": "A comment in a thread." }, "CommentCreate": { "type": "object", "properties": { "comment_thread_id": { "type": "string", "format": "uuid", "description": "Identifier of the thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Comment text; mentions are recorded separately.", "example": "Load-in moved to 07:00." }, "source": { "type": "string", "enum": ["App", "Email", "API"], "description": "Where the comment came from.", "example": "App" } }, "required": ["comment_thread_id", "body"], "description": "Fields accepted when creating a Comment." }, "CommentUpdate": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Comment text; mentions are recorded separately.", "example": "Load-in moved to 07:00." }, "source": { "type": "string", "enum": ["App", "Email", "API"], "description": "Where the comment came from.", "example": "App" } }, "description": "Fields accepted when updating a Comment. Omitted fields are unchanged." }, "SubjectCommentRequest": { "type": "object", "properties": { "subject_table": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Table of the subject, one of app.comment_subjects without its schema.", "example": "records" }, "subject_id": { "type": "string", "format": "uuid", "description": "Identifier of the row commented on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Comment text.", "example": "Picked up, thanks." }, "anchor": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Part of the subject the thread is anchored to; absent for the main thread.", "example": "line:12" } }, "required": ["subject_table", "subject_id", "body"], "description": "A comment on a subject row, posted in its main thread or the thread of an anchor." }, "NotificationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the notification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Notification kind from `notification-kinds.yaml`.", "example": "timesheet.approved" }, "recipient_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person the notification is for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "read_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was read.", "example": "2026-10-08T14:30:00Z" }, "actor_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person whose action caused it, when one did.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject_table": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Table of the record it is about.", "example": "records" }, "subject_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record it is about.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project of the record, when it belongs to one.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message_args": { "type": "object", "additionalProperties": {}, "description": "ICU message arguments for the kind's catalog messages, such as a record title.", "example": { "type": "doc" } }, "archived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the recipient archived it.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "kind", "recipient_person_id", "read_at", "actor_person_id", "subject_table", "subject_id", "project_id", "message_args", "archived_at" ], "description": "A notification for the caller." }, "NotificationUpdate": { "type": "object", "properties": { "read_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was read.", "example": "2026-10-08T14:30:00Z" }, "archived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the recipient archived it.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a Notification. Omitted fields are unchanged." }, "MarkAllReadResult": { "type": "object", "properties": { "updated_count": { "type": "integer", "example": 12 } }, "required": ["updated_count"] }, "NotificationActRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": ["approve", "reject", "done"], "description": "What to do.", "example": "approve" }, "comment": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Reason, required when rejecting.", "example": "Over the stage budget." } }, "required": ["action"], "description": "An action on a notification." }, "NotificationPreferencePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationPreference" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "NotificationPreference": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the notification preference.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "channel": { "type": "string", "enum": ["In App", "Email", "SMS", "Push"], "description": "Delivery channel.", "example": "In App" }, "enabled": { "type": "boolean", "description": "Whether the channel is on for the kind.", "example": true }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership whose preference this is; preferences are per org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "category_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Notification category.", "example": "approvals" } }, "required": [ "id", "created_at", "updated_at", "channel", "enabled", "membership_id", "category_code" ], "description": "A per-kind, per-channel notification preference." }, "NotificationPreferenceCreate": { "type": "object", "properties": { "channel": { "type": "string", "enum": ["In App", "Email", "SMS", "Push"], "description": "Delivery channel.", "example": "In App" }, "enabled": { "type": "boolean", "description": "Whether the channel is on for the kind.", "example": true }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership whose preference this is; preferences are per org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "category_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Notification category.", "example": "approvals" } }, "required": ["channel", "enabled", "membership_id", "category_code"], "description": "Fields accepted when creating a NotificationPreference." }, "NotificationPreferenceUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the channel is on for the kind.", "example": true } }, "description": "Fields accepted when updating a NotificationPreference. Omitted fields are unchanged." }, "CalendarFeedPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarFeed" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CalendarFeed": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was revoked.", "example": "2026-10-08T14:30:00Z" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who owns the feed; it shows what they may see.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "last_accessed_at": { "type": ["string", "null"], "format": "date-time", "description": "Last time a calendar fetched the feed.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "revoked_at", "membership_id", "last_accessed_at" ], "description": "An iCalendar feed. The token is shown once, stored hashed and revocable." }, "CalendarFeedToken": { "type": "object", "properties": { "calendar_feed_id": { "type": "string", "format": "uuid", "description": "Identifier of the calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "feed_token": { "type": "string", "minLength": 1, "description": "The token of the feed's subscription URL. Shown once; only its hash is stored, and revoking the feed ends it.", "example": "cal_9fQ2mX4vT7kL1pR8" } }, "required": ["calendar_feed_id", "feed_token"], "description": "A newly created calendar feed and its subscription token, shown once." }, "CalendarFeedCreate": { "type": "object", "properties": { "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when creating a CalendarFeed." }, "TrashItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrashItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TrashItem": { "type": "object", "properties": { "subject_urn": { "type": "string", "minLength": 1, "maxLength": 300, "description": "URN of the deleted row.", "example": "urn:xpms:record:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "deleted_at": { "type": "string", "format": "date-time", "description": "When it was deleted.", "example": "2026-10-08T14:30:00Z" }, "purge_after": { "type": "string", "format": "date-time", "description": "When it will be purged.", "example": "2026-10-08T14:30:00Z" }, "subject_table": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Table of the deleted row.", "example": "budgets" }, "subject_id": { "type": "string", "format": "uuid", "description": "Identifier of the deleted row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the org of the deleted row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project of the deleted row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the row is called.", "example": "Summer Series Budget" }, "deleted_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who deleted it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "subject_urn", "deleted_at", "purge_after", "subject_table", "subject_id", "org_id", "project_id", "title", "deleted_by" ], "description": "A soft-deleted row, restorable for its table's retention period. A view, not a copy." }, "TrashRestoreResult": { "type": "object", "properties": { "subject_urn": { "type": "string", "description": "URN of the restored row.", "example": "urn:xpms:budgets:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "subject_table": { "type": "string", "description": "Table of the restored row.", "example": "budgets" }, "subject_id": { "type": "string", "format": "uuid", "description": "Identifier of the restored row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "rows_restored": { "type": "integer", "minimum": 1, "description": "Rows restored: the row and the rows that reference it and were deleted with it.", "example": 2 } }, "required": ["subject_urn", "subject_table", "subject_id", "rows_restored"], "description": "What a restore from Trash brought back." }, "RestoreRequest": { "type": "object", "properties": { "subject_urn": { "type": "string", "minLength": 1, "example": "urn:xpms:record:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["subject_urn"] }, "TemplatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Template": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Template name.", "example": "Three-Day Festival" }, "current_version_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the current version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "When to use the template.", "example": "Outdoor weekend shows." }, "template_kind": { "type": "string", "enum": ["Project"], "description": "What the template creates.", "example": "Project" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "current_version_id", "description", "template_kind" ], "description": "A project or record template, including the XOS 4.0 Production Template copy." }, "TemplateCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Template name.", "example": "Three-Day Festival" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "When to use the template.", "example": "Outdoor weekend shows." }, "template_kind": { "type": "string", "enum": ["Project"], "description": "What the template creates.", "example": "Project" } }, "required": ["name"], "description": "Fields accepted when creating a Template." }, "TemplateUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Template name.", "example": "Three-Day Festival" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "When to use the template.", "example": "Outdoor weekend shows." }, "template_kind": { "type": "string", "enum": ["Project"], "description": "What the template creates.", "example": "Project" } }, "description": "Fields accepted when updating a Template. Omitted fields are unchanged." }, "TemplateFromProjectRequest": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project saved as a template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Template name.", "example": "Three-Day Festival" }, "description": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "When to use the template.", "example": "Outdoor weekend shows." } }, "required": ["project_id", "name"], "description": "A project to save as a template." }, "TemplateApplicationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateApplication" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TemplateApplication": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the template application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row; null when a seed, platform or system process created it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row; null when a seed, platform or system process updated it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "template_id": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the created project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "template_version_id": { "type": "string", "format": "uuid", "description": "Identifier of the published version applied.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_nodes_created": { "type": "integer", "minimum": 0, "description": "Scope nodes created.", "example": 1 }, "records_created": { "type": "integer", "minimum": 0, "description": "Records created.", "example": 4 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "template_id", "project_id", "template_version_id", "scope_nodes_created", "records_created" ], "description": "A template applied to create a project and its records." }, "TemplateApplicationCreate": { "type": "object", "properties": { "template_id": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Key of the project to create.", "example": "NWT" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of the project to create.", "example": "Tidewater Weekend" }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone; defaults to the version's.", "example": "America/New_York" }, "starts_on": { "type": "string", "format": "date", "description": "Start date; records are due relative to it.", "example": "2026-10-08" }, "venue_id": { "type": "string", "format": "uuid", "description": "Identifier of the venue of the project and its shows.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["template_id", "project_key", "name"], "description": "Fields accepted when creating a TemplateApplication." }, "ProjectAuthorityPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectAuthority" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectAuthority": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "service": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Responder service the agency provides.", "example": "fire" }, "agency": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Agency having jurisdiction.", "example": "Miami-Dade Fire Rescue" }, "contact": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "How to reach the agency.", "example": "911" } }, "required": ["project_id", "service", "agency", "contact"], "description": "An authority having jurisdiction over a project: a responder agency of the jurisdiction of the project's venue (xpms.jurisdiction_agency), one row per service and agency. A project without a venue has none." }, "MeasurementMetricPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeasurementMetric" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MeasurementMetric": { "type": "object", "properties": { "metric_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Metric (app.measurement_metrics).", "example": "waste_generated" }, "family": { "type": "string", "enum": ["Sustainability", "Audience", "Earned Media", "Sentiment"], "description": "Family of the figure.", "example": "Sustainability" }, "dimension": { "type": "string", "enum": ["Mass", "Volume", "Energy", "Emissions", "Count", "Percent"], "description": "Dimension of the figure.", "example": "Mass" }, "base_unit_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit totals and comparisons are computed in.", "example": "kg" }, "aggregation": { "type": "string", "enum": ["Sum", "Latest"], "description": "How a project's figures combine: each adds to the total (Sum) or the latest measured one stands (Latest).", "example": "Sum" }, "is_derived": { "type": "boolean", "description": "True when the figure is computed from the coverage records rather than entered.", "example": false }, "lower_bound": { "type": ["number", "null"], "description": "Lowest figure accepted, in the base unit.", "example": 0 }, "upper_bound": { "type": ["number", "null"], "description": "Highest figure accepted, in the base unit.", "example": 100 }, "canon_domain": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Domain of the benchmarking canon metric.", "example": "site_services" }, "canon_item": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Item of the benchmarking canon metric.", "example": "Waste lbs per guest per day" }, "canon_value_numeric": { "type": ["number", "null"], "description": "The canon benchmark as a number.", "example": 2.4 }, "canon_value_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "The canon benchmark in words.", "example": "1.9 kW continuous" }, "canon_qualifier": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Qualifier of the canon benchmark.", "example": "MODELED event avg" }, "ordinal": { "type": "integer", "minimum": 1, "description": "Display order.", "example": 1 } }, "required": [ "metric_code", "family", "dimension", "base_unit_code", "aggregation", "is_derived", "lower_bound", "upper_bound", "canon_domain", "canon_item", "canon_value_numeric", "canon_value_text", "canon_qualifier", "ordinal" ], "description": "A figure a project measures against its gate 1 objectives (Section 4.10): sustainability, audience, earned media or sentiment. Canon's metric table holds reference values, so each metric names the canon metric that benchmarks it where canon states one." }, "MeasurementUnitPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeasurementUnit" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MeasurementUnit": { "type": "object", "properties": { "unit_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit code.", "example": "kg" }, "dimension": { "type": "string", "enum": ["Mass", "Volume", "Energy", "Emissions", "Count", "Percent"], "description": "Dimension of the unit.", "example": "Mass" }, "factor_to_base": { "type": "number", "description": "Base units in one of this unit.", "example": 0.45359237 }, "unit_system": { "type": "string", "enum": ["Metric", "Imperial", "Either"], "description": "Measurement system of the unit.", "example": "Imperial" }, "is_display": { "type": "boolean", "description": "True for the unit reports show the dimension in for readers of its system.", "example": true }, "ordinal": { "type": "integer", "minimum": 1, "description": "Display order.", "example": 3 } }, "required": [ "unit_code", "dimension", "factor_to_base", "unit_system", "is_display", "ordinal" ], "description": "A unit a figure or objective is entered in, with its exact factor to the base unit of its dimension and whether reports show the dimension in it for metric or imperial readers." }, "MeasurementMetricTagPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeasurementMetricTag" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "MeasurementMetricTag": { "type": "object", "properties": { "metric_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Metric (app.measurement_metrics).", "example": "waste_generated" }, "tag_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon tag code.", "example": "TAG-005" }, "tag": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Tag value as written in canon.", "example": "REUSABLE" } }, "required": ["metric_code", "tag_id", "tag"], "description": "A Bible sustainability tag (Bible tab 09) a sustainability figure is reported against (Section 4.10)." }, "ProjectObjectivePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectObjective" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectObjective": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project objective.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "metric_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Metric (app.measurement_metrics).", "example": "waste_generated" }, "direction": { "type": "string", "enum": ["At Least", "At Most"], "description": "Met by reaching the target (At Least) or by staying within it (At Most).", "example": "At Most" }, "target_value": { "type": "number", "description": "Target figure, in unit_code.", "example": 2 }, "unit_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit of the target, of the metric's dimension.", "example": "kg" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "metric_code", "direction", "target_value", "unit_code", "note" ], "description": "A measurable objective recorded at gate 1 (canon criterion G1.OBJECTIVES_STATED): one target per metric and project, which gate 8 measures against. Once gate 1 is passed only a gate approver (projects.gate.transition) sets, changes or withdraws one; every change is in the audit ledger." }, "ProjectObjectiveCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "metric_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Metric (app.measurement_metrics).", "example": "waste_generated" }, "direction": { "type": "string", "enum": ["At Least", "At Most"], "description": "Met by reaching the target (At Least) or by staying within it (At Most).", "example": "At Most" }, "target_value": { "type": "number", "description": "Target figure, in unit_code.", "example": 2 }, "unit_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit of the target, of the metric's dimension.", "example": "kg" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "required": ["project_id", "metric_code", "direction", "target_value", "unit_code"], "description": "Fields accepted when creating a ProjectObjective." }, "ProjectObjectiveUpdate": { "type": "object", "properties": { "direction": { "type": "string", "enum": ["At Least", "At Most"], "description": "Met by reaching the target (At Least) or by staying within it (At Most).", "example": "At Most" }, "target_value": { "type": "number", "description": "Target figure, in unit_code.", "example": 2 }, "unit_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit of the target, of the metric's dimension.", "example": "kg" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "description": "Fields accepted when updating a ProjectObjective. Omitted fields are unchanged." }, "ProjectMeasurementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectMeasurement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectMeasurement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project measurement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "metric_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Metric (app.measurement_metrics).", "example": "waste_generated" }, "measured_on": { "type": "string", "format": "date", "description": "Day the figure covers, on the project's calendar; today there when omitted, never later.", "example": "2026-10-08" }, "value": { "type": ["number", "null"], "description": "The figure in unit_code; null when not measured.", "example": 1200 }, "unit_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit of the figure, of the metric's dimension.", "example": "kg" }, "source": { "type": "string", "enum": ["Manual", "Import", "Integration"], "description": "How the figure reached XOS.", "example": "Import" }, "source_reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the figure came from, such as an invoice, a meter reading or a file name.", "example": "Hauler invoice 4471" }, "source_uri": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Link to the source: an http(s) URL or a URN.", "example": "https://hauler.example/invoices/4471" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "metric_code", "measured_on", "value", "unit_code", "source", "source_reference", "source_uri", "note" ], "description": "A figure measured on a project (Section 4.10) for one metric, day and source. A null value records that the figure was not measured (Unmeasured), never zero. Correcting the value, unit or day needs correction_reason and writes the change to the correction ledger. Who recorded it and when are created_by and created_at." }, "ProjectMeasurementCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "metric_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Metric (app.measurement_metrics).", "example": "waste_generated" }, "measured_on": { "type": "string", "format": "date", "description": "Day the figure covers, on the project's calendar; today there when omitted, never later.", "example": "2026-10-08" }, "value": { "type": ["number", "null"], "description": "The figure in unit_code; null when not measured.", "example": 1200 }, "unit_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit of the figure, of the metric's dimension.", "example": "kg" }, "source": { "type": "string", "enum": ["Manual", "Import", "Integration"], "description": "How the figure reached XOS.", "example": "Import" }, "source_reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the figure came from, such as an invoice, a meter reading or a file name.", "example": "Hauler invoice 4471" }, "source_uri": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Link to the source: an http(s) URL or a URN.", "example": "https://hauler.example/invoices/4471" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "required": ["project_id", "metric_code"], "description": "Fields accepted when creating a ProjectMeasurement." }, "ProjectMeasurementUpdate": { "type": "object", "properties": { "measured_on": { "type": "string", "format": "date", "description": "Day the figure covers, on the project's calendar; today there when omitted, never later.", "example": "2026-10-08" }, "value": { "type": ["number", "null"], "description": "The figure in unit_code; null when not measured.", "example": 1200 }, "unit_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit of the figure, of the metric's dimension.", "example": "kg" }, "source_reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the figure came from, such as an invoice, a meter reading or a file name.", "example": "Hauler invoice 4471" }, "source_uri": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Link to the source: an http(s) URL or a URN.", "example": "https://hauler.example/invoices/4471" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." }, "correction_reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the figure is corrected: required when the value, unit or day changes, kept in the correction ledger and never returned.", "example": "Weighbridge ticket supersedes the estimate." } }, "description": "Fields accepted when updating a ProjectMeasurement. Omitted fields are unchanged." }, "ProjectMeasurementCorrectionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectMeasurementCorrection" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectMeasurementCorrection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project measurement correction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_measurement_id": { "type": "string", "format": "uuid", "description": "Identifier of the figure that changed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "correction_kind": { "type": "string", "enum": ["Corrected", "Withdrawn", "Restored"], "description": "What changed the figure.", "example": "Corrected" }, "previous_value": { "type": ["number", "null"], "description": "Value before the change; null when Unmeasured.", "example": 1200 }, "previous_unit_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit before the change.", "example": "kg" }, "previous_measured_on": { "type": "string", "format": "date", "description": "Day before the change.", "example": "2026-10-08" }, "value": { "type": ["number", "null"], "description": "Value after the change; null when Unmeasured.", "example": 1.25 }, "unit_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit after the change.", "example": "kg" }, "measured_on": { "type": "string", "format": "date", "description": "Day after the change.", "example": "2026-10-08" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Why the figure changed.", "example": "Weighbridge ticket supersedes the estimate." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_measurement_id", "correction_kind", "previous_value", "previous_unit_code", "previous_measured_on", "value", "unit_code", "measured_on", "reason" ], "description": "An entry of the append-only correction ledger: a figure corrected, withdrawn or restored, with the figure before and after and the reason. Who changed it and when are created_by and created_at." }, "EarnedMediaItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EarnedMediaItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EarnedMediaItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the earned media item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Headline or title of the coverage.", "example": "Summer Series opens on the pier" }, "outlet": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Publication, station, channel or account that ran it.", "example": "WLRN" }, "medium": { "type": "string", "enum": ["Online", "Print", "Broadcast", "Podcast", "Social"], "description": "Where the coverage ran.", "example": "Broadcast" }, "published_on": { "type": "string", "format": "date", "description": "Day it ran, on the project's calendar; never after today there.", "example": "2026-10-08" }, "url": { "type": ["string", "null"], "format": "uri", "description": "Link to the coverage; one live row per link in a project.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "reach": { "type": ["integer", "null"], "minimum": 0, "description": "Audience the outlet reports for the piece; null when unreported.", "example": 120000 }, "tone": { "type": ["string", "null"], "enum": ["Positive", "Neutral", "Negative", null], "description": "Sentiment of the coverage; null until rated.", "example": "Positive" }, "source": { "type": "string", "enum": ["Manual", "Import", "Integration"], "description": "How the figure reached XOS.", "example": "Import" }, "source_reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the figure came from, such as an invoice, a meter reading or a file name.", "example": "Hauler invoice 4471" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "title", "outlet", "medium", "published_on", "url", "reach", "tone", "source", "source_reference", "note" ], "description": "A piece of earned media coverage of a project (gate 8, G8.MEASUREMENT_REPORTED), sourced, dated and linked. The earned media figures of the measurement summary are computed from these rows. A reach the source does not report is null (Unmeasured); a tone is null until rated." }, "EarnedMediaItemCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Headline or title of the coverage.", "example": "Summer Series opens on the pier" }, "outlet": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Publication, station, channel or account that ran it.", "example": "WLRN" }, "medium": { "type": "string", "enum": ["Online", "Print", "Broadcast", "Podcast", "Social"], "description": "Where the coverage ran.", "example": "Broadcast" }, "published_on": { "type": "string", "format": "date", "description": "Day it ran, on the project's calendar; never after today there.", "example": "2026-10-08" }, "url": { "type": ["string", "null"], "format": "uri", "description": "Link to the coverage; one live row per link in a project.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "reach": { "type": ["integer", "null"], "minimum": 0, "description": "Audience the outlet reports for the piece; null when unreported.", "example": 120000 }, "tone": { "type": ["string", "null"], "enum": ["Positive", "Neutral", "Negative", null], "description": "Sentiment of the coverage; null until rated.", "example": "Positive" }, "source": { "type": "string", "enum": ["Manual", "Import", "Integration"], "description": "How the figure reached XOS.", "example": "Import" }, "source_reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the figure came from, such as an invoice, a meter reading or a file name.", "example": "Hauler invoice 4471" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "required": ["project_id", "title", "outlet", "medium", "published_on"], "description": "Fields accepted when creating a EarnedMediaItem." }, "EarnedMediaItemUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Headline or title of the coverage.", "example": "Summer Series opens on the pier" }, "outlet": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Publication, station, channel or account that ran it.", "example": "WLRN" }, "medium": { "type": "string", "enum": ["Online", "Print", "Broadcast", "Podcast", "Social"], "description": "Where the coverage ran.", "example": "Broadcast" }, "published_on": { "type": "string", "format": "date", "description": "Day it ran, on the project's calendar; never after today there.", "example": "2026-10-08" }, "url": { "type": ["string", "null"], "format": "uri", "description": "Link to the coverage; one live row per link in a project.", "example": "https://northwindlive.example/files/site-plan.pdf" }, "reach": { "type": ["integer", "null"], "minimum": 0, "description": "Audience the outlet reports for the piece; null when unreported.", "example": 120000 }, "tone": { "type": ["string", "null"], "enum": ["Positive", "Neutral", "Negative", null], "description": "Sentiment of the coverage; null until rated.", "example": "Positive" }, "source": { "type": "string", "enum": ["Manual", "Import", "Integration"], "description": "How the figure reached XOS.", "example": "Import" }, "source_reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the figure came from, such as an invoice, a meter reading or a file name.", "example": "Hauler invoice 4471" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Note.", "example": "Two roll-off containers." } }, "description": "Fields accepted when updating a EarnedMediaItem. Omitted fields are unchanged." }, "ProjectMeasurementSummaryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectMeasurementSummary" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectMeasurementSummary": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "metric_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Metric (app.measurement_metrics).", "example": "waste_generated" }, "family": { "type": "string", "enum": ["Sustainability", "Audience", "Earned Media", "Sentiment"], "description": "Family of the figure.", "example": "Sustainability" }, "dimension": { "type": "string", "enum": ["Mass", "Volume", "Energy", "Emissions", "Count", "Percent"], "description": "Dimension of the figure.", "example": "Mass" }, "base_unit_code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit of target_base and measured_base.", "example": "kg" }, "aggregation": { "type": "string", "enum": ["Sum", "Latest"], "description": "How figures combine.", "example": "Sum" }, "objective_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the live gate 1 objective for the metric.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "direction": { "type": ["string", "null"], "enum": ["At Least", "At Most", null], "description": "Direction of the objective.", "example": "At Most" }, "target_value": { "type": ["number", "null"], "description": "Target as set, in target_unit_code.", "example": 2 }, "target_unit_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Unit the target was set in.", "example": "kg" }, "target_base": { "type": ["number", "null"], "description": "Target in the base unit.", "example": 2000 }, "measured_count": { "type": "integer", "minimum": 0, "description": "Figures with a value.", "example": 2 }, "unmeasured_count": { "type": "integer", "minimum": 0, "description": "Figures recorded as not measured; never counted as zero.", "example": 1 }, "measured_base": { "type": ["number", "null"], "description": "Total (Sum) or latest figure (Latest) in the base unit; null when nothing was measured.", "example": 1953.59237 }, "last_measured_on": { "type": ["string", "null"], "format": "date", "description": "Day of the most recent measured figure.", "example": "2026-10-08" }, "outcome": { "type": ["string", "null"], "enum": ["Met", "Not Met", "Incomplete", "Unmeasured", null], "description": "Met, Not Met, Incomplete (unmeasured figures leave the objective undecided) or Unmeasured; null without an objective.", "example": "Met" } }, "required": [ "project_id", "metric_code", "family", "dimension", "base_unit_code", "aggregation", "objective_id", "direction", "target_value", "target_unit_code", "target_base", "measured_count", "unmeasured_count", "measured_base", "last_measured_on", "outcome" ], "description": "Gate 8 measurement against the gate 1 objectives, per project and metric, in the metric's base unit. Totals cover measured figures only, with the unmeasured count beside them; with nothing measured the figure is null (Unmeasured), never zero." }, "CueCallPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CueCall" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CueCall": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the cue call.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "cue_id": { "type": "string", "format": "uuid", "description": "Identifier of the cue the call belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "call_kind": { "type": "string", "enum": ["Audio", "Lighting", "Video", "Special Effects", "Stage"], "description": "Department making the call.", "example": "Lighting" }, "instruction": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What the department does on the cue.", "example": "LX 14 GO, house to half." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "cue_id", "call_kind", "instruction" ], "description": "A department's call on a cue (1180): the audio, lighting, video, special effects or stage instruction given when the cue fires. The Run of Show sheet holds one column per department." }, "CueCallCreate": { "type": "object", "properties": { "cue_id": { "type": "string", "format": "uuid", "description": "Identifier of the cue the call belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "call_kind": { "type": "string", "enum": ["Audio", "Lighting", "Video", "Special Effects", "Stage"], "description": "Department making the call.", "example": "Lighting" }, "instruction": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What the department does on the cue.", "example": "LX 14 GO, house to half." } }, "required": ["cue_id", "call_kind", "instruction"], "description": "Fields accepted when creating a CueCall." }, "CueCallUpdate": { "type": "object", "properties": { "call_kind": { "type": "string", "enum": ["Audio", "Lighting", "Video", "Special Effects", "Stage"], "description": "Department making the call.", "example": "Lighting" }, "instruction": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What the department does on the cue.", "example": "LX 14 GO, house to half." } }, "description": "Fields accepted when updating a CueCall. Omitted fields are unchanged." }, "GuestListEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GuestListEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "GuestListEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the show or other scope node of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person whose list the guest is on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "counterparty_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the organization whose list the guest is on.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement the guest was requested under in Gateway.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "guest_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name the guest gives at the door.", "example": "Jordan Pike" }, "plus_ones": { "type": "integer", "minimum": 0, "description": "Additional guests admitted with this guest, 0 to 20.", "example": 1 }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Notes for the door.", "example": "Side stage." }, "entry_state": { "type": "string", "enum": ["Requested", "Approved", "Declined", "Checked In"], "description": "Requested, Approved, Declined or Checked In; moved by the decide and check-in actions.", "example": "Requested" }, "decided_at": { "type": ["string", "null"], "format": "date-time", "description": "When the request was approved or declined. Set by the database.", "example": "2026-10-08T14:30:00Z" }, "decided_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who decided, set by the database.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "checked_in_at": { "type": ["string", "null"], "format": "date-time", "description": "When the guest was checked in. Set by the database.", "example": "2026-10-08T14:30:00Z" }, "checked_in_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who checked the guest in, set by the database.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "scope_node_id", "person_id", "counterparty_id", "engagement_id", "guest_name", "plus_ones", "note", "entry_state", "decided_at", "decided_by", "checked_in_at", "checked_in_by" ], "description": "A guest on a project's guest list with plus-ones. Requested guests are approved or declined by someone with review authority who did not request them, then checked in at the door." }, "GuestListEntryCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the show or other scope node of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "guest_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name the guest gives at the door.", "example": "Jordan Pike" }, "plus_ones": { "type": "integer", "minimum": 0, "description": "Additional guests admitted with this guest, 0 to 20.", "example": 1 }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Notes for the door.", "example": "Side stage." } }, "required": ["project_id", "guest_name", "plus_ones"], "description": "Fields accepted when creating a GuestListEntry." }, "GuestListEntryUpdate": { "type": "object", "properties": { "scope_node_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the show or other scope node of the same project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "guest_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name the guest gives at the door.", "example": "Jordan Pike" }, "plus_ones": { "type": "integer", "minimum": 0, "description": "Additional guests admitted with this guest, 0 to 20.", "example": 1 }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Notes for the door.", "example": "Side stage." } }, "description": "Fields accepted when updating a GuestListEntry. Omitted fields are unchanged." }, "GuestDecisionRequest": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["Approved", "Declined"], "description": "Approved or Declined.", "example": "Approved" } }, "required": ["outcome"], "description": "Decision on a requested guest." }, "Form1099NecRowPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Form1099NecRow" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Form1099NecRow": { "type": "object", "properties": { "payee_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person paid as an individual.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payee_organization_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the account paid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "payee_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Name on the W-9, or the payee's name.", "example": "Ivy Marchetti" }, "w9_on_file": { "type": "boolean", "description": "Whether a W-9 is on file with the org.", "example": true }, "tin_type": { "type": ["integer", "null"], "minimum": 1, "description": "FIRE TIN type: 1 EIN (an account), 2 SSN (a person).", "example": 2 }, "tin_last4": { "type": ["string", "null"], "minLength": 1, "maxLength": 4, "description": "Last four of the TIN.", "example": "6789" }, "address_complete": { "type": "boolean", "description": "Whether the W-9 address is complete.", "example": true }, "amount_minor": { "type": ["integer", "null"], "description": "Approved USD payments in the year. Integer minor units of the resource currency; null means unpriced, never zero.", "example": 75000, "format": "int64" }, "payment_count": { "type": "integer", "minimum": 0, "description": "Payments counted.", "example": 2 } }, "required": [ "payee_person_id", "payee_organization_id", "payee_name", "w9_on_file", "tin_type", "tin_last4", "address_complete", "amount_minor", "payment_count" ], "description": "A payee paid $600 or more in approved USD payments in a tax year as an independent contractor, with the W-9 on file." }, "InsuranceCertificateInsuredPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsuranceCertificateInsured" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InsuranceCertificateInsured": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "certificate_id": { "type": "string", "format": "uuid", "description": "Identifier of the certificate naming the party.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insured_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Party named, as printed.", "example": "Example Venue Owner LLC" }, "endorsement_kind": { "type": "string", "enum": ["Additional Insured", "Primary and Noncontributory", "Waiver of Subrogation"], "description": "Endorsement: Additional Insured, Primary and Noncontributory, or Waiver of Subrogation.", "example": "Additional Insured" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "certificate_id", "insured_name", "endorsement_kind" ], "description": "A party a certificate of insurance names, with the endorsement it grants (1130). A name appears once per endorsement on a certificate, ignoring case and spacing (409)." }, "InsuranceCertificateInsuredCreate": { "type": "object", "properties": { "certificate_id": { "type": "string", "format": "uuid", "description": "Identifier of the certificate naming the party.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insured_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Party named, as printed.", "example": "Example Venue Owner LLC" }, "endorsement_kind": { "type": "string", "enum": ["Additional Insured", "Primary and Noncontributory", "Waiver of Subrogation"], "description": "Endorsement: Additional Insured, Primary and Noncontributory, or Waiver of Subrogation.", "example": "Additional Insured" } }, "required": ["certificate_id", "insured_name", "endorsement_kind"], "description": "Fields accepted when creating a InsuranceCertificateInsured." }, "InsuranceCertificateInsuredUpdate": { "type": "object", "properties": { "insured_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Party named, as printed.", "example": "Example Venue Owner LLC" }, "endorsement_kind": { "type": "string", "enum": ["Additional Insured", "Primary and Noncontributory", "Waiver of Subrogation"], "description": "Endorsement: Additional Insured, Primary and Noncontributory, or Waiver of Subrogation.", "example": "Additional Insured" } }, "description": "Fields accepted when updating a InsuranceCertificateInsured. Omitted fields are unchanged." }, "RequiredAdditionalInsuredPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredAdditionalInsured" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "RequiredAdditionalInsured": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the required additional insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the requirement adds to; null for every project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insured_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Party that must be named.", "example": "Example Venue Owner LLC" }, "endorsement_kind": { "type": "string", "enum": ["Additional Insured", "Primary and Noncontributory", "Waiver of Subrogation"], "description": "Endorsement: Additional Insured, Primary and Noncontributory, or Waiver of Subrogation.", "example": "Additional Insured" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "insured_name", "endorsement_kind" ], "description": "A party the org requires its vendors' certificates to name (1130): org-wide when project_id is null, or for vendors engaged on one project as well. app.verify_onboarding_insureds checks an engagement against them." }, "RequiredAdditionalInsuredCreate": { "type": "object", "properties": { "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the requirement adds to; null for every project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "insured_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Party that must be named.", "example": "Example Venue Owner LLC" }, "endorsement_kind": { "type": "string", "enum": ["Additional Insured", "Primary and Noncontributory", "Waiver of Subrogation"], "description": "Endorsement: Additional Insured, Primary and Noncontributory, or Waiver of Subrogation.", "example": "Additional Insured" } }, "required": ["insured_name", "endorsement_kind"], "description": "Fields accepted when creating a RequiredAdditionalInsured." }, "RequiredAdditionalInsuredUpdate": { "type": "object", "properties": { "insured_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Party that must be named.", "example": "Example Venue Owner LLC" }, "endorsement_kind": { "type": "string", "enum": ["Additional Insured", "Primary and Noncontributory", "Waiver of Subrogation"], "description": "Endorsement: Additional Insured, Primary and Noncontributory, or Waiver of Subrogation.", "example": "Additional Insured" } }, "description": "Fields accepted when updating a RequiredAdditionalInsured. Omitted fields are unchanged." }, "CanonStdEmergencyProtocolPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanonStdEmergencyProtocol" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "CanonStdEmergencyProtocol": { "type": "object", "properties": { "record_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Record identifier of the protocol.", "example": "EMG-001" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Radio code the protocol answers (xpms.emergency_code).", "example": "CODE_RED" }, "domain": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Operational domain the protocol applies to.", "example": "Site Operations" }, "department": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Department as the sheet names it.", "example": "Security & Safety" }, "category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Category as the sheet names it.", "example": "Emergency Protocols" }, "sub_category": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Sub-category as the sheet names it.", "example": "Incident Response" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/CanonEmergencyProtocolStep" }, "description": "The protocol's steps (xpms.emergency_protocol_step), in order." } }, "required": [ "record_key", "code", "domain", "department", "category", "sub_category", "steps" ], "description": "An emergency protocol of the Standard Library (Emergency Codes sheet): what one operational domain does when a radio code is called, in numbered steps." }, "CanonEmergencyProtocolStep": { "type": "object", "properties": { "step_no": { "type": "integer", "minimum": 1, "description": "Step number, from 1.", "example": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What to do; responder services appear as tokens such as {fire} (ruling D15).", "example": "Contact {fire}." } }, "required": ["step_no", "body"], "description": "One numbered step of an emergency protocol." }, "ReportScheduleRecipientPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportScheduleRecipient" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReportScheduleRecipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "report_schedule_id": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the recipient, in the schedule's org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "report_schedule_id", "membership_id" ], "description": "A member of the org a scheduled report is emailed to; each receives it run with their own access, so a report never leaves the org (Section 4.6.4)." }, "ReportScheduleRecipientCreate": { "type": "object", "properties": { "report_schedule_id": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the recipient, in the schedule's org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["report_schedule_id", "membership_id"], "description": "Fields accepted when creating a ReportScheduleRecipient." }, "ReportDeliveryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportDelivery" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ReportDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the report delivery.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "report_schedule_id": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the recipient membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "report_run_id": { "type": "string", "format": "uuid", "description": "Identifier of the report run whose file is attached.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "scheduled_for": { "type": "string", "format": "date-time", "description": "The schedule slot this delivery is for.", "example": "2026-10-08T14:30:00Z" }, "delivery_status": { "type": "string", "enum": ["Queued", "Sent", "Failed"], "description": "Delivery status.", "example": "Queued" }, "sent_at": { "type": ["string", "null"], "format": "date-time", "description": "When the email was handed to the transport.", "example": "2026-10-08T14:30:00Z" }, "last_error": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Why the delivery failed.", "example": "The report run failed." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "report_schedule_id", "membership_id", "report_run_id", "scheduled_for", "delivery_status", "sent_at", "last_error" ], "description": "One email of a scheduled report to one recipient: the run made as that member for the slot, and whether the email went out. Written only by the scheduler and the delivery worker." }, "AuroraStatus": { "type": "object", "properties": { "enabled_features": { "type": "array", "items": { "$ref": "#/components/schemas/AiFeature" }, "description": "Features the caller may use now.", "example": ["assistant", "extraction"] }, "used": { "type": "integer", "minimum": 0, "description": "Requests the org made this UTC month.", "example": 12 }, "allowance": { "type": ["integer", "null"], "minimum": 0, "description": "Monthly allowance; null when the plan sets no limit.", "example": 500 }, "plan_includes_aurora": { "type": "boolean", "description": "Whether the plan includes Aurora AI.", "example": true } }, "required": ["enabled_features", "used", "allowance", "plan_includes_aurora"], "description": "What Aurora can do for the caller now: the features an Admin turned on that the plan includes, and this month's use of the allowance." }, "AiFeature": { "type": "string", "enum": ["assistant", "plain_language", "extraction", "drafting", "summaries", "mapping"], "description": "An Aurora AI feature (Section 4.7).", "example": "assistant" }, "AuroraResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["answer", "no_answer", "failed"], "description": "answer, no_answer (the data does not support an answer; `missing` says why) or failed (the model call failed and was logged).", "example": "answer" }, "ai_generated": { "type": "boolean", "enum": [true], "description": "Always true: the content is AI-generated and is labeled so (EU AI Act Article 50).", "example": true }, "request_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the logged AI request; null when no model was called.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "model": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Model that answered.", "example": "claude-sonnet-5-5" }, "missing": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "What the data lacks, for no_answer.", "example": "No budget lines exist yet." }, "failure_code": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "Why the request failed.", "example": "model_error" }, "answer": { "description": "The feature's answer for outcome answer, shaped per operation; null otherwise.", "example": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] } }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/AuroraProposal" }, "description": "Changes stored for confirmation.", "example": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] } }, "required": [ "outcome", "ai_generated", "request_id", "model", "missing", "failure_code", "suggestions" ], "description": "The result of one Aurora request." }, "AuroraProposal": { "type": "object", "properties": { "suggestion_id": { "type": "string", "format": "uuid", "description": "Identifier of the stored suggestion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Public API operation the change would call.", "example": "savedViews.create" }, "summary": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What will change.", "example": "Save the view Blocked Miami Permits." } }, "required": ["suggestion_id", "operation_id", "summary"], "description": "A change waiting for confirmation." }, "AuroraAskRequest": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The question.", "example": "Which permits are blocked?" }, "history": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 4000 }, "answer": { "type": "string", "maxLength": 8000 } }, "required": ["question", "answer"] }, "maxItems": 10, "default": [], "description": "Earlier turns of this conversation, oldest first.", "example": [ { "question": "Which permits are blocked?", "answer": "One: Fire Marshal Permit." } ] } }, "required": ["question"], "description": "A question for the assistant." }, "AuroraFilterRequest": { "type": "object", "properties": { "sentence": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The sentence to turn into a filter.", "example": "blocked permits for Miami shows this month" }, "collections": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, "minItems": 1, "maxItems": 20, "description": "Collections the filter may target.", "example": ["permits"] }, "time_zone": { "type": "string", "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "Time zone the caller works in. Relative dates such as this month or overdue resolve on the org's calendar (its locale.time_zone setting), never on UTC.", "example": "America/New_York" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 64, "pattern": "^[a-z][a-z0-9_.]*$", "description": "Filter name as the page's query string writes it.", "example": "overdue" }, "type": { "type": "string", "enum": ["string", "number", "date", "boolean", "enum"], "description": "Value type.", "example": "boolean" }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 200, "description": "The values an enum filter takes.", "example": ["Issued", "Approved"] }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What the filter means, in a sentence.", "example": "Unpaid invoices past their due date on the org's calendar." }, "ops": { "type": "array", "items": { "type": "string", "enum": ["eq", "ne", "lt", "lte", "gt", "gte", "in", "is_null", "contains"] }, "minItems": 1, "description": "The only operators the filter takes.", "example": ["eq"] } }, "required": ["name", "type"] }, "minItems": 1, "maxItems": 40, "description": "A page's own filters, offered instead of the API fields of the first collection: names, types, values and operators only, never record data. Restricted columns are never offered.", "example": [{ "name": "overdue", "type": "boolean", "ops": ["eq"] }] } }, "required": ["sentence", "collections", "time_zone"], "description": "A sentence to turn into a saved view." }, "AuroraExtractRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["rider", "insurance_certificate", "invoice", "receipt", "quote"], "description": "What the document is.", "example": "insurance_certificate" }, "document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the stored document read, when the file is one.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "media_type": { "type": "string", "enum": ["application/pdf", "text/plain", "image/png", "image/jpeg", "image/webp"], "description": "Media type of the content.", "example": "application/pdf" }, "content_base64": { "type": "string", "minLength": 1, "maxLength": 14000000, "description": "The document content in base64, read by the caller from storage.", "example": "JVBERi0xLjcK" }, "file_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "File name shown in the log.", "example": "coi-atlantic.pdf" } }, "required": ["kind", "media_type", "content_base64", "file_name"], "description": "A document to extract into proposed fields." }, "AuroraDraftRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["sop", "advance_packet", "email", "day_sheet", "change_order_description"], "description": "What to draft.", "example": "sop" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What the draft should say.", "example": "Write the load-in SOP for the main stage." }, "context": { "type": "array", "items": { "type": "object", "properties": { "collection": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, "id": { "type": "string", "format": "uuid" } }, "required": ["collection", "id"] }, "maxItems": 20, "default": [], "description": "Records to draft from, read with the caller's permissions.", "example": [{ "collection": "venues", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }] }, "verbiage": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 100 }, "preferred": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["term", "preferred"] }, "maxItems": 200, "default": [], "description": "The org's verbiage library entries to apply.", "example": [{ "term": "loading dock", "preferred": "Dock" }] } }, "required": ["kind", "instructions"], "description": "Instructions for a draft." }, "AuroraSummarizeRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["record_activity", "project_week", "gate_readiness"], "description": "What to summarize.", "example": "project_week" }, "subject_collection": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "Collection of the record or project summarized.", "example": "projects" }, "subject_id": { "type": "string", "format": "uuid", "description": "Identifier of the record or project summarized.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "items": { "type": "array", "items": { "type": "object", "properties": { "collection": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, "id": { "type": "string", "format": "uuid" } }, "required": ["collection", "id"] }, "maxItems": 100, "description": "Activity and records to summarize, read with the caller's permissions.", "example": [ { "collection": "activity-events", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ] } }, "required": ["kind", "subject_collection", "subject_id", "items"], "description": "What to summarize." }, "AuroraMapColumnsRequest": { "type": "object", "properties": { "collection": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "Import target.", "example": "people" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "header": { "type": "string", "maxLength": 200 }, "samples": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 5 } }, "required": ["header", "samples"] }, "minItems": 1, "maxItems": 200, "description": "Import columns with sample values.", "example": [{ "header": "E-mail", "samples": ["crew@example.com"] }] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 300 } }, "required": ["name", "description"] }, "minItems": 1, "maxItems": 200, "description": "Target fields of the collection.", "example": [{ "name": "email", "description": "Email address." }] } }, "required": ["collection", "columns", "fields"], "description": "Import columns to map onto fields." }, "AuroraBindCodeRequest": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The scanned code.", "example": "0012345678905" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "What the label said.", "example": "LED PANEL 500MM" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "element_id": { "type": "string", "maxLength": 100 }, "name": { "type": "string", "maxLength": 300 }, "urid": { "type": "string", "maxLength": 20 } }, "required": ["element_id", "name", "urid"] }, "minItems": 1, "maxItems": 50, "description": "Catalog elements found for the code.", "example": [ { "element_id": "9000.02.03-NWL-0001", "name": "LED Wall Panel", "urid": "9000.02.03" } ] } }, "required": ["code", "description", "candidates"], "description": "An unknown scanned code to bind." }, "AuroraPreview": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/AuroraPreviewRecord" }, "description": "Each record the request names, in order, with the gate readiness a gate summary adds.", "example": [] }, "vocabulary_terms": { "type": "integer", "minimum": 0, "description": "Verbiage library terms a draft follows.", "example": 12 } }, "required": ["records", "vocabulary_terms"], "description": "What a drafting or summary request would send to the model, read and scrubbed exactly as the request would be. No model is called and nothing is metered." }, "AuroraPreviewRecord": { "type": "object", "properties": { "collection": { "type": "string", "description": "Collection of the record.", "example": "change-orders" }, "id": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "sent": { "type": "boolean", "description": "False when the record cannot be read or its whole table is never sent to a model.", "example": true }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Fields that would be sent.", "example": ["title", "reason"] }, "withheld": { "type": "array", "items": { "type": "string" }, "description": "Fields left out: Restricted columns and masked values.", "example": ["agreed_rate_minor"] }, "data": { "type": ["object", "null"], "additionalProperties": {}, "description": "The values that would be sent; null when nothing of the record is sent.", "example": { "title": "Extra rigging points", "reason": null } } }, "required": ["collection", "id", "sent", "fields", "withheld", "data"], "description": "One record as a model would see it." }, "AuroraPreviewRequest": { "type": "object", "properties": { "feature": { "type": "string", "enum": ["drafting", "summaries"], "description": "The feature whose request is previewed.", "example": "drafting" }, "kind": { "type": "string", "enum": ["record_activity", "project_week", "gate_readiness"], "description": "For summaries, what is summarized.", "example": "gate_readiness" }, "subject_collection": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "For summaries, the collection summarized.", "example": "projects" }, "subject_id": { "type": "string", "format": "uuid", "description": "Identifier of the record or project summarized.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "items": { "type": "array", "items": { "type": "object", "properties": { "collection": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, "id": { "type": "string", "format": "uuid" } }, "required": ["collection", "id"] }, "maxItems": 100, "description": "The records the request names: a draft's context or a summary's items, read with the caller's permissions.", "example": [{ "collection": "sops", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }] } }, "required": ["feature", "items"], "description": "A drafting or summary request to preview before it is sent." }, "AiSuggestionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiSuggestion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AiSuggestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the ai suggestion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "request_id": { "type": "string", "format": "uuid", "description": "Identifier of the AI request that proposed the change.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Public API operation that performs the change.", "example": "insuranceCertificates.create" }, "target_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the change updates; null when it creates one.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "summary": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What will change, shown on the confirmation step.", "example": "Add the Atlantic Mutual general liability certificate." }, "suggestion_state": { "$ref": "#/components/schemas/AiSuggestionState" }, "expires_at": { "type": "string", "format": "date-time", "description": "After this time the suggestion can no longer be confirmed.", "example": "2026-10-08T14:30:00Z" }, "applied_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the public API wrote, once Applied.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "proposed_fields": { "type": "array", "items": { "$ref": "#/components/schemas/AiSuggestionField" }, "description": "Proposed fields in confirmation order.", "example": [ { "field_path": "expires_on", "proposed_value": "2027-03-31", "confidence": 0.91, "refusal": null, "missing": null, "source_excerpt": "Policy expiration 03/31/2027", "provenance": "agent" } ] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "request_id", "operation_id", "target_id", "summary", "suggestion_state", "expires_at", "applied_id", "proposed_fields" ], "description": "A change an Aurora feature proposes, waiting for the confirmation of the person who asked. The summary says exactly what will change; nothing is written until they confirm." }, "AiSuggestionState": { "type": "string", "enum": ["Proposed", "Confirmed", "Applied", "Rejected", "Expired"], "description": "Proposed and waiting for the person who asked, Confirmed by them, Applied once the public API accepted the write, Rejected, or Expired unanswered.", "example": "Proposed" }, "AiSuggestionField": { "type": "object", "properties": { "field_path": { "type": "string", "description": "API field the value is for.", "example": "expires_on" }, "proposed_value": { "description": "Proposed value as JSON; null when the field is NO_ANSWER.", "example": "2027-03-31" }, "confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1, "description": "Confidence from 0 to 1; null when the field is NO_ANSWER.", "example": 0.91 }, "refusal": { "type": ["string", "null"], "enum": ["NO_ANSWER", null], "description": "NO_ANSWER when the source does not support a value.", "example": null }, "missing": { "type": ["string", "null"], "description": "What the source lacks, when the field is NO_ANSWER.", "example": null }, "source_excerpt": { "type": ["string", "null"], "description": "The passage the value was read from, redacted.", "example": "Policy expiration 03/31/2027" }, "provenance": { "type": "string", "enum": ["agent"], "description": "Every AI-proposed value carries provenance agent (rank 40, Section 3.8).", "example": "agent" } }, "required": [ "field_path", "confidence", "refusal", "missing", "source_excerpt", "provenance" ], "description": "One proposed field of an AI suggestion." }, "AiSuggestionConfirmRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why, recorded in the suggestion ledger.", "example": "Checked against the certificate." }, "values": { "type": "object", "additionalProperties": {}, "description": "Field values to send instead of, or in addition to, the proposed ones: corrections the person made and context ids such as `document_id`.", "example": { "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } } }, "required": ["reason"], "description": "Confirmation of an AI suggestion." }, "AiSuggestionRejectRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why, recorded in the suggestion ledger.", "example": "Checked against the certificate." } }, "required": ["reason"], "description": "Rejection of an AI suggestion." }, "AiSuggestionApplyRequest": { "type": "object", "properties": { "applied_id": { "type": "string", "format": "uuid", "description": "Identifier of the record the public API wrote or updated.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What was written.", "example": "Written by insuranceCertificates.create." } }, "required": ["applied_id", "reason"], "description": "The record a confirmed suggestion wrote." }, "AiSuggestionReopenRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why, recorded in the suggestion ledger.", "example": "Checked against the certificate." } }, "required": ["reason"], "description": "Why the write was refused." }, "AiRequestPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiRequest" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AiRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the ai request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person who asked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "feature": { "$ref": "#/components/schemas/AiFeature" }, "model": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Model identifier from configuration.", "example": "claude-sonnet-5-5" }, "subject_table": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Table of the record the request was about.", "example": "app.documents" }, "subject_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the request was about.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "outcome": { "$ref": "#/components/schemas/AiRequestOutcome" }, "prompt_redacted": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Prompt as sent, redacted.", "example": "Who is the vendor contact?" }, "output_redacted": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Model output, redacted.", "example": "Ivy Chen, [phone]." }, "failure_code": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "Why a Failed request failed.", "example": "model_error" }, "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the request finished.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "person_id", "feature", "model", "subject_table", "subject_id", "outcome", "prompt_redacted", "output_redacted", "failure_code", "completed_at" ], "description": "One Aurora model call: who asked, for which feature, with which configured model, and the prompt and output with personal data redacted. Restricted fields and medical records are never in it." }, "AiRequestOutcome": { "type": "string", "enum": ["Pending", "Answered", "No Answer", "Failed"], "description": "How a model call ended. No Answer is the silence rule (Section 3.7).", "example": "Answered" }, "AiUsagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AiUsage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AiUsage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the ai usage.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "request_id": { "type": "string", "format": "uuid", "description": "Identifier of the AI request metered.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "metered_at": { "type": "string", "format": "date-time", "description": "When the request was authorized and counted.", "example": "2026-10-08T14:30:00Z" }, "input_tokens": { "type": ["integer", "null"], "minimum": 0, "description": "Input tokens the model reported.", "example": 812 }, "output_tokens": { "type": ["integer", "null"], "minimum": 0, "description": "Output tokens the model reported.", "example": 96 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "request_id", "metered_at", "input_tokens", "output_tokens" ], "description": "Aurora metering (ADR 0020): one row per authorized request. The monthly allowance aurora_requests_per_month counts these rows by UTC month." }, "WorkDetailsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetails" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkDetails": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the work details.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person the work details belong to; always the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shirt_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "jacket_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "pants_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Pants size as the person writes it.", "example": "32x32" }, "shoe_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Shoe size with its system.", "example": "US 10.5" }, "glove_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "hat_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Hat size as the person writes it.", "example": "7 1/4" }, "uniform_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Anything else about fit.", "example": "Prefers a relaxed cut." }, "dietary_needs": { "type": "array", "items": { "$ref": "#/components/schemas/DietaryNeed" }, "maxItems": 9, "description": "Dietary needs, each once, in enum order.", "example": ["Vegan"] }, "allergies": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Allergies in the person's words, with how severe.", "example": "Peanuts, severe" }, "dietary_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Other dietary notes.", "example": "No pork." }, "accessibility_needs": { "type": "array", "items": { "$ref": "#/components/schemas/AccessibilityNeed" }, "maxItems": 10, "description": "Accessibility needs, each once, in enum order.", "example": ["Seating"] }, "accessibility_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Accessibility needs in the person's words.", "example": "Needs a seat near the stage door." }, "seat_preference": { "anyOf": [{ "$ref": "#/components/schemas/SeatPreference" }, { "type": "null" }] }, "meal_preference": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Preferred in-flight meal.", "example": "Vegetarian (VGML)" }, "home_airport": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "IATA airport code.", "example": "MIA" }, "passport_number": { "anyOf": [ { "type": "string", "minLength": 5, "maxLength": 30, "description": "Passport number, write-only: letters and digits are kept and encrypted. Send null to clear it.", "example": "YA0000TEST" }, { "$ref": "#/components/schemas/Masked" }, { "type": "null" } ] }, "passport_number_last4": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Last four characters of the passport number.", "example": "TEST" }, "passport_issuing_country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "Country that issued the passport.", "example": "US" }, "passport_expires_on": { "type": ["string", "null"], "format": "date", "description": "Day the passport expires.", "example": "2026-10-08" }, "passport_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Name exactly as printed in the passport.", "example": "IVY MARCHETTI" } }, "required": [ "id", "created_at", "updated_at", "person_id", "shirt_size", "jacket_size", "pants_size", "shoe_size", "glove_size", "hat_size", "uniform_notes", "dietary_needs", "allergies", "dietary_notes", "accessibility_needs", "accessibility_notes", "seat_preference", "meal_preference", "home_airport", "passport_number", "passport_number_last4", "passport_issuing_country", "passport_expires_on", "passport_name" ], "description": "The caller's own work details (Section 4.5.6 item 10): uniform sizes, dietary and accessibility needs and the travel profile. Read and written only by the person; an engaging org sees a category only while the person shares it with that engagement. The passport number is Restricted and encrypted: it is written here, always read masked, and shown only through the logged revealPassport action. One live row per person (409 on a second)." }, "GarmentLetterSize": { "type": "string", "enum": ["XXS", "XS", "S", "M", "L", "XL", "2XL", "3XL", "4XL", "5XL"], "description": "Letter size for a shirt, jacket or gloves.", "example": "XXS" }, "DietaryNeed": { "type": "string", "enum": [ "Vegetarian", "Vegan", "Pescatarian", "Halal", "Kosher", "Gluten Free", "Dairy Free", "Nut Free", "Shellfish Free" ], "description": "A dietary need hospitality caters for.", "example": "Vegetarian" }, "AccessibilityNeed": { "type": "string", "enum": [ "Step-Free Access", "Accessible Parking", "Accessible Restroom", "Seating", "Sign Language Interpreter", "Captioning", "Large Print", "Service Animal", "Quiet Space", "Assistance on Arrival" ], "description": "An accessibility need the person asks an engaging org to plan for.", "example": "Step-Free Access" }, "SeatPreference": { "type": "string", "enum": ["Window", "Aisle", "No Preference"], "description": "Preferred seat when an org books travel.", "example": "Window" }, "WorkDetailsCreate": { "type": "object", "properties": { "shirt_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "jacket_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "pants_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Pants size as the person writes it.", "example": "32x32" }, "shoe_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Shoe size with its system.", "example": "US 10.5" }, "glove_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "hat_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Hat size as the person writes it.", "example": "7 1/4" }, "uniform_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Anything else about fit.", "example": "Prefers a relaxed cut." }, "dietary_needs": { "type": "array", "items": { "$ref": "#/components/schemas/DietaryNeed" }, "maxItems": 9, "description": "Dietary needs, each once, in enum order.", "example": ["Vegan"] }, "allergies": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Allergies in the person's words, with how severe.", "example": "Peanuts, severe" }, "dietary_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Other dietary notes.", "example": "No pork." }, "accessibility_needs": { "type": "array", "items": { "$ref": "#/components/schemas/AccessibilityNeed" }, "maxItems": 10, "description": "Accessibility needs, each once, in enum order.", "example": ["Seating"] }, "accessibility_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Accessibility needs in the person's words.", "example": "Needs a seat near the stage door." }, "seat_preference": { "anyOf": [{ "$ref": "#/components/schemas/SeatPreference" }, { "type": "null" }] }, "meal_preference": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Preferred in-flight meal.", "example": "Vegetarian (VGML)" }, "home_airport": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "IATA airport code.", "example": "MIA" }, "passport_number": { "type": ["string", "null"], "minLength": 5, "maxLength": 30, "description": "Passport number, write-only: letters and digits are kept and encrypted. Send null to clear it.", "example": "YA0000TEST" }, "passport_issuing_country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "Country that issued the passport.", "example": "US" }, "passport_expires_on": { "type": ["string", "null"], "format": "date", "description": "Day the passport expires.", "example": "2026-10-08" }, "passport_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Name exactly as printed in the passport.", "example": "IVY MARCHETTI" } }, "description": "Fields accepted when creating a WorkDetails." }, "WorkDetailsUpdate": { "type": "object", "properties": { "shirt_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "jacket_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "pants_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Pants size as the person writes it.", "example": "32x32" }, "shoe_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Shoe size with its system.", "example": "US 10.5" }, "glove_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "hat_size": { "type": ["string", "null"], "minLength": 1, "maxLength": 20, "description": "Hat size as the person writes it.", "example": "7 1/4" }, "uniform_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Anything else about fit.", "example": "Prefers a relaxed cut." }, "dietary_needs": { "type": "array", "items": { "$ref": "#/components/schemas/DietaryNeed" }, "maxItems": 9, "description": "Dietary needs, each once, in enum order.", "example": ["Vegan"] }, "allergies": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Allergies in the person's words, with how severe.", "example": "Peanuts, severe" }, "dietary_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Other dietary notes.", "example": "No pork." }, "accessibility_needs": { "type": "array", "items": { "$ref": "#/components/schemas/AccessibilityNeed" }, "maxItems": 10, "description": "Accessibility needs, each once, in enum order.", "example": ["Seating"] }, "accessibility_notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Accessibility needs in the person's words.", "example": "Needs a seat near the stage door." }, "seat_preference": { "anyOf": [{ "$ref": "#/components/schemas/SeatPreference" }, { "type": "null" }] }, "meal_preference": { "type": ["string", "null"], "minLength": 1, "maxLength": 100, "description": "Preferred in-flight meal.", "example": "Vegetarian (VGML)" }, "home_airport": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "IATA airport code.", "example": "MIA" }, "passport_number": { "type": ["string", "null"], "minLength": 5, "maxLength": 30, "description": "Passport number, write-only: letters and digits are kept and encrypted. Send null to clear it.", "example": "YA0000TEST" }, "passport_issuing_country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "Country that issued the passport.", "example": "US" }, "passport_expires_on": { "type": ["string", "null"], "format": "date", "description": "Day the passport expires.", "example": "2026-10-08" }, "passport_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Name exactly as printed in the passport.", "example": "IVY MARCHETTI" } }, "description": "Fields accepted when updating a WorkDetails. Omitted fields are unchanged." }, "PassportReveal": { "type": "object", "properties": { "passport_number": { "type": "string", "description": "The passport number in plain text.", "example": "YA0000TEST" } }, "required": ["passport_number"], "description": "A revealed passport number. Each reveal is written to the person's access log." }, "EmergencyContactPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmergencyContact" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EmergencyContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the emergency contact.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person the contact belongs to; always the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "full_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Contact's name.", "example": "Marco Marchetti" }, "relationship": { "type": ["string", "null"], "minLength": 1, "maxLength": 60, "description": "How the contact relates to the person.", "example": "Brother" }, "phone_e164": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "Contact's phone. E.164 format.", "example": "+13055550142" }, "alternate_phone_e164": { "type": ["string", "null"], "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "A second phone. E.164 format.", "example": "+13055550142" }, "email": { "type": ["string", "null"], "format": "email", "description": "Contact's email address.", "example": "alex.rivera@northwindlive.example" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Order to call in, lowest first.", "example": 0 } }, "required": [ "id", "created_at", "updated_at", "person_id", "full_name", "relationship", "phone_e164", "alternate_phone_e164", "email", "sort_order" ], "description": "One of the caller's emergency contacts (Section 4.5.6 item 10), in calling order, at most five (422 emergency_contact_limit). Phones are E.164 (Section 15). Shared with an engagement under the Emergency Contacts category." }, "EmergencyContactCreate": { "type": "object", "properties": { "full_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Contact's name.", "example": "Marco Marchetti" }, "relationship": { "type": ["string", "null"], "minLength": 1, "maxLength": 60, "description": "How the contact relates to the person.", "example": "Brother" }, "phone_e164": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "Contact's phone. E.164 format.", "example": "+13055550142" }, "alternate_phone_e164": { "type": ["string", "null"], "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "A second phone. E.164 format.", "example": "+13055550142" }, "email": { "type": ["string", "null"], "format": "email", "description": "Contact's email address.", "example": "alex.rivera@northwindlive.example" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Order to call in, lowest first.", "example": 0 } }, "required": ["full_name", "phone_e164"], "description": "Fields accepted when creating a EmergencyContact." }, "EmergencyContactUpdate": { "type": "object", "properties": { "full_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Contact's name.", "example": "Marco Marchetti" }, "relationship": { "type": ["string", "null"], "minLength": 1, "maxLength": 60, "description": "How the contact relates to the person.", "example": "Brother" }, "phone_e164": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "Contact's phone. E.164 format.", "example": "+13055550142" }, "alternate_phone_e164": { "type": ["string", "null"], "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "A second phone. E.164 format.", "example": "+13055550142" }, "email": { "type": ["string", "null"], "format": "email", "description": "Contact's email address.", "example": "alex.rivera@northwindlive.example" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Order to call in, lowest first.", "example": 0 } }, "description": "Fields accepted when updating a EmergencyContact. Omitted fields are unchanged." }, "LoyaltyProgramPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyProgram" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "LoyaltyProgram": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the loyalty program.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person the program belongs to; always the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "program_kind": { "$ref": "#/components/schemas/LoyaltyProgramKind" }, "program_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Program.", "example": "SkyMiles" }, "member_number": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Membership number.", "example": "SM-0000-TEST" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Display order.", "example": 0 } }, "required": [ "id", "created_at", "updated_at", "person_id", "program_kind", "program_name", "member_number", "sort_order" ], "description": "A travel loyalty program the caller belongs to, at most twenty (422 loyalty_program_limit). A program name appears once per kind (409). Shared with an engagement under the Travel Profile category." }, "LoyaltyProgramKind": { "type": "string", "enum": ["Airline", "Hotel", "Car Rental", "Rail"], "description": "Kind of travel loyalty program.", "example": "Airline" }, "LoyaltyProgramCreate": { "type": "object", "properties": { "program_kind": { "$ref": "#/components/schemas/LoyaltyProgramKind" }, "program_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Program.", "example": "SkyMiles" }, "member_number": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Membership number.", "example": "SM-0000-TEST" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Display order.", "example": 0 } }, "required": ["program_kind", "program_name", "member_number"], "description": "Fields accepted when creating a LoyaltyProgram." }, "LoyaltyProgramUpdate": { "type": "object", "properties": { "program_kind": { "$ref": "#/components/schemas/LoyaltyProgramKind" }, "program_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Program.", "example": "SkyMiles" }, "member_number": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Membership number.", "example": "SM-0000-TEST" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Display order.", "example": 0 } }, "description": "Fields accepted when updating a LoyaltyProgram. Omitted fields are unchanged." }, "WorkDetailSharePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailShare" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkDetailShare": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the work detail share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement the share serves; the caller must be its person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person sharing.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "consent_record_id": { "type": "string", "format": "uuid", "description": "Identifier of the work_details_sharing consent record for the org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailCategory" }, "minItems": 1, "maxItems": 6, "description": "Categories shared.", "example": ["Dietary Needs", "Emergency Contacts"] }, "shared_at": { "type": "string", "format": "date-time", "description": "When the share was given.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the person revoked it; null while it stands.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "engagement_id", "person_id", "consent_record_id", "categories", "shared_at", "revoked_at" ], "description": "The caller's consent to share chosen categories of their work details with the org that engages them, for one engagement, under a work_details_sharing consent record (Section 14.3). Creating a share for an engagement that already has one replaces its categories; fewer categories is a partial revocation. Revoke ends it at once and withdraws the org's consent with its last share. Shares cannot be made once the engagement is Complete or Canceled (422 work_detail_share_closed). The person and the engaging org read shares; only the person writes them." }, "WorkDetailCategory": { "type": "string", "enum": [ "Emergency Contacts", "Uniform Sizes", "Dietary Needs", "Accessibility Needs", "Travel Profile", "Passport" ], "description": "A category of work details shared with an engaging org on its own. Travel Profile is seat and meal preference, home airport and loyalty programs; Passport is the passport details.", "example": "Emergency Contacts" }, "WorkDetailShareCreate": { "type": "object", "properties": { "engagement_id": { "type": "string", "format": "uuid", "description": "Identifier of the engagement the share serves; the caller must be its person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailCategory" }, "minItems": 1, "maxItems": 6, "description": "Categories shared.", "example": ["Dietary Needs", "Emergency Contacts"] } }, "required": ["engagement_id", "categories"], "description": "Fields accepted when creating a WorkDetailShare." }, "WorkDetailShareUpdate": { "type": "object", "properties": { "categories": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailCategory" }, "minItems": 1, "maxItems": 6, "description": "Categories shared.", "example": ["Dietary Needs", "Emergency Contacts"] } }, "description": "Fields accepted when updating a WorkDetailShare. Omitted fields are unchanged." }, "SharedWorkDetails": { "type": "object", "properties": { "engagement_id": { "type": "string", "format": "uuid", "description": "Engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": ["string", "null"], "format": "uuid", "description": "Person the engagement names.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Engaging org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "work_detail_share_id": { "type": ["string", "null"], "format": "uuid", "description": "Live share; null when none stands.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shared_at": { "type": ["string", "null"], "format": "date-time", "description": "When the share was given.", "example": "2026-10-08T14:30:00Z" }, "sharing_open": { "type": "boolean", "description": "The engagement is Onboarding to Closing; a closed engagement reads nothing.", "example": true }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailCategory" }, "description": "Categories the person shared.", "example": ["Dietary Needs"] }, "readable": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailCategory" }, "description": "Shared categories the caller's project capabilities cover; the others come back null.", "example": ["Dietary Needs"] }, "emergency_contacts": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/SharedEmergencyContact" } }, "uniform": { "anyOf": [{ "$ref": "#/components/schemas/SharedUniformSizes" }, { "type": "null" }] }, "dietary": { "anyOf": [{ "$ref": "#/components/schemas/SharedDietaryNeeds" }, { "type": "null" }] }, "accessibility": { "anyOf": [ { "$ref": "#/components/schemas/SharedAccessibilityNeeds" }, { "type": "null" } ] }, "travel": { "anyOf": [{ "$ref": "#/components/schemas/SharedTravelProfile" }, { "type": "null" }] }, "passport": { "anyOf": [{ "$ref": "#/components/schemas/SharedPassport" }, { "type": "null" }] } }, "required": [ "engagement_id", "person_id", "org_id", "work_detail_share_id", "shared_at", "sharing_open", "categories", "readable", "emergency_contacts", "uniform", "dietary", "accessibility", "travel", "passport" ], "description": "What the person an engagement names shared of their work details, as the caller may read it. Unshared or unreadable categories are null; the passport number is always masked." }, "SharedEmergencyContact": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Contact's name.", "example": "Marco Marchetti" }, "relationship": { "type": ["string", "null"], "description": "Relationship.", "example": "Brother" }, "phone_e164": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "Contact's phone. E.164 format.", "example": "+13055550142" }, "alternate_phone_e164": { "type": ["string", "null"], "pattern": "^\\+[1-9][0-9]{6,14}$", "description": "A second phone. E.164 format.", "example": "+13055550142" }, "email": { "type": ["string", "null"], "description": "Email address.", "example": "marco@example.com" }, "sort_order": { "type": "integer", "description": "Calling order.", "example": 0 } }, "required": [ "full_name", "relationship", "phone_e164", "alternate_phone_e164", "email", "sort_order" ], "description": "An emergency contact as an engaging org reads it." }, "SharedUniformSizes": { "type": "object", "properties": { "shirt_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "jacket_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "pants_size": { "type": ["string", "null"], "description": "Pants size.", "example": "32x32" }, "shoe_size": { "type": ["string", "null"], "description": "Shoe size.", "example": "US 10.5" }, "glove_size": { "anyOf": [{ "$ref": "#/components/schemas/GarmentLetterSize" }, { "type": "null" }] }, "hat_size": { "type": ["string", "null"], "description": "Hat size.", "example": "7 1/4" }, "uniform_notes": { "type": ["string", "null"], "description": "Fit notes.", "example": "Prefers a relaxed cut." } }, "required": [ "shirt_size", "jacket_size", "pants_size", "shoe_size", "glove_size", "hat_size", "uniform_notes" ], "description": "Uniform sizes as an engaging org reads them." }, "SharedDietaryNeeds": { "type": "object", "properties": { "dietary_needs": { "type": "array", "items": { "$ref": "#/components/schemas/DietaryNeed" } }, "allergies": { "type": ["string", "null"], "description": "Allergies.", "example": "Peanuts, severe" }, "dietary_notes": { "type": ["string", "null"], "description": "Other dietary notes.", "example": "No pork." } }, "required": ["dietary_needs", "allergies", "dietary_notes"], "description": "Dietary needs as an engaging org reads them." }, "SharedAccessibilityNeeds": { "type": "object", "properties": { "accessibility_needs": { "type": "array", "items": { "$ref": "#/components/schemas/AccessibilityNeed" } }, "accessibility_notes": { "type": ["string", "null"], "description": "Accessibility notes.", "example": "Needs a seat near the stage door." } }, "required": ["accessibility_needs", "accessibility_notes"], "description": "Accessibility needs as an engaging org reads them." }, "SharedTravelProfile": { "type": "object", "properties": { "seat_preference": { "anyOf": [{ "$ref": "#/components/schemas/SeatPreference" }, { "type": "null" }] }, "meal_preference": { "type": ["string", "null"], "description": "Preferred in-flight meal.", "example": "Vegetarian (VGML)" }, "home_airport": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "IATA airport code.", "example": "MIA" }, "loyalty_programs": { "type": "array", "items": { "$ref": "#/components/schemas/SharedLoyaltyProgram" } } }, "required": ["seat_preference", "meal_preference", "home_airport", "loyalty_programs"], "description": "The travel profile as an engaging org reads it." }, "SharedLoyaltyProgram": { "type": "object", "properties": { "program_kind": { "$ref": "#/components/schemas/LoyaltyProgramKind" }, "program_name": { "type": "string", "description": "Program.", "example": "SkyMiles" }, "member_number": { "type": "string", "description": "Membership number.", "example": "SM-0000-TEST" } }, "required": ["program_kind", "program_name", "member_number"], "description": "A loyalty program as an engaging org reads it." }, "SharedPassport": { "type": "object", "properties": { "passport_number": { "type": "null", "description": "Always null: the number is masked; reveal it through revealPassport.", "example": null }, "passport_number_last4": { "type": ["string", "null"], "description": "Last four characters of the number.", "example": "TEST" }, "passport_number_masked": { "type": "boolean", "description": "A number is recorded and withheld.", "example": true }, "passport_issuing_country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "Country that issued the passport.", "example": "US" }, "passport_expires_on": { "type": ["string", "null"], "format": "date", "description": "Day the passport expires.", "example": "2026-10-08" }, "passport_name": { "type": ["string", "null"], "description": "Name as printed in the passport.", "example": "IVY MARCHETTI" } }, "required": [ "passport_number", "passport_number_last4", "passport_number_masked", "passport_issuing_country", "passport_expires_on", "passport_name" ], "description": "Passport details as an engaging org reads them, the number masked." }, "PassportRevealRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500, "description": "Why the number is needed, 10 to 500 characters. Logged with the reveal.", "example": "Booking the June flights." } }, "required": ["reason"], "description": "Request to reveal a shared passport number." }, "WorkDetailEventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailEvent" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkDetailEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person whose work details were touched.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "actor_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who acted; null for the database or a service.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org whose member acted or whose share changed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "engagement_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the engagement of a share, read or reveal.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "action": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$", "description": "What happened, as subject.verb: person_work_details.update, work_details.shared, work_details.share_changed, work_details.share_revoked, work_details.viewed, passport.revealed and others.", "example": "work_details.viewed" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/WorkDetailCategory" }, "description": "Categories the act covered.", "example": ["Dietary Needs"] }, "changed_columns": { "type": "array", "items": { "type": "string" }, "description": "Columns an owner change touched, never their values.", "example": ["allergies"] }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Reason an org member gave for revealing the passport number.", "example": "Booking the June flights." }, "created_at": { "type": "string", "format": "date-time", "description": "When it happened.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "person_id", "actor_person_id", "org_id", "engagement_id", "action", "categories", "changed_columns", "reason", "created_at" ], "description": "One entry of a person's work details access log (Section 8.4): a change they made, a share or revocation, or a read or reveal by an engaging org, with the categories and changed column names but never a value. The person reads all of theirs; an org's audit readers read the entries naming their org." }, "SavedViewSharePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedViewShare" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SavedViewShare": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the saved view share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "saved_view_id": { "type": "string", "format": "uuid", "description": "Identifier of the saved view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team of the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "saved_view_id", "team_id" ], "description": "A saved view shared with one team of its org (0641). Only the view's owner shares or unshares it; team members open it and see only the rows their own access allows." }, "SavedViewShareCreate": { "type": "object", "properties": { "saved_view_id": { "type": "string", "format": "uuid", "description": "Identifier of the saved view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team of the same org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["saved_view_id", "team_id"], "description": "Fields accepted when creating a SavedViewShare." }, "SavedViewDefaultPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedViewDefault" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SavedViewDefault": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the saved view default.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the caller, set by the server.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "collection_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\/[a-z][a-z0-9_]*)?$", "description": "Collection (page) the default applies to, as saved views name it.", "example": "logistics/shipments" }, "saved_view_id": { "type": "string", "format": "uuid", "description": "Identifier of the saved view the caller can read, of the same collection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "membership_id", "collection_key", "saved_view_id" ], "description": "The saved view the caller opens by default on a page (0641): one per member and collection. Creating one replaces the earlier default of the page (app.set_saved_view_default)." }, "SavedViewDefaultCreate": { "type": "object", "properties": { "saved_view_id": { "type": "string", "format": "uuid", "description": "Identifier of the saved view the caller can read, of the same collection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["saved_view_id"], "description": "Fields accepted when creating a SavedViewDefault." }, "TourProgressPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TourProgress" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TourProgress": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the tour progress.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the caller, set by the server.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tour_key": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$", "description": "Tour key from the help content.", "example": "atlas.getting-started" }, "tour_state": { "type": "string", "enum": ["Offered", "Started", "Completed", "Dismissed"], "description": "Offered, Started, Completed or Dismissed.", "example": "Started" }, "step": { "type": "integer", "minimum": 0, "description": "Last step reached, from 0.", "example": 2 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "membership_id", "tour_key", "tour_state", "step" ], "description": "The caller's progress through one guided tour (0642). A tour is offered once (the row exists from then on), can be replayed by moving it to Started at step 0, and is never offered again." }, "TourProgressCreate": { "type": "object", "properties": { "tour_key": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$", "description": "Tour key from the help content.", "example": "atlas.getting-started" }, "tour_state": { "type": "string", "enum": ["Offered", "Started", "Completed", "Dismissed"], "description": "Offered, Started, Completed or Dismissed.", "example": "Started" }, "step": { "type": "integer", "minimum": 0, "description": "Last step reached, from 0.", "example": 2 } }, "required": ["tour_key", "tour_state", "step"], "description": "Fields accepted when creating a TourProgress." }, "TourProgressUpdate": { "type": "object", "properties": { "tour_state": { "type": "string", "enum": ["Offered", "Started", "Completed", "Dismissed"], "description": "Offered, Started, Completed or Dismissed.", "example": "Started" }, "step": { "type": "integer", "minimum": 0, "description": "Last step reached, from 0.", "example": 2 } }, "description": "Fields accepted when updating a TourProgress. Omitted fields are unchanged." }, "TipDismissalPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TipDismissal" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TipDismissal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the tip dismissal.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the caller, set by the server.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "tip_key": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$", "description": "Tip key from the help content.", "example": "gates" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "membership_id", "tip_key" ], "description": "A contextual tip the caller dismissed (0642). Deleting it shows the tip again; a reset dismissal is never revived." }, "TipDismissalCreate": { "type": "object", "properties": { "tip_key": { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$", "description": "Tip key from the help content.", "example": "gates" } }, "required": ["tip_key"], "description": "Fields accepted when creating a TipDismissal." }, "SupportTicketPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicket" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SupportTicket": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the membership of the requester, set by the server.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "ticket_number": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Display number, SUP-0001 upward per org.", "example": "SUP-0001" }, "queue": { "type": "string", "enum": ["Organization", "Platform"], "description": "Organization or Platform.", "example": "Organization" }, "category": { "type": "string", "enum": ["Question", "Problem", "Access", "Billing", "Account", "Feature Request"], "description": "What the request is about.", "example": "Access" }, "severity": { "type": "string", "enum": ["Severity 1", "Severity 2", "Severity 3", "Severity 4"], "description": "Severity 1 (outage) to Severity 4 (question).", "example": "Severity 3" }, "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "One-line summary.", "example": "Scanner shows an unknown zone" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What happened and what the requester needs.", "example": "At the north gate the scanner says the zone is unknown." }, "ticket_state": { "type": "string", "enum": ["Open", "Waiting", "Resolved", "Closed"], "description": "Open, Waiting, Resolved or Closed; moved by the transition action.", "example": "Open" }, "channel": { "type": "string", "enum": ["In App", "Email", "Chat", "Priority Queue", "Dedicated Channel"], "description": "In App for the Organization queue; by plan for the Platform queue.", "example": "In App" }, "first_response_due_at": { "type": ["string", "null"], "format": "date-time", "description": "Platform first response deadline from the plan; null for best effort.", "example": "2026-10-08T14:30:00Z" }, "first_responded_at": { "type": ["string", "null"], "format": "date-time", "description": "When a responder first answered.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "membership_id", "ticket_number", "queue", "category", "severity", "subject", "body", "ticket_state", "channel", "first_response_due_at", "first_responded_at" ], "description": "A request for help (0643): to the org's own admins (Organization queue) or, from holders of org.help.write, to the platform team (Platform queue), whose channel and first response deadline follow the plan. Readable by the requester and by those who answer support for the org." }, "SupportTicketOpenRequest": { "type": "object", "properties": { "queue": { "type": "string", "enum": ["Organization", "Platform"], "description": "Organization or Platform.", "example": "Organization" }, "category": { "type": "string", "enum": ["Question", "Problem", "Access", "Billing", "Account", "Feature Request"], "description": "What the request is about.", "example": "Access" }, "severity": { "type": "string", "enum": ["Severity 1", "Severity 2", "Severity 3", "Severity 4"], "description": "Severity 1 to 4; Severity 3 when omitted.", "example": "Severity 3" }, "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "One-line summary.", "example": "Scanner shows an unknown zone" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What happened and what the requester needs.", "example": "Zone B denies Crew." }, "diagnostics": { "type": "object", "properties": { "consent": { "type": "boolean", "enum": [true], "description": "Must be true: diagnostics are stored only with the requester's consent.", "example": true }, "route": { "type": "string", "maxLength": 500, "description": "Page the requester was on.", "example": "/demo/credentials/scans" }, "app_version": { "type": "string", "maxLength": 50, "description": "App version and build.", "example": "4.0.0 (812)" }, "device": { "type": "string", "maxLength": 300, "description": "Browser or device.", "example": "Safari 19 on iOS 26" }, "recent_errors": { "type": "string", "maxLength": 4000, "description": "Recent client errors, newest first.", "example": "TypeError" } }, "required": ["consent"], "description": "Diagnostics to attach, with consent." } }, "required": ["queue", "category", "subject", "body"], "description": "A new support request." }, "SupportTicketTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Open", "Waiting", "Resolved", "Closed"], "description": "The state the caller believes the row is in (compare-and-set).", "example": "Open" }, "to_state": { "type": "string", "enum": ["Open", "Waiting", "Resolved", "Closed"], "description": "Target state.", "example": "Waiting" }, "reason": { "type": "string", "minLength": 1, "description": "Reason, required by some transitions.", "example": "Client approved the revised scope." } }, "required": ["expected_state", "to_state"], "description": "Request to move a lifecycle to another state." }, "SupportTicketMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "support_ticket_id": { "type": "string", "format": "uuid", "description": "Identifier of the support request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "author_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who wrote it; null for the platform team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Message text.", "example": "Which zone did you pick?" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "support_ticket_id", "author_membership_id", "body" ], "description": "One message on a support request (0643), oldest first. Append-only; posted with the reply action." }, "SupportTicketReplyRequest": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Message text.", "example": "Zone B, backstage." } }, "required": ["body"], "description": "A reply on a support request." }, "SupportTicketMessagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicketMessage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SupportTicketDiagnosticsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicketDiagnostics" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SupportTicketDiagnostics": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket diagnostics.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "support_ticket_id": { "type": "string", "format": "uuid", "description": "Identifier of the support request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "consented_at": { "type": "string", "format": "date-time", "description": "When the requester agreed to send the diagnostics.", "example": "2026-10-08T14:30:00Z" }, "route": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Page the requester was on.", "example": "/demo/credentials/scans" }, "app_version": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "description": "App version and build.", "example": "4.0.0 (812)" }, "device": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Browser or device and operating system.", "example": "Safari 19 on iOS 26" }, "recent_errors": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Recent client errors, newest first.", "example": "TypeError" }, "screenshot_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Storage path of a screenshot.", "example": "org/ticket/shot.png" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "support_ticket_id", "consented_at", "route", "app_version", "device", "recent_errors", "screenshot_path" ], "description": "Diagnostics the requester chose to attach to a support request (0643), with the moment they consented. Append-only." }, "ApprovalStepPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStep" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ApprovalStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the approval step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approval_policy_id": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "step_order": { "type": "integer", "minimum": 1, "description": "Position of the step, 1 first; steps are decided in order.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Step name.", "example": "Department head" }, "approver_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role whose holders decide the step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approver_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the the one member who decides the step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "approval_policy_id", "step_order", "name", "approver_role_id", "approver_membership_id" ], "description": "An ordered step of an approval policy (1030). It names its approvers: everyone holding a role, or one member. Steps change only while the policy is a Draft (approval_step_policy_not_draft: 422)." }, "ApprovalStepCreate": { "type": "object", "properties": { "approval_policy_id": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "step_order": { "type": "integer", "minimum": 1, "description": "Position of the step, 1 first; steps are decided in order.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Step name.", "example": "Department head" }, "approver_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role whose holders decide the step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approver_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the the one member who decides the step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["approval_policy_id", "step_order", "name"], "description": "Fields accepted when creating a ApprovalStep." }, "ApprovalStepUpdate": { "type": "object", "properties": { "step_order": { "type": "integer", "minimum": 1, "description": "Position of the step, 1 first; steps are decided in order.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Step name.", "example": "Department head" }, "approver_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the role whose holders decide the step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "approver_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the the one member who decides the step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a ApprovalStep. Omitted fields are unchanged." }, "TemplateVersionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVersion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TemplateVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the template version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "template_id": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "version_number": { "type": "integer", "minimum": 1, "description": "Version number, issued in order, 1 first.", "example": 1 }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What changed in this version.", "example": "Adds the load-out records." }, "default_time_zone": { "type": ["string", "null"], "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone a new project starts with.", "example": "America/New_York" }, "default_tier_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon tier a new project starts with.", "example": "05" }, "default_region_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon region a new project starts with.", "example": "SE" }, "default_jurisdiction_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon jurisdiction a new project starts with.", "example": "US-FL-MIAMI-DADE" }, "default_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency a new project starts with.", "example": "USD" }, "duration_days": { "type": ["integer", "null"], "minimum": 1, "description": "Length of the project in days.", "example": 3 }, "published_at": { "type": ["string", "null"], "format": "date-time", "description": "When the version was published; null while a draft.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "template_id", "version_number", "notes", "default_time_zone", "default_tier_code", "default_region_code", "default_jurisdiction_id", "default_currency_code", "duration_days", "published_at" ], "description": "A version of a template (1032): the project defaults and ordered items. Edited while a draft; publishing (templateVersions.publish) freezes it and makes it the template's current version." }, "TemplateVersionCreate": { "type": "object", "properties": { "template_id": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What changed in this version.", "example": "Adds the load-out records." }, "default_time_zone": { "type": ["string", "null"], "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone a new project starts with.", "example": "America/New_York" }, "default_tier_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon tier a new project starts with.", "example": "05" }, "default_region_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon region a new project starts with.", "example": "SE" }, "default_jurisdiction_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon jurisdiction a new project starts with.", "example": "US-FL-MIAMI-DADE" }, "default_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency a new project starts with.", "example": "USD" }, "duration_days": { "type": ["integer", "null"], "minimum": 1, "description": "Length of the project in days.", "example": 3 } }, "required": ["template_id"], "description": "Fields accepted when creating a TemplateVersion." }, "TemplateVersionUpdate": { "type": "object", "properties": { "notes": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "What changed in this version.", "example": "Adds the load-out records." }, "default_time_zone": { "type": ["string", "null"], "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+)*$", "description": "IANA time zone a new project starts with.", "example": "America/New_York" }, "default_tier_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon tier a new project starts with.", "example": "05" }, "default_region_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon region a new project starts with.", "example": "SE" }, "default_jurisdiction_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon jurisdiction a new project starts with.", "example": "US-FL-MIAMI-DADE" }, "default_currency_code": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency a new project starts with.", "example": "USD" }, "duration_days": { "type": ["integer", "null"], "minimum": 1, "description": "Length of the project in days.", "example": 3 } }, "description": "Fields accepted when updating a TemplateVersion. Omitted fields are unchanged." }, "TemplateItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TemplateItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the template item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "template_version_id": { "type": "string", "format": "uuid", "description": "Identifier of the template version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "item_kind": { "type": "string", "enum": ["Scope Node", "Record"], "description": "What the item creates.", "example": "Scope Node" }, "sort_order": { "type": "integer", "minimum": 1, "description": "Position in the version, 1 first.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Scope node name, or record title.", "example": "Opening Night" }, "scope_kind": { "type": ["string", "null"], "enum": ["Standing Venue", "Show", null], "description": "For a scope node: Show or Standing Venue.", "example": "Show" }, "scope_code_suffix": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "For a scope node: code after the project key.", "example": "E02" }, "record_kind": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "description": "For a record: canon record kind.", "example": "Inspection" }, "xyz": { "type": ["string", "null"], "enum": ["X", "Y", "Z", null], "description": "For a record: declared schema family tag.", "example": "X" }, "phase_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "For a record: canon phase.", "example": "SCP" }, "due_offset_days": { "type": ["integer", "null"], "minimum": -3660, "maximum": 3660, "description": "For a record: due this many days after the project start; null for none.", "example": 3 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "template_version_id", "item_kind", "sort_order", "name", "scope_kind", "scope_code_suffix", "record_kind", "xyz", "phase_code", "due_offset_days" ], "description": "An item of a template version (1032): a scope node created under the new project's engagement root ({KEY}-{suffix}), or a record due a number of days after the project start. Items of a published version are frozen (template_version_published: 422)." }, "TemplateItemCreate": { "type": "object", "properties": { "template_version_id": { "type": "string", "format": "uuid", "description": "Identifier of the template version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "item_kind": { "type": "string", "enum": ["Scope Node", "Record"], "description": "What the item creates.", "example": "Scope Node" }, "sort_order": { "type": "integer", "minimum": 1, "description": "Position in the version, 1 first.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Scope node name, or record title.", "example": "Opening Night" }, "scope_kind": { "type": ["string", "null"], "enum": ["Standing Venue", "Show", null], "description": "For a scope node: Show or Standing Venue.", "example": "Show" }, "scope_code_suffix": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "For a scope node: code after the project key.", "example": "E02" }, "record_kind": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "description": "For a record: canon record kind.", "example": "Inspection" }, "xyz": { "type": ["string", "null"], "enum": ["X", "Y", "Z", null], "description": "For a record: declared schema family tag.", "example": "X" }, "phase_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "For a record: canon phase.", "example": "SCP" }, "due_offset_days": { "type": ["integer", "null"], "minimum": -3660, "maximum": 3660, "description": "For a record: due this many days after the project start; null for none.", "example": 3 } }, "required": ["template_version_id", "item_kind", "sort_order", "name"], "description": "Fields accepted when creating a TemplateItem." }, "TemplateItemUpdate": { "type": "object", "properties": { "sort_order": { "type": "integer", "minimum": 1, "description": "Position in the version, 1 first.", "example": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Scope node name, or record title.", "example": "Opening Night" }, "scope_kind": { "type": ["string", "null"], "enum": ["Standing Venue", "Show", null], "description": "For a scope node: Show or Standing Venue.", "example": "Show" }, "scope_code_suffix": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "For a scope node: code after the project key.", "example": "E02" }, "record_kind": { "type": ["string", "null"], "minLength": 1, "maxLength": 50, "description": "For a record: canon record kind.", "example": "Inspection" }, "xyz": { "type": ["string", "null"], "enum": ["X", "Y", "Z", null], "description": "For a record: declared schema family tag.", "example": "X" }, "phase_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "For a record: canon phase.", "example": "SCP" }, "due_offset_days": { "type": ["integer", "null"], "minimum": -3660, "maximum": 3660, "description": "For a record: due this many days after the project start; null for none.", "example": 3 } }, "description": "Fields accepted when updating a TemplateItem. Omitted fields are unchanged." }, "SupportSessionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupportSession" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SupportSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the support session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "grantee_org_id": { "type": "string", "format": "uuid", "description": "Identifier of the partner org whose staff may read while the session lasts.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the session was granted.", "example": "Help with the venue import." }, "starts_at": { "type": "string", "format": "date-time", "description": "When access began.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "When access ends on its own, at most 24 hours after it began.", "example": "2026-10-08T14:30:00Z" }, "ended_at": { "type": ["string", "null"], "format": "date-time", "description": "When someone ended the session early.", "example": "2026-10-08T14:30:00Z" }, "ended_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who ended it early.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "grantee_org_id", "reason", "starts_at", "ends_at", "ended_at", "ended_by" ], "description": "A support session (1060): the client org's Owner lets its partner's staff read the client org for 1 to 24 hours. Partner staff read nothing of a client without one; they never write. Created with supportSessions.grant and ended early with supportSessions.end." }, "SupportSessionGrantRequest": { "type": "object", "properties": { "hours": { "type": "integer", "minimum": 1, "description": "Length of the session in hours, 1 to 24.", "example": 4 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the partner needs access.", "example": "Help with the venue import." } }, "required": ["hours", "reason"], "description": "A support session to grant." }, "WholesaleStatementPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WholesaleStatement" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WholesaleStatement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the wholesale statement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "period_start": { "type": "string", "format": "date", "description": "First day of the month billed.", "example": "2026-10-08" }, "currency_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of the partner agreement.", "example": "USD" }, "wholesale_discount_bps": { "type": "integer", "minimum": 0, "description": "Discount in basis points when the statement ran; agreements default to 3000, the 30 percent of ADR 0035.", "example": 3000 }, "client_count": { "type": "integer", "minimum": 0, "description": "Client orgs on the statement.", "example": 3 }, "list_total_minor": { "type": ["integer", "null"], "minimum": 0, "description": "Sum of priced list prices in minor units; null only while a statement has no priced line.", "example": 44700 }, "wholesale_total_minor": { "type": ["integer", "null"], "minimum": 0, "description": "What the partner owes, in minor units; null only while a statement has no priced line.", "example": 31290 }, "unpriced_count": { "type": "integer", "minimum": 0, "description": "Lines whose plan is unpriced in the currency.", "example": 0 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "period_start", "currency_code", "wholesale_discount_bps", "client_count", "list_total_minor", "wholesale_total_minor", "unpriced_count" ], "description": "What the platform bills a partner for one month (1060): each client org at its plan's list price less the wholesale discount. Totals cover priced lines; unpriced lines are counted, never zero. Append-only." }, "WholesaleBillingRequest": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date", "description": "First day of the month to bill.", "example": "2026-10-08" } }, "required": ["period_start"], "description": "The month to bill." }, "OwnershipTransferPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OwnershipTransfer" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OwnershipTransfer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the ownership transfer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "from_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the Owner who offered the org.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the member the org is offered to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "previous_owner_outcome": { "type": "string", "enum": ["admin", "leave"], "description": "What happens to the Owner who offered on acceptance.", "example": "admin" }, "offered_at": { "type": "string", "format": "date-time", "description": "When the offer was made.", "example": "2026-10-08T14:30:00Z" }, "expires_at": { "type": "string", "format": "date-time", "description": "When an unanswered offer lapses, 7 days after it was made.", "example": "2026-10-08T14:30:00Z" }, "accepted_at": { "type": ["string", "null"], "format": "date-time", "description": "When the member accepted and became an Owner.", "example": "2026-10-08T14:30:00Z" }, "declined_at": { "type": ["string", "null"], "format": "date-time", "description": "When the member declined.", "example": "2026-10-08T14:30:00Z" }, "canceled_at": { "type": ["string", "null"], "format": "date-time", "description": "When an Owner withdrew the offer.", "example": "2026-10-08T14:30:00Z" }, "canceled_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Owner who withdrew it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "expired_at": { "type": ["string", "null"], "format": "date-time", "description": "When the lifecycle job lapsed the unanswered offer.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "from_person_id", "to_person_id", "previous_owner_outcome", "offered_at", "expires_at", "accepted_at", "declined_at", "canceled_at", "canceled_by", "expired_at" ], "description": "An Owner's offer to hand the org to another active member (1352, Section 14.7). The member accepts with step-up (a second factor) within 7 days; the old Owner then becomes an Admin, or leaves, and the org keeps an Owner at every step. Written only by the transfer actions; audited." }, "OwnershipTransferOfferRequest": { "type": "object", "properties": { "to_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the member to offer the org to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "previous_owner_outcome": { "type": "string", "enum": ["admin", "leave"], "description": "What happens to the offering Owner on acceptance.", "example": "admin" } }, "required": ["to_person_id", "previous_owner_outcome"], "description": "An ownership offer." }, "OrgDeletionRequestPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgDeletionRequest" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OrgDeletionRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the org deletion request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "reason": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why the org is deleted, in the Owner's words.", "example": "We are closing down." }, "requested_at": { "type": "string", "format": "date-time", "description": "When the Owner asked for deletion.", "example": "2026-10-08T14:30:00Z" }, "recover_until": { "type": "string", "format": "date-time", "description": "End of the 7-day recovery window.", "example": "2026-10-08T14:30:00Z" }, "requested_by": { "type": "string", "format": "uuid", "description": "Identifier of the Owner who asked for deletion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "recovered_at": { "type": ["string", "null"], "format": "date-time", "description": "When an Owner recovered the org.", "example": "2026-10-08T14:30:00Z" }, "recovered_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the Owner who recovered it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "reason", "requested_at", "recover_until", "requested_by", "recovered_at", "recovered_by" ], "description": "An Owner's request to delete the org (1351, Section 14.7), separate from cancellation: made with step-up and the typed name, it ends the subscription and makes the org read-only at once; an Owner may recover it for 7 days, after which the data is deleted and the Owner receives a deletion certificate." }, "OrgDeletionRequestCreate": { "type": "object", "properties": { "confirm_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The org's name, typed exactly.", "example": "Harbor Lights Productions" }, "reason": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Why the org is deleted.", "example": "We are closing down." } }, "required": ["confirm_name", "reason"], "description": "A deletion request." }, "DeletionCertificatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeletionCertificate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DeletionCertificate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the deletion certificate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "deleted_org_id": { "type": "string", "format": "uuid", "description": "Id the deleted org had.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Name of the org when it was deleted.", "example": "Harbor Lights Productions" }, "org_slug": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Web address of the org when it was deleted.", "example": "harbor-lights" }, "basis": { "type": "string", "enum": ["cancellation", "deletion_request"], "description": "Day 90 of a cancellation, or the end of a deletion request's recovery window.", "example": "cancellation" }, "requested_at": { "type": "string", "format": "date-time", "description": "When the Owner canceled or asked for deletion.", "example": "2026-10-08T14:30:00Z" }, "due_at": { "type": "string", "format": "date-time", "description": "When the data became due for deletion.", "example": "2026-10-08T14:30:00Z" }, "purged_at": { "type": ["string", "null"], "format": "date-time", "description": "When every row of the org was deleted.", "example": "2026-10-08T14:30:00Z" }, "tables_purged": { "type": ["integer", "null"], "minimum": 0, "description": "Tables rows were deleted from.", "example": 41 }, "rows_purged": { "type": ["integer", "null"], "minimum": 0, "description": "Rows deleted.", "example": 1820 }, "storage_objects_deleted": { "type": "integer", "minimum": 0, "description": "Stored files deleted.", "example": 12 }, "document_sha256": { "type": ["string", "null"], "minLength": 1, "maxLength": 64, "description": "SHA-256 of the certificate PDF.", "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "issued_at": { "type": ["string", "null"], "format": "date-time", "description": "When the certificate PDF was stored.", "example": "2026-10-08T14:30:00Z" }, "delivered_at": { "type": ["string", "null"], "format": "date-time", "description": "When the certificate was emailed to the former Owner.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "created_at", "updated_at", "deleted_org_id", "org_name", "org_slug", "basis", "requested_at", "due_at", "purged_at", "tables_purged", "rows_purged", "storage_objects_deleted", "document_sha256", "issued_at", "delivered_at" ], "description": "The record of an org whose data was deleted (1351, Section 14.7), kept after the org is gone. Read only by the former Owner it was issued to. The PDF itself is downloaded from Atlas." }, "PartnerStandingGrantPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerStandingGrant" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PartnerStandingGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the partner standing grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "partner_org_id": { "type": "string", "format": "uuid", "description": "Identifier of the partner org whose staff may read.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "The scope: one read capability a support session may grant.", "example": "org.settings.read" }, "agreement_reference": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The clause of the agreement that provides the grant.", "example": "Partner agreement, clause 7.2" }, "valid_from": { "type": "string", "format": "date-time", "description": "When access began.", "example": "2026-10-08T14:30:00Z" }, "valid_to": { "type": "string", "format": "date-time", "description": "When access ends on its own.", "example": "2026-10-08T14:30:00Z" }, "record_grant_id": { "type": "string", "format": "uuid", "description": "Identifier of the org-level record grant the standing grant issued.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "ended_at": { "type": ["string", "null"], "format": "date-time", "description": "When someone ended the grant early.", "example": "2026-10-08T14:30:00Z" }, "ended_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who ended it early.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "partner_org_id", "capability_code", "agreement_reference", "valid_from", "valid_to", "record_grant_id", "ended_at", "ended_by" ], "description": "A standing grant of the partner and client agreement (1354, Section 4.6.1): the client Owner lets the partner's staff read one area of the client org until an expiry within a year, citing the clause. Each issues an org-level record grant; either side may end it early. Partner staff never write through one." }, "PartnerStandingGrantRecordRequest": { "type": "object", "properties": { "capability_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "The read capability the grant covers.", "example": "org.settings.read" }, "valid_to": { "type": "string", "format": "date-time", "description": "When the grant ends, within a year.", "example": "2026-10-08T14:30:00Z" }, "agreement_reference": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The clause of the agreement.", "example": "Partner agreement, clause 7.2" } }, "required": ["capability_code", "valid_to", "agreement_reference"], "description": "A standing grant to record." }, "ShareLinkPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShareLink" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ShareLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the share link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "attachment_id": { "type": "string", "format": "uuid", "description": "Identifier of the file the link shares.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "attachment_version_id": { "type": ["string", "null"], "format": "uuid", "description": "Clean version the link opens, set from the file's current version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "classification": { "$ref": "#/components/schemas/Classification" }, "access_code_required": { "type": "boolean", "description": "True when the link asks for a 6-digit access code; always true for a Confidential file.", "example": false }, "recipient_email": { "type": ["string", "null"], "format": "email", "description": "Who the link is for, lowercased. Required for a Confidential file.", "example": "alex.rivera@northwindlive.example" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "What the link is for.", "example": "Stage plot for the venue" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the link stops opening: within 90 days, 30 for a Confidential file. Null only for a Public file.", "example": "2026-10-08T14:30:00Z" }, "failed_attempts": { "type": "integer", "minimum": 0, "description": "Wrong access codes entered; the link locks at 5.", "example": 0 }, "open_count": { "type": "integer", "minimum": 0, "description": "Successful opens.", "example": 2 }, "last_opened_at": { "type": ["string", "null"], "format": "date-time", "description": "When the link was last opened.", "example": "2026-10-08T14:30:00Z" }, "revoked_at": { "type": ["string", "null"], "format": "date-time", "description": "When the link was revoked; it never opens again.", "example": "2026-10-08T14:30:00Z" }, "revoked_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who revoked the link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "attachment_id", "attachment_version_id", "classification", "access_code_required", "recipient_email", "note", "expires_at", "failed_attempts", "open_count", "last_opened_at", "revoked_at", "revoked_by" ], "description": "A link that opens one clean version of a file without an account (Section 8.6). Public files may have a link without an expiry; Internal links need an expiry within 90 days; Confidential links need an expiry within 30 days, an access code and the recipient's email, which the watermark on every downloaded page carries; Restricted files never get a link. The token and the access code are returned once by `shareLinks.create` and stored only as hashes, so they never appear here. Anyone who can read the file reads its links." }, "ShareLinkToken": { "type": "object", "properties": { "share_link_id": { "type": "string", "format": "uuid", "description": "The new link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "token": { "type": "string", "pattern": "^xshr_[0-9a-f]{64}$", "description": "The link token. The link is `{Atlas origin}/share/{token}`. Shown once; only its hash is stored.", "example": "xshr_0000000000000000000000000000000000000000000000000000000000000000" }, "access_code": { "type": ["string", "null"], "pattern": "^[0-9]{6}$", "description": "The 6-digit access code, or null when the link asks for none. Shown once; send it apart from the link.", "example": "042424" }, "classification": { "$ref": "#/components/schemas/Classification" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the link stops opening.", "example": "2026-10-08T14:30:00Z" } }, "required": ["share_link_id", "token", "access_code", "classification", "expires_at"], "description": "A new share link with its token and access code, shown once." }, "ShareLinkCreate": { "type": "object", "properties": { "attachment_id": { "type": "string", "format": "uuid", "description": "Identifier of the file the link shares.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "access_code_required": { "type": "boolean", "description": "True when the link asks for a 6-digit access code; always true for a Confidential file.", "example": false }, "recipient_email": { "type": ["string", "null"], "format": "email", "description": "Who the link is for, lowercased. Required for a Confidential file.", "example": "alex.rivera@northwindlive.example" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "What the link is for.", "example": "Stage plot for the venue" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the link stops opening: within 90 days, 30 for a Confidential file. Null only for a Public file.", "example": "2026-10-08T14:30:00Z" } }, "required": ["attachment_id"], "description": "Fields accepted when creating a ShareLink." }, "PersonCalendarFeedPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonCalendarFeed" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PersonCalendarFeed": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the person calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person who owns the feed; always the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "token_hint": { "type": "string", "minLength": 1, "maxLength": 4, "description": "Last four characters of the token.", "example": "a1b2" }, "last_accessed_at": { "type": ["string", "null"], "format": "date-time", "description": "Last time a calendar fetched the feed.", "example": "2026-10-08T14:30:00Z" }, "rotated_at": { "type": ["string", "null"], "format": "date-time", "description": "When the token was last replaced.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "created_at", "updated_at", "person_id", "token_hint", "last_accessed_at", "rotated_at" ], "description": "A person's own iCalendar feed across every org they work with through an engagement (1410): their published shifts and the meetings, milestones and deadlines shared with them. Only a hash of the token is kept; the token is shown once by personCalendarFeeds.create and personCalendarFeeds.rotate, and deleting the feed revokes it for good." }, "ProjectInboxPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectInbox" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ProjectInbox": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the project inbox.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project the inbox belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "local_part": { "type": "string", "minLength": 1, "maxLength": 63, "description": "Part before the @ of the receiving domain: the project key and a random suffix.", "example": "nwl-0a1b2c3d4e" }, "disabled_at": { "type": ["string", "null"], "format": "date-time", "description": "When the address stopped accepting mail.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "local_part", "disabled_at" ], "description": "A project inbox address (0550, 1411): mail forwarded to `@` lands as inbound mail of the project for a coordinator to file. One live address per project; it is never edited, only replaced or disabled." }, "ProjectInboxCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project the inbox is for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["project_id"], "description": "The project to give an inbox." }, "InboundMessagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundMessage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "InboundMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the inbound message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "purpose": { "type": "string", "enum": ["Project Inbox", "Reply"], "description": "What the mail was sent to.", "example": "Project Inbox" }, "inbound_address_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project inbox the mail was sent to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "from_address": { "type": "string", "minLength": 1, "maxLength": 320, "description": "Sender address.", "example": "rigging@bayside-audio.test" }, "subject_line": { "type": ["string", "null"], "minLength": 1, "maxLength": 998, "description": "Subject.", "example": "Rigging plot v4" }, "body_text": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Plain-text body with quoted text stripped.", "example": "Updated plot attached." }, "dkim_verified": { "type": "boolean", "description": "True when the sender's DKIM signature verified.", "example": true }, "inbound_status": { "type": "string", "enum": ["Received", "Verified", "Filed", "Rejected"], "description": "Processing status.", "example": "Verified" }, "rejection_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Why the mail was rejected.", "example": "DKIM failed." }, "received_at": { "type": "string", "format": "date-time", "description": "When the mail arrived.", "example": "2026-10-08T14:30:00Z" }, "filed_document_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the document the mail was filed as.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "filed_record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record of the project the mail was filed to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "filed_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who filed the mail.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "filed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the mail was filed.", "example": "2026-10-08T14:30:00Z" }, "discarded_at": { "type": ["string", "null"], "format": "date-time", "description": "When the mail was discarded.", "example": "2026-10-08T14:30:00Z" }, "discarded_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who discarded the mail.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "discard_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Why the mail was discarded.", "example": "Spam." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "purpose", "inbound_address_id", "from_address", "subject_line", "body_text", "dkim_verified", "inbound_status", "rejection_reason", "received_at", "filed_document_id", "filed_record_id", "filed_by", "filed_at", "discarded_at", "discarded_by", "discard_reason" ], "description": "Mail received (0550, 1411): forwarded to a project inbox, or a reply to a notification email. People who file documents on the project read its inbox mail; a person reads their own replies. Project inbox mail is filed once, as a Document record of the project, or discarded with a reason." }, "InboundMessageFileRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Document title; the subject when omitted.", "example": "Rigging plot v4" }, "record_id": { "type": "string", "format": "uuid", "description": "Identifier of the record of the project to file the mail to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "How to file the mail." }, "InboundMessageDiscardRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the mail is discarded.", "example": "Spam." } }, "description": "Why the mail is discarded." }, "AutomationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the automation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name shown in Settings, Automations.", "example": "Pick up new tasks" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "What the automation is for.", "example": "Comments on every new task." }, "trigger_event_type": { "type": "string", "pattern": "^[a-z][a-z_]*\\.[a-z][a-z_]*$", "description": "Domain event type that starts a run, from the catalog webhooks use (webhookEventTypes.list).", "example": "record.created" }, "condition_match": { "type": "string", "enum": ["all", "any"], "description": "How the top-level conditions combine; set from the conditions document.", "example": "all" }, "owner_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the person the actions run as.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "enabled": { "type": "boolean", "description": "True while new events start runs.", "example": true }, "paused_at": { "type": ["string", "null"], "format": "date-time", "description": "When the engine turned the automation off because a run could not act as the owner; null otherwise. Turning it on again clears it.", "example": "2026-10-08T14:30:00Z" }, "pause_reason": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Why the engine paused it: owner_left_org, owner_lost_capability, owner_cannot_sign_in or owner_access_refused.", "example": "owner_left_org" }, "conditions": { "$ref": "#/components/schemas/AutomationConditions" }, "actions": { "$ref": "#/components/schemas/AutomationActions" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "description", "trigger_event_type", "condition_match", "owner_person_id", "enabled", "paused_at", "pause_reason", "conditions", "actions" ], "description": "An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422)." }, "AutomationConditions": { "anyOf": [ { "type": "object", "properties": { "all": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["eq", "ne", "lt", "lte", "gt", "gte", "contains"] }, "value": { "type": "string", "maxLength": 1000, "description": "Value compared, as text.", "example": "Task" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["in"] }, "value": { "type": "string", "maxLength": 1000, "pattern": "[^, ]", "description": "Comma-separated values, each trimmed.", "example": "Build, Task" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["is_null"] }, "value": { "type": ["string", "null"], "enum": ["true", "false", null], "description": "true (or absent) holds for a missing value, false for a present one." } }, "required": ["field", "operator"], "additionalProperties": false }, { "type": "object", "properties": { "all": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationCondition" }, "minItems": 1, "maxItems": 20 } }, "required": ["all"], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationCondition" }, "minItems": 1, "maxItems": 20 } }, "required": ["any"], "additionalProperties": false } ] }, "maxItems": 20 } }, "required": ["all"], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["eq", "ne", "lt", "lte", "gt", "gte", "contains"] }, "value": { "type": "string", "maxLength": 1000, "description": "Value compared, as text.", "example": "Task" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["in"] }, "value": { "type": "string", "maxLength": 1000, "pattern": "[^, ]", "description": "Comma-separated values, each trimmed.", "example": "Build, Task" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["is_null"] }, "value": { "type": ["string", "null"], "enum": ["true", "false", null], "description": "true (or absent) holds for a missing value, false for a present one." } }, "required": ["field", "operator"], "additionalProperties": false }, { "type": "object", "properties": { "all": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationCondition" }, "minItems": 1, "maxItems": 20 } }, "required": ["all"], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationCondition" }, "minItems": 1, "maxItems": 20 } }, "required": ["any"], "additionalProperties": false } ] }, "maxItems": 20 } }, "required": ["any"], "additionalProperties": false } ], "description": "An automation's conditions: {\"all\": [...]} or {\"any\": [...]} of conditions and one-level groups, at most 20 in all. An empty list always holds.", "example": { "all": [{ "field": "data.record_kind", "operator": "eq", "value": "Task" }] } }, "AutomationCondition": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["eq", "ne", "lt", "lte", "gt", "gte", "contains"] }, "value": { "type": "string", "maxLength": 1000, "description": "Value compared, as text.", "example": "Task" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["in"] }, "value": { "type": "string", "maxLength": 1000, "pattern": "[^, ]", "description": "Comma-separated values, each trimmed.", "example": "Build, Task" } }, "required": ["field", "operator", "value"], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z0-9_]+){0,7}$", "description": "Path into the event, such as data.record_kind.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["is_null"] }, "value": { "type": ["string", "null"], "enum": ["true", "false", null], "description": "true (or absent) holds for a missing value, false for a present one." } }, "required": ["field", "operator"], "additionalProperties": false } ], "description": "One condition: a path of the event, an API filter operator (ADR 0003) and a text value. Numbers compare numerically, strings by code point; contains folds ASCII case or finds an array element; every operator but is_null is false on a missing value." }, "AutomationActions": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationAction" }, "minItems": 1, "maxItems": 10, "description": "An automation's 1 to 10 actions, in the order they run.", "example": [{ "type": "add_comment", "body": "Picked up {{data.title}}." }] }, "AutomationAction": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["create_task"] }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Text; event paths in double braces are filled in, such as {{data.title}}.", "example": "Review {{data.title}}" }, "project_id": { "type": ["string", "null"], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Project the Task goes in, under its engagement root; null for the event's project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "phase_code": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Gated phase of the Task.", "example": "SCP" }, "xyz": { "type": "string", "enum": ["X", "Y", "Z"], "description": "Declared XYZ tag of the Task.", "example": "Y" }, "due_in_days": { "type": ["integer", "null"], "minimum": 0, "maximum": 365, "description": "Due at 17:00 on the org's calendar this many days after the run.", "example": 2 } }, "required": ["type", "title", "phase_code", "xyz"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["update_status"] }, "to_state": { "type": "string", "enum": [ "Proposed", "Ready", "Scheduled", "Active", "In Review", "Complete", "Canceled" ], "description": "Record state the subject record moves to." }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Text; event paths in double braces are filled in, such as {{data.title}}.", "example": "Picked up {{data.title}}." } }, "required": ["type", "to_state"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["update_status"] }, "to_state": { "type": "string", "enum": ["Blocked", "Deferred"] }, "note": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The blocker (Blocked) or the replan reason (Deferred).", "example": "Picked up {{data.title}}." } }, "required": ["type", "to_state", "note"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["assign"] }, "assignee_person_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Member who becomes the subject record's owner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["type", "assignee_person_id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["add_comment"] }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Text; event paths in double braces are filled in, such as {{data.title}}.", "example": "Picked up {{data.title}}." } }, "required": ["type", "body"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["notify"] }, "recipient_person_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Member who receives the notification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Text; event paths in double braces are filled in, such as {{data.title}}.", "example": "Review {{data.title}}" }, "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Text; event paths in double braces are filled in, such as {{data.title}}.", "example": "Picked up {{data.title}}." } }, "required": ["type", "recipient_person_id", "title"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["call_webhook"] }, "webhook_endpoint_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The org's webhook endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["type", "webhook_endpoint_id"], "additionalProperties": false } ], "description": "One action, run in order as the owner through a public API operation: create_task (records.create), update_status (records.transition), assign (records.update), add_comment (comments.postOnSubject), notify (automationRuns.notify) or call_webhook (automationRuns.deliverWebhook)." }, "AutomationCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name shown in Settings, Automations.", "example": "Pick up new tasks" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "What the automation is for.", "example": "Comments on every new task." }, "trigger_event_type": { "type": "string", "pattern": "^[a-z][a-z_]*\\.[a-z][a-z_]*$", "description": "Domain event type that starts a run, from the catalog webhooks use (webhookEventTypes.list).", "example": "record.created" }, "enabled": { "type": "boolean", "description": "True while new events start runs.", "example": true }, "conditions": { "$ref": "#/components/schemas/AutomationConditions" }, "actions": { "$ref": "#/components/schemas/AutomationActions" } }, "required": ["name", "trigger_event_type", "conditions", "actions"], "description": "Fields accepted when creating a Automation." }, "AutomationUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Name shown in Settings, Automations.", "example": "Pick up new tasks" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "What the automation is for.", "example": "Comments on every new task." }, "trigger_event_type": { "type": "string", "pattern": "^[a-z][a-z_]*\\.[a-z][a-z_]*$", "description": "Domain event type that starts a run, from the catalog webhooks use (webhookEventTypes.list).", "example": "record.created" }, "enabled": { "type": "boolean", "description": "True while new events start runs.", "example": true }, "conditions": { "$ref": "#/components/schemas/AutomationConditions" }, "actions": { "$ref": "#/components/schemas/AutomationActions" } }, "description": "Fields accepted when updating a Automation. Omitted fields are unchanged." }, "AutomationTestResult": { "type": "object", "properties": { "matched": { "type": "boolean", "description": "Whether the conditions hold for the sample event.", "example": true }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationConditionResult" }, "description": "Each condition in document order.", "example": [] } }, "required": ["matched", "conditions"], "description": "A dry run of an automation's conditions: nothing runs and nothing is written." }, "AutomationConditionResult": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Path into the event.", "example": "data.record_kind" }, "operator": { "type": "string", "enum": ["eq", "ne", "lt", "lte", "gt", "gte", "in", "is_null", "contains"], "description": "Filter operator.", "example": "eq" }, "value": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Value compared.", "example": "Task" }, "actual": { "description": "Value found in the event; null when missing.", "example": "Task" }, "matched": { "type": "boolean", "description": "Whether the condition held.", "example": true } }, "required": ["field", "operator", "value", "matched"], "description": "One condition of a dry run." }, "AutomationTestRequest": { "type": "object", "properties": { "event": { "type": "object", "additionalProperties": {}, "description": "A sample event body, as a webhook receives it; app.sample_automation_event gives the org's latest of the trigger type.", "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "type": "record.created", "occurred_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": { "table": "records", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "data": { "record_kind": "Task", "title": "Call the venue" } } } }, "required": ["event"], "description": "A sample event to test an automation against." }, "AutomationRunPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the automation run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "automation_id": { "type": "string", "format": "uuid", "description": "Identifier of the automation that ran.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "domain_event_id": { "type": "string", "format": "uuid", "description": "Identifier of the domain event that started the run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "parent_run_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the run whose action raised the event, when an automation caused it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "depth": { "type": "integer", "minimum": 0, "description": "Automation runs that led to this one; 0 for an event a person raised.", "example": 0 }, "run_status": { "type": "string", "enum": ["Queued", "Running", "Retrying", "Succeeded", "Failed", "Skipped"], "description": "Queued, Running, Retrying after a failure the job queue retries with backoff, Succeeded, Failed, or Skipped (loop_depth, rate_limited, or the automation was off).", "example": "Queued" }, "event_payload": { "type": "object", "additionalProperties": {}, "description": "The event as webhooks send it: the run's input.", "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "type": "record.created", "occurred_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": { "table": "records", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "data": { "record_kind": "Task", "title": "Call the venue" } } }, "owner_person_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person the run acted as.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "attempts": { "type": "integer", "minimum": 0, "description": "Times the worker started the run.", "example": 1 }, "error_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Rule code of the failure or skip.", "example": "owner_left_org" }, "error_message": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Why the run failed or was skipped.", "example": "The API answered 503." }, "started_at": { "type": ["string", "null"], "format": "date-time", "description": "When the worker first started the run.", "example": "2026-10-08T14:30:00Z" }, "finished_at": { "type": ["string", "null"], "format": "date-time", "description": "When the run reached Succeeded, Failed or Skipped.", "example": "2026-10-08T14:30:00Z" }, "duration_ms": { "type": ["integer", "null"], "minimum": 0, "description": "Milliseconds from the first start to the end.", "example": 840 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "automation_id", "domain_event_id", "parent_run_id", "depth", "run_status", "event_payload", "owner_person_id", "attempts", "error_code", "error_message", "started_at", "finished_at", "duration_ms" ], "description": "One run of an automation for one domain event (ADR 0047): an event never runs an automation twice. A run caused by another automation's action is one level deeper; past depth 3 it is Skipped (loop_depth), and past 1,000 runs in an hour in the org new runs are Skipped (rate_limited). A run fails closed when the owner left the org or lost org.automations.write, and the automation pauses with a notice." }, "AutomationNoticeResult": { "type": "object", "properties": { "notification_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the notification created.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["notification_id"], "description": "The notification an automation sent." }, "AutomationNoticeRequest": { "type": "object", "properties": { "recipient_person_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who receives the notification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Notification title.", "example": "New task: Call the venue" }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Message; the title is repeated when absent.", "example": "Call the venue needs a look." } }, "required": ["recipient_person_id", "title"], "description": "A notification an automation sends during a run." }, "AutomationWebhookResult": { "type": "object", "properties": { "webhook_delivery_id": { "type": "string", "format": "uuid", "description": "Identifier of the webhook delivery queued.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["webhook_delivery_id"], "description": "The delivery a run queued." }, "AutomationWebhookRequest": { "type": "object", "properties": { "webhook_endpoint_id": { "type": "string", "format": "uuid", "description": "Identifier of the the org's webhook endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["webhook_endpoint_id"], "description": "The endpoint a run's event is delivered to." }, "AutomationRunStepPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRunStep" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "AutomationRunStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the automation run step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who created the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the person who last updated the row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "automation_run_id": { "type": "string", "format": "uuid", "description": "Identifier of the run the step belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "automation_action_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the action the step ran.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Position of the action, 1 first.", "example": 1 }, "action_type": { "type": "string", "enum": [ "create_task", "update_status", "assign", "add_comment", "notify", "call_webhook" ], "description": "What the action does.", "example": "create_task" }, "operation_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Public API operation called.", "example": "records.create" }, "step_status": { "type": "string", "enum": ["Succeeded", "Failed", "Skipped"], "description": "Outcome of the action.", "example": "Succeeded" }, "request_body": { "type": ["object", "null"], "additionalProperties": {}, "description": "Body sent, with templates filled in from the event.", "example": { "title": "Review Call the venue" } }, "response_body": { "type": ["object", "null"], "additionalProperties": {}, "description": "Identifying fields of the answer, or the problem it reported.", "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "http_status": { "type": ["integer", "null"], "minimum": 100, "description": "HTTP status the API answered.", "example": 201 }, "error_code": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9_]*$", "description": "Rule code of the failure.", "example": "record_title_grammar" }, "error_message": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "Why the step failed.", "example": "A Task title starts with an imperative verb." }, "started_at": { "type": "string", "format": "date-time", "description": "When the step started.", "example": "2026-10-08T14:30:00Z" }, "finished_at": { "type": "string", "format": "date-time", "description": "When the step ended.", "example": "2026-10-08T14:30:00Z" }, "duration_ms": { "type": "integer", "minimum": 0, "description": "Milliseconds the step took.", "example": 120 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "automation_run_id", "automation_action_id", "position", "action_type", "operation_id", "step_status", "request_body", "response_body", "http_status", "error_code", "error_message", "started_at", "finished_at", "duration_ms" ], "description": "One action of an automation run: the public API operation called as the owner, what was sent and answered, and how long it took. A retried run rewrites the step of the action that failed." }, "WorkforceGroupPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkforceGroup" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkforceGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the workforce group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Group name, unique in the org.", "example": "Rigging Crew" }, "group_kind": { "type": "string", "enum": ["Department", "Project", "Crew", "Custom"], "description": "What the group gathers.", "example": "Department" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project a Project group gathers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the group is for.", "example": "Everyone flying points." }, "archived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the group was archived.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "group_kind", "project_id", "description", "archived_at" ], "description": "A group space by department, project, crew or custom audience, with its own chat and files." }, "WorkforceGroupCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Group name, unique in the org.", "example": "Rigging Crew" }, "group_kind": { "type": "string", "enum": ["Department", "Project", "Crew", "Custom"], "description": "What the group gathers.", "example": "Department" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project a Project group gathers.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the group is for.", "example": "Everyone flying points." } }, "required": ["name", "group_kind"], "description": "Fields accepted when creating a WorkforceGroup." }, "WorkforceGroupUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Group name, unique in the org.", "example": "Rigging Crew" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the group is for.", "example": "Everyone flying points." } }, "description": "Fields accepted when updating a WorkforceGroup. Omitted fields are unchanged." }, "WorkforceGroupMemberPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkforceGroupMember" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkforceGroupMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the workforce group member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": "string", "format": "uuid", "description": "Identifier of the group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member of the org in the group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_role": { "type": "string", "enum": ["Member", "Owner"], "description": "Owners add and remove members.", "example": "Member" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "group_id", "membership_id", "group_role" ], "description": "A member of a group space. Deleting removes the member, who also leaves the group conversation." }, "WorkforceGroupMemberCreate": { "type": "object", "properties": { "group_id": { "type": "string", "format": "uuid", "description": "Identifier of the group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member of the org in the group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_role": { "type": "string", "enum": ["Member", "Owner"], "description": "Owners add and remove members.", "example": "Member" } }, "required": ["group_id", "membership_id", "group_role"], "description": "Fields accepted when creating a WorkforceGroupMember." }, "ConversationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the conversation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "conversation_kind": { "type": "string", "enum": ["Direct", "Group"], "description": "Direct or Group.", "example": "Direct" }, "group_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the group whose conversation this is.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "direct_key": { "type": ["string", "null"], "minLength": 1, "maxLength": 80, "description": "The two membership ids of a Direct conversation, sorted and joined by a colon.", "example": "a:b" }, "last_message_at": { "type": ["string", "null"], "format": "date-time", "description": "When the latest message was sent.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "conversation_kind", "group_id", "direct_key", "last_message_at" ], "description": "A chat conversation: one-to-one between two members, or the conversation of a group." }, "DirectConversationRequest": { "type": "object", "properties": { "other_membership_id": { "type": "string", "format": "uuid", "description": "The other member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["other_membership_id"], "description": "Whom to message." }, "MarkConversationReadRequest": { "type": "object", "properties": { "muted": { "type": "boolean", "description": "Mute or unmute.", "example": false } }, "description": "Read position and mute switch." }, "ConversationReadReceiptPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationReadReceipt" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ConversationReadReceipt": { "type": "object", "properties": { "membership_id": { "type": "string", "format": "uuid", "description": "Member of the conversation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "full_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Their name.", "example": "Carol Nguyen" }, "last_read_at": { "type": ["string", "null"], "format": "date-time", "description": "When they last read it.", "example": "2026-10-08T14:30:00Z" } }, "required": ["membership_id", "full_name", "last_read_at"], "description": "When another member last read the conversation." }, "ChatMessagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "ChatMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the chat message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Identifier of the conversation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "author_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who sent it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message_kind": { "type": "string", "enum": ["Text", "Photo", "File", "Voice"], "description": "What the message carries.", "example": "Text" }, "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Message text; optional for a photo, file or voice note.", "example": "Points are up on stage left." }, "language": { "type": ["string", "null"], "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$", "description": "Language the author wrote in.", "example": "en-US" }, "edited_at": { "type": ["string", "null"], "format": "date-time", "description": "When the author last edited the text.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "conversation_id", "author_membership_id", "message_kind", "body", "language", "edited_at" ], "description": "A chat message. Photos, files and voice notes are attachments on the message." }, "ChatMessageCreate": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid", "description": "Identifier of the conversation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message_kind": { "type": "string", "enum": ["Text", "Photo", "File", "Voice"], "description": "What the message carries.", "example": "Text" }, "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Message text; optional for a photo, file or voice note.", "example": "Points are up on stage left." }, "language": { "type": ["string", "null"], "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$", "description": "Language the author wrote in.", "example": "en-US" } }, "required": ["conversation_id", "message_kind"], "description": "Fields accepted when creating a ChatMessage." }, "ChatMessageUpdate": { "type": "object", "properties": { "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000, "description": "Message text; optional for a photo, file or voice note.", "example": "Points are up on stage left." } }, "description": "Fields accepted when updating a ChatMessage. Omitted fields are unchanged." }, "DirectoryEntryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryEntry" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DirectoryEntry": { "type": "object", "properties": { "membership_id": { "type": "string", "format": "uuid", "description": "Membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "full_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Name.", "example": "Frank Adeyemi" }, "preferred_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Preferred name.", "example": "Frankie" }, "headline": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Profile headline.", "example": "Head rigger" }, "photo_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Profile photo storage path.", "example": "profiles/p1.jpg" }, "role_names": { "type": "array", "items": { "type": "string" }, "description": "Org roles held.", "example": ["Field"] }, "on_site_now": { "type": "boolean", "description": "Whether they are clocked in inside a geofence now.", "example": true }, "on_site_project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project they are on site for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "on_site_since": { "type": ["string", "null"], "format": "date-time", "description": "When they clocked in.", "example": "2026-10-08T14:30:00Z" }, "work_phone": { "type": ["string", "null"], "minLength": 1, "maxLength": 32, "description": "Work phone they shared for one-tap calls.", "example": "+1 305 555 0199" }, "recognition_count": { "type": ["integer", "null"], "minimum": 0, "description": "Times recognized, shown only with their consent.", "example": 3 } }, "required": [ "membership_id", "person_id", "full_name", "preferred_name", "headline", "photo_path", "role_names", "on_site_now", "on_site_project_id", "on_site_since", "work_phone", "recognition_count" ], "description": "A member in the org directory: profile basics they share with their network, roles, whether they are on site now (clocked in inside a geofence), the work phone they chose to share and their recognition count when they consented." }, "FeedPostPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedPost" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "FeedPost": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "post_kind": { "type": "string", "enum": ["Announcement", "Update", "Poll", "Recognition"], "description": "Post kind; Poll posts come from the createPoll action, Recognition posts from recognitions.", "example": "Announcement" }, "title": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Optional headline.", "example": "Wristband change" }, "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Post text.", "example": "Wristbands change color on Friday." }, "audience_kind": { "type": "string", "enum": ["Organization", "Project", "Team", "Department", "Role", "Group"], "description": "Who the row reaches. Department (a canon department, 1365) is for feed posts only.", "example": "Organization" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project audience, or the project the row belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the group audience, including department groups.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "department_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon department code of a Department audience (xpms.dim_department).", "example": "5000" }, "author_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who wrote the post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "pinned_at": { "type": ["string", "null"], "format": "date-time", "description": "When the post was pinned; null when not pinned.", "example": "2026-10-08T14:30:00Z" }, "requires_acknowledgment": { "type": "boolean", "description": "Whether every member of the audience must acknowledge it.", "example": false }, "reactions_enabled": { "type": "boolean", "description": "Whether members can react.", "example": true }, "comments_enabled": { "type": "boolean", "description": "Whether members can comment.", "example": true }, "publish_at": { "type": "string", "format": "date-time", "description": "When the post appears; a future time schedules it.", "example": "2026-10-08T14:30:00Z" }, "notified_at": { "type": ["string", "null"], "format": "date-time", "description": "When the audience was notified.", "example": "2026-10-08T14:30:00Z" }, "hidden_at": { "type": ["string", "null"], "format": "date-time", "description": "When the post was hidden.", "example": "2026-10-08T14:30:00Z" }, "hidden_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Why it was hidden.", "example": "Posted to the wrong project." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "post_kind", "title", "body", "audience_kind", "project_id", "team_id", "role_id", "group_id", "department_code", "author_membership_id", "pinned_at", "requires_acknowledgment", "reactions_enabled", "comments_enabled", "publish_at", "notified_at", "hidden_at", "hidden_reason" ], "description": "A feed post for an audience: an announcement, update, poll or recognition, with pinning, required acknowledgment, reaction and comment switches and a publish time." }, "FeedPostCreate": { "type": "object", "properties": { "post_kind": { "type": "string", "enum": ["Announcement", "Update", "Poll", "Recognition"], "description": "Post kind; Poll posts come from the createPoll action, Recognition posts from recognitions.", "example": "Announcement" }, "title": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Optional headline.", "example": "Wristband change" }, "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Post text.", "example": "Wristbands change color on Friday." }, "audience_kind": { "type": "string", "enum": ["Organization", "Project", "Team", "Department", "Role", "Group"], "description": "Who the row reaches. Department (a canon department, 1365) is for feed posts only.", "example": "Organization" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project audience, or the project the row belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the group audience, including department groups.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "department_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon department code of a Department audience (xpms.dim_department).", "example": "5000" }, "requires_acknowledgment": { "type": "boolean", "description": "Whether every member of the audience must acknowledge it.", "example": false }, "reactions_enabled": { "type": "boolean", "description": "Whether members can react.", "example": true }, "comments_enabled": { "type": "boolean", "description": "Whether members can comment.", "example": true }, "publish_at": { "type": "string", "format": "date-time", "description": "When the post appears; a future time schedules it.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "post_kind", "body", "audience_kind", "requires_acknowledgment", "reactions_enabled", "comments_enabled", "publish_at" ], "description": "Fields accepted when creating a FeedPost." }, "FeedPostUpdate": { "type": "object", "properties": { "reactions_enabled": { "type": "boolean", "description": "Whether members can react.", "example": true }, "comments_enabled": { "type": "boolean", "description": "Whether members can comment.", "example": true }, "publish_at": { "type": "string", "format": "date-time", "description": "When the post appears; a future time schedules it.", "example": "2026-10-08T14:30:00Z" } }, "description": "Fields accepted when updating a FeedPost. Omitted fields are unchanged." }, "PollPostRequest": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Post text.", "example": "Pick the crew meal." }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Optional headline.", "example": "Crew meal" }, "audience_kind": { "type": "string", "enum": ["Organization", "Project", "Team", "Department", "Role", "Group"], "description": "Who the row reaches. Department (a canon department, 1365) is for feed posts only.", "example": "Organization" }, "project_id": { "type": "string", "format": "uuid", "description": "Project audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": "string", "format": "uuid", "description": "Team audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": "string", "format": "uuid", "description": "Role audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": "string", "format": "uuid", "description": "Group audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "department_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon department code of a Department audience (xpms.dim_department).", "example": "5000" }, "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Poll question.", "example": "Which crew meal on Saturday?" }, "options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 2, "maxItems": 10, "description": "2 to 10 options.", "example": ["Tacos", "Pasta"] }, "allows_multiple": { "type": "boolean", "description": "Whether members may pick several.", "example": false }, "closes_at": { "type": "string", "format": "date-time", "description": "When voting closes.", "example": "2026-10-08T14:30:00Z" } }, "required": ["body", "question", "options"], "description": "A poll posted to the feed." }, "PinFeedPostRequest": { "type": "object", "properties": { "pinned": { "type": "boolean", "description": "Pinned.", "example": true } }, "required": ["pinned"], "description": "Pin switch." }, "HideFeedPostRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the post is hidden.", "example": "Posted to the wrong project." } }, "required": ["reason"], "description": "A reason for the change." }, "FeedReactionRequest": { "type": "object", "properties": { "reaction_code": { "type": "string", "enum": ["thumbs_up", "heart", "check", "eyes", "laugh", "celebrate"], "description": "Reaction.", "example": "heart" }, "on": { "type": "boolean", "description": "Add (default) or remove.", "example": true } }, "required": ["reaction_code"], "description": "A reaction." }, "FeedAcknowledgmentStatusPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedAcknowledgmentStatus" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "FeedAcknowledgmentStatus": { "type": "object", "properties": { "membership_id": { "type": "string", "format": "uuid", "description": "Member of the audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "person_id": { "type": "string", "format": "uuid", "description": "Person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "full_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Name.", "example": "Frank Adeyemi" }, "acknowledged_at": { "type": ["string", "null"], "format": "date-time", "description": "When they acknowledged.", "example": "2026-10-08T14:30:00Z" } }, "required": ["membership_id", "person_id", "full_name", "acknowledged_at"], "description": "One audience member and when they acknowledged the post." }, "PollPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Poll" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Poll": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the poll.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "feed_post_id": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Question.", "example": "Which crew meal on Saturday?" }, "allows_multiple": { "type": "boolean", "description": "Whether members may pick several options.", "example": false }, "closes_at": { "type": ["string", "null"], "format": "date-time", "description": "When voting closes.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "feed_post_id", "question", "allows_multiple", "closes_at" ], "description": "A quick poll in the feed, attached to a post of kind Poll." }, "PollVoteRequest": { "type": "object", "properties": { "option_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Options chosen.", "example": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"] } }, "required": ["option_ids"], "description": "Options chosen." }, "PollResultPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PollResult" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "PollResult": { "type": "object", "properties": { "poll_option_id": { "type": "string", "format": "uuid", "description": "Option.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "option_position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "label": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Option text.", "example": "Tacos" }, "votes": { "type": "integer", "minimum": 0, "description": "Votes for the option.", "example": 12 }, "voters": { "type": "integer", "minimum": 0, "description": "Members who voted in the poll.", "example": 20 } }, "required": ["poll_option_id", "option_position", "label", "votes", "voters"], "description": "Votes for one poll option." }, "SurveyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Survey" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Survey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Survey title.", "example": "Load-in pulse" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the survey asks about.", "example": "Tell us how the load-in felt." }, "audience_kind": { "type": "string", "enum": ["Organization", "Project", "Team", "Department", "Role", "Group"], "description": "Who the row reaches. Department (a canon department, 1365) is for feed posts only.", "example": "Organization" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project audience, or the project the row belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the group audience, including department groups.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "author_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who wrote the survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "is_anonymous": { "type": "boolean", "description": "Whether answers are stored with no respondent.", "example": true }, "min_responses": { "type": "integer", "minimum": 3, "description": "Responses needed before results show.", "example": 5 }, "survey_state": { "type": "string", "enum": ["Draft", "Open", "Closed"], "description": "Draft, Open or Closed.", "example": "Draft" }, "closes_at": { "type": ["string", "null"], "format": "date-time", "description": "When responses stop.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "title", "description", "audience_kind", "project_id", "team_id", "role_id", "group_id", "author_membership_id", "is_anonymous", "min_responses", "survey_state", "closes_at" ], "description": "A pulse survey for an audience, anonymous by default, with results only once the minimum number of responses is met." }, "SurveyDraftRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Survey title.", "example": "Load-in pulse" }, "description": { "type": "string", "maxLength": 2000, "description": "What the survey asks about.", "example": "How did it go?" }, "audience_kind": { "type": "string", "enum": ["Organization", "Project", "Team", "Department", "Role", "Group"], "description": "Who the row reaches. Department (a canon department, 1365) is for feed posts only.", "example": "Organization" }, "project_id": { "type": "string", "format": "uuid", "description": "Project audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": "string", "format": "uuid", "description": "Team audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": "string", "format": "uuid", "description": "Role audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": "string", "format": "uuid", "description": "Group audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "is_anonymous": { "type": "boolean", "description": "Anonymous by default.", "example": true }, "min_responses": { "type": "integer", "minimum": 3, "maximum": 1000, "description": "Responses before results show; 5 by default.", "example": 5 }, "closes_at": { "type": "string", "format": "date-time", "description": "When responses stop.", "example": "2026-10-08T14:30:00Z" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Question text.", "example": "How safe did it feel?" }, "kind": { "type": "string", "enum": ["Scale", "Choice", "Text"], "description": "Question kind.", "example": "Scale" }, "choices": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 2, "maxItems": 10, "description": "Choice options.", "example": ["A", "B"] }, "scale_max": { "anyOf": [ { "type": "number", "enum": [5] }, { "type": "number", "enum": [10] } ], "description": "Scale top.", "example": 5 }, "required": { "type": "boolean", "description": "Required; true by default.", "example": true } }, "required": ["prompt", "kind"] }, "minItems": 1, "maxItems": 50, "description": "1 to 50 questions in order.", "example": [{ "prompt": "How safe did it feel?", "kind": "Scale" }] } }, "required": ["title", "questions"], "description": "A survey drafted with its questions." }, "WorkforceLedgerEntry": { "type": "object", "properties": { "ledger_id": { "type": "string", "format": "uuid", "description": "The state transition ledger entry written.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["ledger_id"], "description": "The ledger entry a lifecycle move wrote." }, "SurveyTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Draft", "Open", "Closed"], "description": "The state the caller believes the row is in.", "example": "Draft" }, "to_state": { "type": "string", "enum": ["Draft", "Open", "Closed"], "description": "Target state.", "example": "Open" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the state changes.", "example": "Ready to go." } }, "required": ["expected_state", "to_state", "reason"], "description": "Request to move a lifecycle to another state." }, "SurveyResponseResult": { "type": "object", "properties": { "response_id": { "type": ["string", "null"], "format": "uuid", "description": "The response, or null for an anonymous survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["response_id"], "description": "The response written." }, "SurveyResponseRequest": { "type": "object", "properties": { "answers": { "type": "object", "additionalProperties": { "anyOf": [{ "type": "string" }, { "type": "number" }] }, "description": "Answers keyed by question id.", "example": { "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f": 4 } } }, "required": ["answers"], "description": "Survey answers." }, "SurveyResults": { "type": "object", "properties": { "survey_id": { "type": "string", "format": "uuid", "description": "Survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "responses": { "type": "integer", "minimum": 0, "description": "Responses so far.", "example": 12 }, "min_responses": { "type": "integer", "minimum": 0, "description": "Responses needed before results show.", "example": 5 }, "threshold_met": { "type": "boolean", "description": "Whether results show.", "example": true }, "audience": { "type": "integer", "minimum": 0, "description": "Members in the audience.", "example": 40 }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "format": "uuid", "description": "Question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 0, "description": "Order.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Question text.", "example": "How safe did it feel?" }, "kind": { "type": "string", "enum": ["Scale", "Choice", "Text"], "description": "Question kind.", "example": "Scale" }, "scale_max": { "type": ["integer", "null"], "description": "Scale top.", "example": 5 }, "answered": { "type": "integer", "minimum": 0, "description": "Answers given.", "example": 12 }, "average": { "type": ["number", "null"], "description": "Average of a Scale question.", "example": 4.2 }, "counts": { "type": ["object", "null"], "additionalProperties": { "type": "number" }, "description": "Answers per choice or scale point.", "example": { "4": 7, "5": 5 } }, "texts": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Text answers, sorted, not in arrival order.", "example": ["More water at the dock."] } }, "required": [ "question_id", "position", "prompt", "kind", "scale_max", "answered", "average", "counts", "texts" ] }, "description": "Per question results; empty below the threshold.", "example": [] } }, "required": [ "survey_id", "responses", "min_responses", "threshold_met", "audience", "questions" ], "description": "Results of a pulse survey." }, "SurveyQuestionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyQuestion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SurveyQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the survey question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "survey_id": { "type": "string", "format": "uuid", "description": "Identifier of the survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Question text.", "example": "How safe did the load-in feel?" }, "question_kind": { "type": "string", "enum": ["Scale", "Choice", "Text"], "description": "Question kind.", "example": "Scale" }, "choices": { "type": ["array", "null"], "items": { "type": "string" }, "description": "Options of a Choice question.", "example": ["Morning", "Night"] }, "scale_max": { "type": ["integer", "null"], "minimum": 5, "description": "Top of a Scale question: 5 or 10.", "example": 5 }, "is_required": { "type": "boolean", "description": "Whether a response must answer it.", "example": true } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "survey_id", "position", "prompt", "question_kind", "choices", "scale_max", "is_required" ], "description": "A question of a pulse survey, in order." }, "RecognitionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Recognition" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "Recognition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the recognition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "from_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who gave the recognition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "to_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member recognized.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the recognition is for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shift_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shift the recognition is for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What they did well.", "example": "Re-rigged the truss in record time." }, "feed_post_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the recognition post in the feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "from_membership_id", "to_membership_id", "project_id", "shift_id", "message", "feed_post_id" ], "description": "A shout-out from one member to another, tied to a project or shift and posted to the feed. No points currency." }, "RecognitionCreate": { "type": "object", "properties": { "to_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member recognized.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the recognition is for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "shift_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the shift the recognition is for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "message": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What they did well.", "example": "Re-rigged the truss in record time." } }, "required": ["to_membership_id", "message"], "description": "Fields accepted when creating a Recognition." }, "WorkforceEventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkforceEvent" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WorkforceEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the workforce event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "event_kind": { "type": "string", "enum": ["Briefing", "Crew Call", "Meeting"], "description": "Event kind.", "example": "Briefing" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Event title.", "example": "Load-in crew call" }, "agenda": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Agenda, in order.", "example": "1. Safety brief. 2. Assignments." }, "location": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Where to meet.", "example": "Dock door 3" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space within the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "audience_kind": { "type": "string", "enum": ["Organization", "Project", "Team", "Department", "Role", "Group"], "description": "Who the row reaches. Department (a canon department, 1365) is for feed posts only.", "example": "Organization" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project audience, or the project the row belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the group audience, including department groups.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "organizer_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who organizes the event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "End, at most seven days after the start.", "example": "2026-10-08T14:30:00Z" }, "rsvp_required": { "type": "boolean", "description": "Whether invitees are asked to RSVP.", "example": true }, "canceled_at": { "type": ["string", "null"], "format": "date-time", "description": "When the event was canceled.", "example": "2026-10-08T14:30:00Z" }, "cancel_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Why it was canceled.", "example": "Dock closed for repairs." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "event_kind", "title", "agenda", "location", "venue_id", "space_id", "audience_kind", "project_id", "team_id", "role_id", "group_id", "organizer_membership_id", "starts_at", "ends_at", "rsvp_required", "canceled_at", "cancel_reason" ], "description": "A briefing, crew call or meeting for an audience, with RSVP, location, agenda and check-in." }, "WorkforceEventCreate": { "type": "object", "properties": { "event_kind": { "type": "string", "enum": ["Briefing", "Crew Call", "Meeting"], "description": "Event kind.", "example": "Briefing" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Event title.", "example": "Load-in crew call" }, "agenda": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Agenda, in order.", "example": "1. Safety brief. 2. Assignments." }, "location": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Where to meet.", "example": "Dock door 3" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space within the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "audience_kind": { "type": "string", "enum": ["Organization", "Project", "Team", "Department", "Role", "Group"], "description": "Who the row reaches. Department (a canon department, 1365) is for feed posts only.", "example": "Organization" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project audience, or the project the row belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "team_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role audience.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "group_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the group audience, including department groups.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "End, at most seven days after the start.", "example": "2026-10-08T14:30:00Z" }, "rsvp_required": { "type": "boolean", "description": "Whether invitees are asked to RSVP.", "example": true } }, "required": [ "event_kind", "title", "audience_kind", "starts_at", "ends_at", "rsvp_required" ], "description": "Fields accepted when creating a WorkforceEvent." }, "WorkforceEventUpdate": { "type": "object", "properties": { "event_kind": { "type": "string", "enum": ["Briefing", "Crew Call", "Meeting"], "description": "Event kind.", "example": "Briefing" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Event title.", "example": "Load-in crew call" }, "agenda": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Agenda, in order.", "example": "1. Safety brief. 2. Assignments." }, "location": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Where to meet.", "example": "Dock door 3" }, "venue_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space within the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project audience, or the project the row belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "starts_at": { "type": "string", "format": "date-time", "description": "Start.", "example": "2026-10-08T14:30:00Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "End, at most seven days after the start.", "example": "2026-10-08T14:30:00Z" }, "rsvp_required": { "type": "boolean", "description": "Whether invitees are asked to RSVP.", "example": true } }, "description": "Fields accepted when updating a WorkforceEvent. Omitted fields are unchanged." }, "CancelWorkforceEventRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it is canceled.", "example": "Posted to the wrong project." } }, "required": ["reason"], "description": "A reason for the change." }, "EventRsvp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the event rsvp.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "workforce_event_id": { "type": "string", "format": "uuid", "description": "Identifier of the event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the invitee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "response": { "type": "string", "enum": ["Going", "Maybe", "Declined"], "description": "RSVP answer.", "example": "Going" }, "responded_at": { "type": "string", "format": "date-time", "description": "When they last answered.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "workforce_event_id", "membership_id", "response", "responded_at" ], "description": "An invitee's RSVP to an event." }, "RsvpRequest": { "type": "object", "properties": { "response": { "type": "string", "enum": ["Going", "Maybe", "Declined"], "description": "Answer.", "example": "Going" } }, "required": ["response"], "description": "An RSVP." }, "EventCheckIn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the event check in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "workforce_event_id": { "type": "string", "format": "uuid", "description": "Identifier of the event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the attendee.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "check_in_method": { "type": "string", "enum": ["Self", "Organizer", "Scan"], "description": "How they were checked in.", "example": "Self" }, "checked_in_at": { "type": "string", "format": "date-time", "description": "When they checked in.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "workforce_event_id", "membership_id", "check_in_method", "checked_in_at" ], "description": "Attendance of an event, one per attendee." }, "EventCheckInRequest": { "type": "object", "properties": { "membership_id": { "type": "string", "format": "uuid", "description": "Invitee to check in; the caller by default.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "method": { "type": "string", "enum": ["Self", "Organizer", "Scan"], "description": "How.", "example": "Self" } }, "description": "A check-in." }, "EventRsvpPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventRsvp" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "EventCheckInPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventCheckIn" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "FormTemplatePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormTemplate" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "FormTemplate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the form template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Form name, unique in the org.", "example": "Rigging pre-use check" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "When to fill it in.", "example": "Before every lift." }, "record_kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon record kind each project submission becomes.", "example": "Inspection" }, "record_subtype": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon record subtype.", "example": "Safety" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormField" }, "minItems": 1, "maxItems": 100, "description": "Field definitions in order.", "example": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }] }, "requires_signature": { "type": "boolean", "description": "Whether a submission must be signed.", "example": true }, "requires_location": { "type": "boolean", "description": "Whether a submission needs a GPS stamp.", "example": true }, "pass_score": { "type": ["number", "null"], "minimum": 0, "description": "Score needed to pass; null when not scored to pass.", "example": 2 }, "approver_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role whose holders approve submissions.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "template_state": { "type": "string", "enum": ["Draft", "Published", "Retired"], "description": "Draft, Published or Retired.", "example": "Draft" }, "current_version": { "type": "integer", "minimum": 0, "description": "Latest published version; 0 before the first publish.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "description", "record_kind", "record_subtype", "fields", "requires_signature", "requires_location", "approver_role_id", "template_state", "current_version" ], "description": "A no-code form with conditional fields, photos, GPS stamp, signature, scoring and approval routing. Project submissions become records of its canon kind and subtype." }, "FormField": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$", "description": "Field key.", "example": "hoist_ok" }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Label.", "example": "Hoist inspected" }, "kind": { "type": "string", "enum": [ "text", "long_text", "number", "yes_no", "choice", "multi_choice", "date", "photo" ], "description": "Field kind.", "example": "yes_no" }, "required": { "type": "boolean", "description": "Whether it must be answered when shown.", "example": true }, "choices": { "type": "array", "items": { "type": "string" }, "description": "Choices of a choice field.", "example": ["Light", "Heavy"] }, "points": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Points per answer, for scoring.", "example": { "true": 2 } }, "show_if": { "type": "object", "properties": { "key": { "type": "string", "description": "Earlier field key.", "example": "hoist_ok" }, "equals": { "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }], "description": "Answer that shows the field.", "example": false } }, "required": ["key", "equals"], "description": "Shows the field only when an earlier field has this answer." } }, "required": ["key", "label", "kind"], "description": "One field of a form." }, "FormTemplateCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Form name, unique in the org.", "example": "Rigging pre-use check" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "When to fill it in.", "example": "Before every lift." }, "record_kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon record kind each project submission becomes.", "example": "Inspection" }, "record_subtype": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon record subtype.", "example": "Safety" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormField" }, "minItems": 1, "maxItems": 100, "description": "Field definitions in order.", "example": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }] }, "requires_signature": { "type": "boolean", "description": "Whether a submission must be signed.", "example": true }, "requires_location": { "type": "boolean", "description": "Whether a submission needs a GPS stamp.", "example": true }, "pass_score": { "type": ["number", "null"], "minimum": 0, "description": "Score needed to pass; null when not scored to pass.", "example": 2 }, "approver_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role whose holders approve submissions.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["name", "record_kind", "fields", "requires_signature", "requires_location"], "description": "Fields accepted when creating a FormTemplate." }, "FormTemplateUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Form name, unique in the org.", "example": "Rigging pre-use check" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "When to fill it in.", "example": "Before every lift." }, "record_kind": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon record kind each project submission becomes.", "example": "Inspection" }, "record_subtype": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon record subtype.", "example": "Safety" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormField" }, "minItems": 1, "maxItems": 100, "description": "Field definitions in order.", "example": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }] }, "requires_signature": { "type": "boolean", "description": "Whether a submission must be signed.", "example": true }, "requires_location": { "type": "boolean", "description": "Whether a submission needs a GPS stamp.", "example": true }, "pass_score": { "type": ["number", "null"], "minimum": 0, "description": "Score needed to pass; null when not scored to pass.", "example": 2 }, "approver_role_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org role whose holders approve submissions.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "description": "Fields accepted when updating a FormTemplate. Omitted fields are unchanged." }, "RetireFormRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it is retired.", "example": "Posted to the wrong project." } }, "required": ["reason"], "description": "A reason for the change." }, "FormSubmissionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormSubmission" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "FormSubmission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the form submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "form_template_id": { "type": "string", "format": "uuid", "description": "Identifier of the form answered.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "form_template_version_id": { "type": "string", "format": "uuid", "description": "Identifier of the version answered.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the submission belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "record_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the record the project submission became.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "submitted_by_membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who submitted.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "answers": { "type": "object", "additionalProperties": {}, "description": "Answers keyed by field key.", "example": { "hoist_ok": true } }, "score": { "type": ["number", "null"], "description": "Points earned.", "example": 3 }, "max_score": { "type": ["number", "null"], "description": "Points available on the shown fields.", "example": 3 }, "passed": { "type": ["boolean", "null"], "description": "Whether the pass score was met.", "example": true }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 }, "accuracy_m": { "type": ["number", "null"], "minimum": 0, "description": "GPS accuracy in metres.", "example": 8 }, "signer_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Name of the signer.", "example": "Frank Adeyemi" }, "signature_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Signature image path in the field-media bucket.", "example": "org/forms/sig.png" }, "signed_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was signed.", "example": "2026-10-08T14:30:00Z" }, "submission_state": { "type": "string", "enum": ["Submitted", "Approved", "Rejected", "Recorded"], "description": "Submission state.", "example": "Submitted" }, "decided_by_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the approver who decided.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decision_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "Approver's note.", "example": "Good to lift." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "form_template_id", "form_template_version_id", "project_id", "record_id", "submitted_by_membership_id", "answers", "score", "max_score", "passed", "latitude", "longitude", "signer_name", "signature_path", "signed_at", "submission_state", "decided_by_membership_id", "decision_note" ], "description": "A submitted form: answers against one template version, score, GPS stamp, signature and approval." }, "FormSubmissionCreate": { "type": "object", "properties": { "form_template_id": { "type": "string", "format": "uuid", "description": "Identifier of the form answered.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the project the submission belongs to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "answers": { "type": "object", "additionalProperties": {}, "description": "Answers keyed by field key.", "example": { "hoist_ok": true } }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90, "description": "WGS 84 latitude.", "example": 25.7617 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180, "description": "WGS 84 longitude.", "example": -80.1918 }, "accuracy_m": { "type": ["number", "null"], "minimum": 0, "description": "GPS accuracy in metres.", "example": 8 }, "signer_name": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Name of the signer.", "example": "Frank Adeyemi" }, "signature_path": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Signature image path in the field-media bucket.", "example": "org/forms/sig.png" } }, "required": ["form_template_id", "answers"], "description": "Fields accepted when creating a FormSubmission." }, "FormDecisionRequest": { "type": "object", "properties": { "approve": { "type": "boolean", "description": "Approve or reject.", "example": true }, "note": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Note; required to reject.", "example": "Good to lift." } }, "required": ["approve"], "description": "A decision." }, "TrainingCoursePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingCourse" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TrainingCourse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the training course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Course title.", "example": "Rigging basics" }, "summary": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the course teaches.", "example": "Slings and shackles." }, "role_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon role trained for.", "example": "5000.01.01" }, "certification_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org certification a pass qualifies for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "gate_criterion_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon gate criterion the course helps satisfy.", "example": "G3.CREW_TRAINED" }, "validity_days": { "type": ["integer", "null"], "minimum": 1, "description": "Days a pass stays current.", "example": 365 }, "pass_percent": { "type": "integer", "minimum": 1, "description": "Quiz score needed to pass, in percent.", "example": 80 }, "estimated_minutes": { "type": ["integer", "null"], "minimum": 1, "description": "Expected time.", "example": 20 }, "course_state": { "type": "string", "enum": ["Draft", "Published", "Retired"], "description": "Course state.", "example": "Draft" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "title", "summary", "role_code", "certification_id", "gate_criterion_id", "validity_days", "pass_percent", "estimated_minutes", "course_state" ], "description": "A short training course of lessons and quizzes with completion records and expiry, linked to a role, a certification and a gate criterion." }, "TrainingCourseCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Course title.", "example": "Rigging basics" }, "summary": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the course teaches.", "example": "Slings and shackles." }, "role_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon role trained for.", "example": "5000.01.01" }, "certification_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org certification a pass qualifies for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "gate_criterion_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon gate criterion the course helps satisfy.", "example": "G3.CREW_TRAINED" }, "validity_days": { "type": ["integer", "null"], "minimum": 1, "description": "Days a pass stays current.", "example": 365 }, "pass_percent": { "type": "integer", "minimum": 1, "description": "Quiz score needed to pass, in percent.", "example": 80 }, "estimated_minutes": { "type": ["integer", "null"], "minimum": 1, "description": "Expected time.", "example": 20 } }, "required": ["title", "pass_percent"], "description": "Fields accepted when creating a TrainingCourse." }, "TrainingCourseUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Course title.", "example": "Rigging basics" }, "summary": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000, "description": "What the course teaches.", "example": "Slings and shackles." }, "role_code": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon role trained for.", "example": "5000.01.01" }, "certification_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the org certification a pass qualifies for.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "gate_criterion_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon gate criterion the course helps satisfy.", "example": "G3.CREW_TRAINED" }, "validity_days": { "type": ["integer", "null"], "minimum": 1, "description": "Days a pass stays current.", "example": 365 }, "pass_percent": { "type": "integer", "minimum": 1, "description": "Quiz score needed to pass, in percent.", "example": 80 }, "estimated_minutes": { "type": ["integer", "null"], "minimum": 1, "description": "Expected time.", "example": 20 } }, "description": "Fields accepted when updating a TrainingCourse. Omitted fields are unchanged." }, "RetireCourseRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it is retired.", "example": "Posted to the wrong project." } }, "required": ["reason"], "description": "A reason for the change." }, "AssignTrainingResult": { "type": "object", "properties": { "assigned": { "type": "integer", "minimum": 0, "description": "Newly assigned learners.", "example": 2 } }, "required": ["assigned"], "description": "How many were assigned." }, "AssignTrainingRequest": { "type": "object", "properties": { "membership_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Learners.", "example": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"] }, "due_on": { "type": "string", "format": "date", "description": "Due date.", "example": "2026-10-20" }, "reason": { "type": "string", "maxLength": 300, "description": "Why.", "example": "New riggers" } }, "required": ["membership_ids"], "description": "Learners to assign." }, "TrainingCompletion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the training completion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "training_course_id": { "type": "string", "format": "uuid", "description": "Identifier of the course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the learner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "score_percent": { "type": ["integer", "null"], "minimum": 0, "description": "Quiz score in percent.", "example": 90 }, "passed": { "type": "boolean", "description": "Whether the attempt passed.", "example": true }, "completed_at": { "type": "string", "format": "date-time", "description": "When the attempt finished.", "example": "2026-10-08T14:30:00Z" }, "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "When the pass stops being current.", "example": "2026-10-08T14:30:00Z" }, "certificate_number": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Completion certificate number.", "example": "TRN-0001" }, "certification_holder_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the certification record a verifier issued.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "training_course_id", "membership_id", "score_percent", "passed", "completed_at", "expires_at", "certificate_number", "certification_holder_id" ], "description": "A training attempt with its quiz score; a pass carries a certificate number and expiry." }, "CompleteTrainingRequest": { "type": "object", "properties": { "answers": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 6 }, "description": "Option numbers keyed by question id.", "example": { "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f": 1 } } }, "required": ["answers"], "description": "Quiz answers." }, "TrainingLessonPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingLesson" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TrainingLesson": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the training lesson.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "training_course_id": { "type": "string", "format": "uuid", "description": "Identifier of the course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Lesson title.", "example": "Slings" }, "lesson_kind": { "type": "string", "enum": ["Reading", "Video", "Quiz"], "description": "Lesson kind.", "example": "Reading" }, "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reading text or notes.", "example": "Inspect every sling before use." }, "video_url": { "type": ["string", "null"], "format": "uri", "description": "HTTPS address of the lesson video.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "training_course_id", "position", "title", "lesson_kind", "body", "video_url" ], "description": "A lesson of a training course: a reading, a video or a quiz. Changes only while the course is a draft." }, "TrainingLessonCreate": { "type": "object", "properties": { "training_course_id": { "type": "string", "format": "uuid", "description": "Identifier of the course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Lesson title.", "example": "Slings" }, "lesson_kind": { "type": "string", "enum": ["Reading", "Video", "Quiz"], "description": "Lesson kind.", "example": "Reading" }, "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reading text or notes.", "example": "Inspect every sling before use." }, "video_url": { "type": ["string", "null"], "format": "uri", "description": "HTTPS address of the lesson video.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "required": ["training_course_id", "position", "title", "lesson_kind"], "description": "Fields accepted when creating a TrainingLesson." }, "TrainingLessonUpdate": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Lesson title.", "example": "Slings" }, "body": { "type": ["string", "null"], "minLength": 1, "maxLength": 20000, "description": "Reading text or notes.", "example": "Inspect every sling before use." }, "video_url": { "type": ["string", "null"], "format": "uri", "description": "HTTPS address of the lesson video.", "example": "https://northwindlive.example/files/site-plan.pdf" } }, "description": "Fields accepted when updating a TrainingLesson. Omitted fields are unchanged." }, "TrainingQuizQuestionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingQuizQuestion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TrainingQuizQuestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the training quiz question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "training_lesson_id": { "type": "string", "format": "uuid", "description": "Identifier of the quiz lesson.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Question text.", "example": "What do you do before a lift?" }, "options": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 6, "description": "Answer options.", "example": ["Inspect the sling", "Skip it"] } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "training_lesson_id", "position", "prompt", "options" ], "description": "A question of a quiz lesson; its correct option is a training quiz key that learners never read." }, "TrainingQuizQuestionCreate": { "type": "object", "properties": { "training_lesson_id": { "type": "string", "format": "uuid", "description": "Identifier of the quiz lesson.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Question text.", "example": "What do you do before a lift?" }, "options": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 6, "description": "Answer options.", "example": ["Inspect the sling", "Skip it"] } }, "required": ["training_lesson_id", "position", "prompt", "options"], "description": "Fields accepted when creating a TrainingQuizQuestion." }, "TrainingQuizQuestionUpdate": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "description": "Order, from 1.", "example": 1 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Question text.", "example": "What do you do before a lift?" }, "options": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 6, "description": "Answer options.", "example": ["Inspect the sling", "Skip it"] } }, "description": "Fields accepted when updating a TrainingQuizQuestion. Omitted fields are unchanged." }, "TrainingQuizKeyPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingQuizKey" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TrainingQuizKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the training quiz key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "training_quiz_question_id": { "type": "string", "format": "uuid", "description": "Identifier of the quiz question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "correct_option": { "type": "integer", "minimum": 1, "description": "Correct option, from 1.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "training_quiz_question_id", "correct_option" ], "description": "The correct option of a quiz question. Only course editors read it." }, "TrainingQuizKeyCreate": { "type": "object", "properties": { "training_quiz_question_id": { "type": "string", "format": "uuid", "description": "Identifier of the quiz question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "correct_option": { "type": "integer", "minimum": 1, "description": "Correct option, from 1.", "example": 1 } }, "required": ["training_quiz_question_id", "correct_option"], "description": "Fields accepted when creating a TrainingQuizKey." }, "TrainingQuizKeyUpdate": { "type": "object", "properties": { "correct_option": { "type": "integer", "minimum": 1, "description": "Correct option, from 1.", "example": 1 } }, "description": "Fields accepted when updating a TrainingQuizKey. Omitted fields are unchanged." }, "TrainingAssignmentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingAssignment" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "TrainingAssignment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the training assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "training_course_id": { "type": "string", "format": "uuid", "description": "Identifier of the course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the learner.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "assigned_by_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the who assigned it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "due_on": { "type": ["string", "null"], "format": "date", "description": "Day it is due.", "example": "2026-10-08" }, "reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Why it was assigned.", "example": "New riggers" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "training_course_id", "membership_id", "assigned_by_membership_id", "due_on", "reason" ], "description": "A course assigned to a member with a due date. Deleting withdraws it." }, "TrainingCompletionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingCompletion" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "HandbookSectionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HandbookSection" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "HandbookSection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the handbook section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Section name.", "example": "Site rules" }, "position": { "type": "integer", "minimum": 1, "description": "Order.", "example": 1 } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "position" ], "description": "A chapter of the org handbook." }, "HandbookSectionCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Section name.", "example": "Site rules" }, "position": { "type": "integer", "minimum": 1, "description": "Order.", "example": 1 } }, "required": ["name", "position"], "description": "Fields accepted when creating a HandbookSection." }, "HandbookSectionUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Section name.", "example": "Site rules" }, "position": { "type": "integer", "minimum": 1, "description": "Order.", "example": 1 } }, "description": "Fields accepted when updating a HandbookSection. Omitted fields are unchanged." }, "HandbookArticlePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HandbookArticle" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "HandbookArticle": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the handbook article.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "handbook_section_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Title.", "example": "Hearing protection" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Working text; members read the published version.", "example": "Wear hearing protection near the stacks." }, "is_mandatory": { "type": "boolean", "description": "Whether every member must acknowledge the current version.", "example": true }, "article_state": { "type": "string", "enum": ["Draft", "Published", "Archived"], "description": "Article state.", "example": "Draft" }, "published_version": { "type": "integer", "minimum": 0, "description": "Latest published version.", "example": 1 }, "published_at": { "type": ["string", "null"], "format": "date-time", "description": "When the latest version was published.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "handbook_section_id", "title", "body", "is_mandatory", "article_state", "published_version", "published_at" ], "description": "A handbook or SOP article: versioned on publish, optionally a mandatory read acknowledged per version." }, "HandbookArticleCreate": { "type": "object", "properties": { "handbook_section_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Title.", "example": "Hearing protection" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Working text; members read the published version.", "example": "Wear hearing protection near the stacks." }, "is_mandatory": { "type": "boolean", "description": "Whether every member must acknowledge the current version.", "example": true } }, "required": ["title", "body", "is_mandatory"], "description": "Fields accepted when creating a HandbookArticle." }, "HandbookArticleUpdate": { "type": "object", "properties": { "handbook_section_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Title.", "example": "Hearing protection" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Working text; members read the published version.", "example": "Wear hearing protection near the stacks." }, "is_mandatory": { "type": "boolean", "description": "Whether every member must acknowledge the current version.", "example": true } }, "description": "Fields accepted when updating a HandbookArticle. Omitted fields are unchanged." }, "PublishArticleRequest": { "type": "object", "properties": { "change_summary": { "type": "string", "maxLength": 500, "description": "What changed.", "example": "Added the distance." } }, "description": "What changed." }, "KnowledgeSourcePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeSource" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "KnowledgeSource": { "type": "object", "properties": { "source_kind": { "type": "string", "enum": ["Handbook", "SOP", "Training"], "description": "Source kind.", "example": "Handbook" }, "source_id": { "type": "string", "format": "uuid", "description": "Source row.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Title.", "example": "Hearing protection" }, "version": { "type": ["integer", "null"], "minimum": 0, "description": "Version cited.", "example": 2 }, "excerpt": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Matching excerpt.", "example": "Wear hearing protection near the stacks." }, "route": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Atlas route of the source.", "example": "/northwind-live/knowledge/handbook?peek=x" }, "rank": { "type": "number", "description": "Relevance.", "example": 0.42 } }, "required": ["source_kind", "source_id", "title", "version", "excerpt", "route", "rank"], "description": "A published handbook article, SOP or training lesson matching a question, for the Assistant to cite (Section 4.7)." }, "HelpDeskTeamPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HelpDeskTeam" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "HelpDeskTeam": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the help desk team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Team name.", "example": "IT Desk" }, "team_kind": { "type": "string", "enum": ["Operations", "IT", "HR", "Facilities", "Other"], "description": "Team kind.", "example": "Operations" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "What the team helps with.", "example": "Devices and accounts." }, "first_response_hours": { "type": "integer", "minimum": 1, "description": "Business hours to first response.", "example": 8 }, "archived_at": { "type": ["string", "null"], "format": "date-time", "description": "When the team stopped taking requests.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "name", "team_kind", "description", "first_response_hours", "archived_at" ], "description": "An internal team that answers help desk requests, with its first response target." }, "HelpDeskTeamCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Team name.", "example": "IT Desk" }, "team_kind": { "type": "string", "enum": ["Operations", "IT", "HR", "Facilities", "Other"], "description": "Team kind.", "example": "Operations" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "What the team helps with.", "example": "Devices and accounts." }, "first_response_hours": { "type": "integer", "minimum": 1, "description": "Business hours to first response.", "example": 8 } }, "required": ["name", "team_kind", "first_response_hours"], "description": "Fields accepted when creating a HelpDeskTeam." }, "HelpDeskTeamUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Team name.", "example": "IT Desk" }, "team_kind": { "type": "string", "enum": ["Operations", "IT", "HR", "Facilities", "Other"], "description": "Team kind.", "example": "Operations" }, "description": { "type": ["string", "null"], "minLength": 1, "maxLength": 1000, "description": "What the team helps with.", "example": "Devices and accounts." }, "first_response_hours": { "type": "integer", "minimum": 1, "description": "Business hours to first response.", "example": 8 } }, "description": "Fields accepted when updating a HelpDeskTeam. Omitted fields are unchanged." }, "HelpDeskTeamMemberPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HelpDeskTeamMember" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "HelpDeskTeamMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the help desk team member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "help_desk_team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "help_desk_team_id", "membership_id" ], "description": "A member who answers a help desk team's requests. Deleting removes them." }, "HelpDeskTeamMemberCreate": { "type": "object", "properties": { "help_desk_team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["help_desk_team_id", "membership_id"], "description": "Fields accepted when creating a HelpDeskTeamMember." }, "HelpDeskRequestPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HelpDeskRequest" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "HelpDeskRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the help desk request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "ticket_number": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Display number.", "example": "SUP-0001" }, "help_desk_team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team the request is routed to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "category": { "type": "string", "enum": ["Question", "Problem", "Access", "Billing", "Account", "Feature Request"], "description": "What it is about.", "example": "Question" }, "severity": { "type": "string", "enum": ["Severity 3", "Severity 1", "Severity 2", "Severity 4"], "description": "Severity.", "example": "Severity 3" }, "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "One-line summary.", "example": "Tablet will not sign in" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What happened and what is needed.", "example": "The dock tablet shows a blank screen." }, "ticket_state": { "type": "string", "enum": ["Open", "Waiting", "Resolved", "Closed"], "description": "Request state.", "example": "Open" }, "membership_id": { "type": "string", "format": "uuid", "description": "Identifier of the member who asked.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "assignee_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the team member it is assigned to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "help_desk_response_due_at": { "type": ["string", "null"], "format": "date-time", "description": "When the first response is due.", "example": "2026-10-08T14:30:00Z" }, "first_responded_at": { "type": ["string", "null"], "format": "date-time", "description": "When the team first answered.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "ticket_number", "help_desk_team_id", "category", "severity", "subject", "body", "ticket_state", "membership_id", "assignee_membership_id", "help_desk_response_due_at", "first_responded_at" ], "description": "A help desk request: an Organization queue support ticket routed to an internal team, with assignment and response deadline." }, "HelpDeskRequestCreate": { "type": "object", "properties": { "help_desk_team_id": { "type": "string", "format": "uuid", "description": "Identifier of the team the request is routed to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "category": { "type": "string", "enum": ["Question", "Problem", "Access", "Billing", "Account", "Feature Request"], "description": "What it is about.", "example": "Question" }, "severity": { "type": "string", "enum": ["Severity 3", "Severity 1", "Severity 2", "Severity 4"], "description": "Severity.", "example": "Severity 3" }, "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "One-line summary.", "example": "Tablet will not sign in" }, "body": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What happened and what is needed.", "example": "The dock tablet shows a blank screen." } }, "required": ["help_desk_team_id", "category", "severity", "subject", "body"], "description": "Fields accepted when creating a HelpDeskRequest." }, "AssignHelpDeskRequest": { "type": "object", "properties": { "assignee_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Team member; null unassigns.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "help_desk_team_id": { "type": "string", "format": "uuid", "description": "Team to move the request to.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["assignee_membership_id"], "description": "Assignment." }, "HelpDeskAnswer": { "type": "object", "properties": { "message_id": { "type": "string", "format": "uuid", "description": "The message written.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": ["message_id"], "description": "The message an answer wrote." }, "AnswerHelpDeskRequest": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Answer.", "example": "Restarting the profile now." } }, "required": ["body"], "description": "An answer." }, "HelpDeskTransitionRequest": { "type": "object", "properties": { "expected_state": { "type": "string", "enum": ["Open", "Waiting", "Resolved", "Closed"], "description": "The state the caller believes the row is in.", "example": "Open" }, "to_state": { "type": "string", "enum": ["Open", "Waiting", "Resolved", "Closed"], "description": "Target state.", "example": "Resolved" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the state changes.", "example": "Ready to go." } }, "required": ["expected_state", "to_state", "reason"], "description": "Request to move a lifecycle to another state." }, "OccupancyCounterPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OccupancyCounter" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "OccupancyCounter": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the occupancy counter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "space_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the space counted.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Counter name.", "example": "Main Floor" }, "load_basis": { "type": "string", "enum": ["Occupant Load Factor", "Space Capacity", "Permit"], "description": "Where the permitted load comes from.", "example": "Occupant Load Factor" }, "metric_domain": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Bible metric domain of the load factor.", "example": "capacity" }, "metric_item": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Bible occupant load factor.", "example": "Assembly - standing space" }, "permitted_load": { "type": "integer", "minimum": 1, "description": "Permitted occupant load.", "example": 100 }, "current_count": { "type": "integer", "minimum": 0, "description": "People inside now.", "example": 82 }, "alert_level_percent": { "type": "integer", "minimum": 0, "description": "Highest alert level met: 0, 80, 90 or 100.", "example": 80 }, "closed_at": { "type": ["string", "null"], "format": "date-time", "description": "When counting stopped.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "space_id", "name", "load_basis", "metric_domain", "metric_item", "permitted_load", "current_count", "alert_level_percent", "closed_at" ], "description": "A live occupancy counter against the permitted occupant load, with alerts at 80, 90 and 100 percent." }, "OccupancyCounterCreateRequest": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Counter name.", "example": "Main Floor" }, "space_id": { "type": "string", "format": "uuid", "description": "Space counted.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "metric_item": { "type": "string", "description": "Bible occupant load factor sizing the space.", "example": "Assembly - standing space" }, "permitted_load": { "type": "integer", "minimum": 1, "description": "Permitted load from a permit.", "example": 400 } }, "required": ["project_id", "name"], "description": "An occupancy counter sized by a permit, a load factor or the space capacity." }, "OccupancyCountRequest": { "type": "object", "properties": { "delta": { "type": "integer", "minimum": -500, "maximum": 500, "description": "People in or out.", "example": 1 }, "door": { "type": "string", "maxLength": 80, "description": "Door.", "example": "Gate A" } }, "required": ["delta"], "description": "A door count." }, "WeatherThresholdPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WeatherThreshold" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WeatherThreshold": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the weather threshold.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hazard": { "type": "string", "enum": ["Wind", "Lightning", "Heat"], "description": "Hazard.", "example": "Wind" }, "alert_level": { "type": "string", "enum": ["Monitor", "Restrict", "Evacuate"], "description": "Level.", "example": "Monitor" }, "threshold_value": { "type": "number", "minimum": 0, "maximum": 200, "description": "Value that triggers the level.", "example": 30 }, "unit": { "type": "string", "enum": ["mph", "mi", "F"], "description": "Unit: mph for wind, mi for lightning distance, F for heat index.", "example": "mph" }, "comparison": { "type": "string", "enum": ["At or Above", "At or Below"], "description": "At or Above for wind and heat, At or Below for lightning.", "example": "At or Above" }, "source_note": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Where the value comes from.", "example": "Emergency plan 4.2" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "hazard", "alert_level", "threshold_value", "unit", "comparison", "source_note" ], "description": "A weather action threshold of a project: one value per hazard and level, with its emergency plan source." }, "WeatherThresholdCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hazard": { "type": "string", "enum": ["Wind", "Lightning", "Heat"], "description": "Hazard.", "example": "Wind" }, "alert_level": { "type": "string", "enum": ["Monitor", "Restrict", "Evacuate"], "description": "Level.", "example": "Monitor" }, "threshold_value": { "type": "number", "minimum": 0, "maximum": 200, "description": "Value that triggers the level.", "example": 30 }, "unit": { "type": "string", "enum": ["mph", "mi", "F"], "description": "Unit: mph for wind, mi for lightning distance, F for heat index.", "example": "mph" }, "comparison": { "type": "string", "enum": ["At or Above", "At or Below"], "description": "At or Above for wind and heat, At or Below for lightning.", "example": "At or Above" }, "source_note": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Where the value comes from.", "example": "Emergency plan 4.2" } }, "required": [ "project_id", "hazard", "alert_level", "threshold_value", "unit", "comparison", "source_note" ], "description": "Fields accepted when creating a WeatherThreshold." }, "WeatherThresholdUpdate": { "type": "object", "properties": { "threshold_value": { "type": "number", "minimum": 0, "maximum": 200, "description": "Value that triggers the level.", "example": 30 }, "source_note": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Where the value comes from.", "example": "Emergency plan 4.2" } }, "description": "Fields accepted when updating a WeatherThreshold. Omitted fields are unchanged." }, "WeatherAlertRolePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WeatherAlertRole" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WeatherAlertRole": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the weather alert role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "alert_level": { "type": "string", "enum": ["Monitor", "Restrict", "Evacuate"], "description": "Level.", "example": "Monitor" }, "role_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon role notified.", "example": "5000.01.01" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "alert_level", "role_code" ], "description": "A canon role the emergency plan names for a weather level; people assigned it on the project are alerted." }, "WeatherAlertRoleCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "alert_level": { "type": "string", "enum": ["Monitor", "Restrict", "Evacuate"], "description": "Level.", "example": "Monitor" }, "role_code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon role notified.", "example": "5000.01.01" } }, "required": ["project_id", "alert_level", "role_code"], "description": "Fields accepted when creating a WeatherAlertRole." }, "WeatherReadingPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WeatherReading" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WeatherReading": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the weather reading.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hazard": { "type": "string", "enum": ["Wind", "Lightning", "Heat"], "description": "Hazard.", "example": "Wind" }, "reading_value": { "type": "number", "minimum": 0, "maximum": 200, "description": "Reading.", "example": 33 }, "observed_at": { "type": "string", "format": "date-time", "description": "When it was observed.", "example": "2026-10-08T14:30:00Z" }, "recorded_by_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who recorded it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "hazard", "reading_value", "observed_at", "recorded_by_membership_id" ], "description": "A weather reading on site, in the hazard's unit." }, "WeatherReadingCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hazard": { "type": "string", "enum": ["Wind", "Lightning", "Heat"], "description": "Hazard.", "example": "Wind" }, "reading_value": { "type": "number", "minimum": 0, "maximum": 200, "description": "Reading.", "example": 33 }, "observed_at": { "type": "string", "format": "date-time", "description": "When it was observed.", "example": "2026-10-08T14:30:00Z" } }, "required": ["project_id", "hazard", "reading_value", "observed_at"], "description": "Fields accepted when creating a WeatherReading." }, "WeatherAlertPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WeatherAlert" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "WeatherAlert": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the weather alert.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "hazard": { "type": "string", "enum": ["Wind", "Lightning", "Heat"], "description": "Hazard.", "example": "Wind" }, "alert_level": { "type": "string", "enum": ["Monitor", "Restrict", "Evacuate"], "description": "Level met.", "example": "Monitor" }, "weather_reading_id": { "type": "string", "format": "uuid", "description": "Identifier of the reading that raised it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "issued_at": { "type": "string", "format": "date-time", "description": "When it was raised.", "example": "2026-10-08T14:30:00Z" }, "cleared_at": { "type": ["string", "null"], "format": "date-time", "description": "When it cleared.", "example": "2026-10-08T14:30:00Z" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "hazard", "alert_level", "weather_reading_id", "issued_at", "cleared_at" ], "description": "A weather alert raised by a reading at the highest level met, cleared when readings fall below every level." }, "GuestCheckInPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GuestCheckIn" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "GuestCheckIn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the guest check in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "guest_list_entry_id": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "plus_ones_admitted": { "type": "integer", "minimum": 0, "description": "Plus-ones admitted.", "example": 2 }, "credential_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the credential scanned.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "door": { "type": ["string", "null"], "minLength": 1, "maxLength": 80, "description": "Door or gate.", "example": "Gate A" }, "checked_in_by_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the door staff member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "guest_list_entry_id", "plus_ones_admitted", "credential_id", "door", "checked_in_by_membership_id" ], "description": "A door check-in of an approved guest with plus-ones admitted and the credential scanned." }, "GuestCheckInCreate": { "type": "object", "properties": { "guest_list_entry_id": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "plus_ones_admitted": { "type": "integer", "minimum": 0, "description": "Plus-ones admitted.", "example": 2 }, "door": { "type": ["string", "null"], "minLength": 1, "maxLength": 80, "description": "Door or gate.", "example": "Gate A" } }, "required": ["guest_list_entry_id", "plus_ones_admitted"], "description": "Fields accepted when creating a GuestCheckIn." }, "DoorGuestPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DoorGuest" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "DoorGuest": { "type": "object", "properties": { "guest_list_entry_id": { "type": "string", "format": "uuid", "description": "Guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "guest_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Guest name.", "example": "Jordan Ellis" }, "plus_ones": { "type": "integer", "minimum": 0, "description": "Plus-ones on the list.", "example": 2 }, "entry_state": { "type": "string", "enum": ["Approved", "Checked In"], "description": "Approved or Checked In.", "example": "Approved" }, "note": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Note for the door.", "example": "Side stage." }, "checked_in_at": { "type": ["string", "null"], "format": "date-time", "description": "When they were checked in.", "example": "2026-10-08T14:30:00Z" }, "plus_ones_admitted": { "type": ["integer", "null"], "description": "Plus-ones admitted.", "example": 2 }, "door": { "type": ["string", "null"], "minLength": 1, "maxLength": 300, "description": "Door.", "example": "Gate A" } }, "required": [ "guest_list_entry_id", "guest_name", "plus_ones", "entry_state", "note", "checked_in_at", "plus_ones_admitted", "door" ], "description": "A guest on the door list." }, "LostFoundItemPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LostFoundItem" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "LostFoundItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the lost found item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "item_number": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Display number.", "example": "LF-0001" }, "category": { "type": "string", "enum": [ "Wallet", "Bag", "Clothing", "Electronics", "Jewelry", "Keys", "Documents", "Other" ], "description": "Category.", "example": "Wallet" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Description a claimant is checked against.", "example": "Brown leather wallet." }, "found_at": { "type": "string", "format": "date-time", "description": "When it was found.", "example": "2026-10-08T14:30:00Z" }, "found_location": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Where it was found.", "example": "Bar 2" }, "storage_location": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Where it is held.", "example": "Security office locker 4" }, "logged_by_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who logged it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "item_state": { "type": "string", "enum": ["Logged", "Claimed", "Returned", "Disposed"], "description": "Item state.", "example": "Logged" } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "project_id", "item_number", "category", "description", "found_at", "found_location", "storage_location", "logged_by_membership_id", "item_state" ], "description": "An item in the lost and found log, with photos as attachments and its claim state." }, "LostFoundItemCreate": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "category": { "type": "string", "enum": [ "Wallet", "Bag", "Clothing", "Electronics", "Jewelry", "Keys", "Documents", "Other" ], "description": "Category.", "example": "Wallet" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Description a claimant is checked against.", "example": "Brown leather wallet." }, "found_at": { "type": "string", "format": "date-time", "description": "When it was found.", "example": "2026-10-08T14:30:00Z" }, "found_location": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Where it was found.", "example": "Bar 2" }, "storage_location": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Where it is held.", "example": "Security office locker 4" } }, "required": ["project_id", "category", "description", "found_at", "found_location"], "description": "Fields accepted when creating a LostFoundItem." }, "LostFoundItemUpdate": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "Wallet", "Bag", "Clothing", "Electronics", "Jewelry", "Keys", "Documents", "Other" ], "description": "Category.", "example": "Wallet" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Description a claimant is checked against.", "example": "Brown leather wallet." }, "storage_location": { "type": ["string", "null"], "minLength": 1, "maxLength": 200, "description": "Where it is held.", "example": "Security office locker 4" } }, "description": "Fields accepted when updating a LostFoundItem. Omitted fields are unchanged." }, "LostFoundClaim": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the lost found claim.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "uuid", "description": "Identifier of the owning organization, derived from the parent row and never accepted from the caller.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "created_at": { "type": "string", "format": "date-time", "description": "When the row was created.", "example": "2026-10-08T14:30:00Z" }, "created_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who created the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the row was last updated.", "example": "2026-10-08T14:30:00Z" }, "updated_by": { "type": ["string", "null"], "format": "uuid", "description": "Person who last updated the row; null for seed, platform or system writes.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "lost_found_item_id": { "type": "string", "format": "uuid", "description": "Identifier of the item claimed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "claimant_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Claimant.", "example": "Riley Park" }, "claimant_contact": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Claimant phone or email.", "example": "+1 305 555 0142" }, "proof_description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "How they proved it.", "example": "Named the card inside." }, "recorded_by_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who took the claim.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_by_membership_id": { "type": ["string", "null"], "format": "uuid", "description": "Identifier of the member who settled it.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "decided_at": { "type": ["string", "null"], "format": "date-time", "description": "When it was settled.", "example": "2026-10-08T14:30:00Z" }, "returned": { "type": ["boolean", "null"], "description": "True when returned, false when rejected.", "example": true }, "decision_note": { "type": ["string", "null"], "minLength": 1, "maxLength": 500, "description": "Why rejected, or a return note.", "example": "ID matched." } }, "required": [ "id", "org_id", "created_at", "created_by", "updated_at", "updated_by", "lost_found_item_id", "claimant_name", "claimant_contact", "proof_description", "recorded_by_membership_id", "decided_by_membership_id", "decided_at", "returned", "decision_note" ], "description": "A claim on a lost item: the claimant, their contact (Confidential), their proof and how it was settled." }, "LostItemClaimRequest": { "type": "object", "properties": { "claimant_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Claimant.", "example": "Riley Park" }, "claimant_contact": { "type": "string", "minLength": 3, "maxLength": 200, "description": "Phone or email.", "example": "+1 305 555 0142" }, "proof_description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Proof.", "example": "Named the card inside." } }, "required": ["claimant_name", "claimant_contact", "proof_description"], "description": "A claim." }, "DisposeLostItemRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it is disposed of.", "example": "Posted to the wrong project." } }, "required": ["reason"], "description": "A reason for the change." }, "LostFoundClaimPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LostFoundClaim" }, "description": "Items on this page, in the documented default order." }, "next_cursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; null on the last page.", "example": "eyJpZCI6IjAxOTJmMWUyIn0" } }, "required": ["data", "next_cursor"], "description": "One page of results with a cursor to the next page." }, "SettleClaimRequest": { "type": "object", "properties": { "returned": { "type": "boolean", "description": "Returned (true) or rejected (false).", "example": true }, "note": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Note; required to reject.", "example": "ID matched." } }, "required": ["returned"], "description": "Settlement." } }, "parameters": { "Limit": { "schema": { "$ref": "#/components/schemas/Limit" }, "required": false, "name": "limit", "in": "query", "description": "Page size. Default 50, maximum 200." }, "Cursor": { "schema": { "$ref": "#/components/schemas/Cursor" }, "required": false, "name": "cursor", "in": "query", "description": "Opaque cursor from `next_cursor` of the previous page." }, "Fields": { "schema": { "$ref": "#/components/schemas/Fields" }, "required": false, "name": "fields", "in": "query", "description": "Sparse fieldset: a comma-separated list of top-level fields to return. `id` is always returned." }, "Sort": { "schema": { "$ref": "#/components/schemas/Sort" }, "required": false, "name": "sort", "in": "query", "description": "Sort keys, comma-separated; a leading `-` sorts descending. Without `sort`, the documented default order applies (coded lists sort in numeric code order)." }, "Filter": { "schema": { "$ref": "#/components/schemas/Filter" }, "required": false, "name": "filter", "in": "query", "style": "deepObject", "explode": true, "description": "Filter grammar `filter[field][op]=value`. Operators: eq, ne, lt, lte, gt, gte, in (comma-separated values), is_null (true or false) and contains. Conditions combine with AND." }, "IdempotencyKey": { "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "required": true, "name": "Idempotency-Key", "in": "header", "description": "Required on every POST. Keys are stored per tenant for 24 hours; a replay with the same key returns the original response." }, "IfMatch": { "schema": { "$ref": "#/components/schemas/IfMatch" }, "required": true, "name": "If-Match", "in": "header", "description": "The `ETag` of the version being updated. A stale tag returns 412; a missing tag returns 428." } } }, "paths": { "/home/summary": { "get": { "operationId": "home.get", "tags": ["Home"], "x-xos-table": "app.v_home_summary", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Get the home summary", "description": "Returns the caller's org dashboard: open and blocked work, projects at risk at their next gate, unread alerts and committed spend as a NULL-aware total. A rule that refuses the request returns 422 with `refusal` and `reason`.", "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "open_work_count": 7, "blocked_work_count": 1, "projects_at_risk_count": 2, "alert_count": 3, "committed_spend": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 } }, "schema": { "$ref": "#/components/schemas/HomeSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects": { "get": { "operationId": "projects.list", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project rows", "description": "A production project. Jurisdiction is resolved at gate 1. Returns a cursor page of project rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "projects.create", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.project.create", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a project", "description": "A production project. Jurisdiction is resolved at gate 1. Creates a project. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "project_key": "NWL-24", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ProjectCreate" } } } }, "responses": { "201": { "description": "The created project.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{id}": { "get": { "operationId": "projects.get", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project", "description": "A production project. Jurisdiction is resolved at gate 1. Returns one project with its `ETag`. A project the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "projects.update", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.project.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a project", "description": "A production project. Jurisdiction is resolved at gate 1. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "project_key": "NWL-24", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/ProjectUpdate" } } } }, "responses": { "200": { "description": "The updated project.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{id}/transitions": { "post": { "operationId": "projects.transition", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.project.archive", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Transition the project state", "description": "Moves the project lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Proposed", "to_state": "Active", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/ProjectTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{id}/gate-transitions": { "post": { "operationId": "projects.passGate", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.gate.transition", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Pass the current gate", "description": "Moves the project to the next phase. Compare-and-set on `expected_phase_code`; refused with 422 when any blocking criterion lacks evidence. The database enforces the criteria. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_phase_code": "SCP", "to_phase_code": "SCP" }, "schema": { "$ref": "#/components/schemas/GateTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{id}/gate-readiness": { "get": { "operationId": "projects.gateReadiness", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get gate readiness", "description": "Lists each criterion of the next gate with whether evidence satisfies it. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate": 3, "criterion_id": "G1.BUDGET_ENVELOPE", "blocking": true, "satisfied": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/GateReadinessPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{id}/archive": { "post": { "operationId": "projects.archive", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.project.archive", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Archive a project", "description": "Sets `archived_at`, so the project leaves the default lists and stays readable and restorable. Archiving an archived project leaves it unchanged. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects/{id}/unarchive": { "post": { "operationId": "projects.unarchive", "tags": ["Projects"], "x-xos-table": "app.projects", "x-xos-capability": "projects.project.archive", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Restore an archived project", "description": "Clears `archived_at`, so the project returns to the default lists. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWL-24", "name": "Harborfront Summer Series", "description": "Six weekend shows on the harbor lawn.", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "region_code": "NA-SE-MIA", "tier_code": "04", "current_phase_code": "SCP", "project_state": "Active", "currency": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_zone": "America/New_York", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "client_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "production_state": "Proposed", "archived_at": "2026-10-08T14:30:00Z", "anchor_on": "2026-10-08", "budget_envelope_minor": 25000000 }, "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/scope-nodes": { "get": { "operationId": "scopeNodes.list", "tags": ["Projects"], "x-xos-table": "app.scope_nodes", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List scope node rows", "description": "A node of the project scope tree: engagement root, standing venue or show. Returns a cursor page of scope node rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of scope node rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_code": "E01", "name": "Opening Weekend", "node_kind": "Show", "path": "root.e01" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ScopeNodePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "scopeNodes.create", "tags": ["Projects"], "x-xos-table": "app.scope_nodes", "x-xos-capability": "projects.scope.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a scope node", "description": "A node of the project scope tree: engagement root, standing venue or show. Creates a scope node. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_code": "E01", "name": "Opening Weekend", "node_kind": "Show" }, "schema": { "$ref": "#/components/schemas/ScopeNodeCreate" } } } }, "responses": { "201": { "description": "The created scope node.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_code": "E01", "name": "Opening Weekend", "node_kind": "Show", "path": "root.e01" }, "schema": { "$ref": "#/components/schemas/ScopeNode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/scope-nodes/{id}": { "get": { "operationId": "scopeNodes.get", "tags": ["Projects"], "x-xos-table": "app.scope_nodes", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a scope node", "description": "A node of the project scope tree: engagement root, standing venue or show. Returns one scope node with its `ETag`. A scope node the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the scope node.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The scope node.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_code": "E01", "name": "Opening Weekend", "node_kind": "Show", "path": "root.e01" }, "schema": { "$ref": "#/components/schemas/ScopeNode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "scopeNodes.update", "tags": ["Projects"], "x-xos-table": "app.scope_nodes", "x-xos-capability": "projects.scope.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a scope node", "description": "A node of the project scope tree: engagement root, standing venue or show. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the scope node.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "scope_code": "E01", "name": "Opening Weekend", "node_kind": "Show" }, "schema": { "$ref": "#/components/schemas/ScopeNodeUpdate" } } } }, "responses": { "200": { "description": "The updated scope node.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_code": "E01", "name": "Opening Weekend", "node_kind": "Show", "path": "root.e01" }, "schema": { "$ref": "#/components/schemas/ScopeNode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "scopeNodes.delete", "tags": ["Projects"], "x-xos-table": "app.scope_nodes", "x-xos-capability": "projects.scope.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a scope node", "description": "A node of the project scope tree: engagement root, standing venue or show. Soft-deletes the scope node: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the scope node.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the scope node.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The scope node moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-phase-transitions": { "get": { "operationId": "projectPhaseTransitions.list", "tags": ["Projects"], "x-xos-table": "app.project_phase_transitions", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["transitioned_at"], "numeric": false }, "summary": "List project phase transition rows", "description": "An append-only gate transition of a project. Returns a cursor page of project phase transition rows the caller may see. The default order is `transitioned_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project phase transition rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_phase_code": "SCP", "to_phase_code": "SCP", "transitioned_at": "2026-10-08T14:30:00Z", "transitioned_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectPhaseTransitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-phase-transitions/{id}": { "get": { "operationId": "projectPhaseTransitions.get", "tags": ["Projects"], "x-xos-table": "app.project_phase_transitions", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project phase transition", "description": "An append-only gate transition of a project. Returns one project phase transition with its `ETag`. A project phase transition the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project phase transition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project phase transition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project phase transition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_phase_code": "SCP", "to_phase_code": "SCP", "transitioned_at": "2026-10-08T14:30:00Z", "transitioned_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ProjectPhaseTransition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/gate-evidence": { "get": { "operationId": "gateEvidence.list", "tags": ["Projects"], "x-xos-table": "app.gate_evidence", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List gate evidence rows", "description": "Evidence for a gate criterion. One evidence spine serves every criterion. Returns a cursor page of gate evidence rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of gate evidence rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "criterion_id": "G1.BUDGET_ENVELOPE", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attested_at": "2026-10-08T14:30:00Z", "assertion_rank": 4, "evidence_uri": "urn:xpms:documents:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Signed by the venue manager." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/GateEvidencePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "gateEvidence.create", "tags": ["Projects"], "x-xos-table": "app.gate_evidence", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a gate evidence", "description": "Evidence for a gate criterion. One evidence spine serves every criterion. Creates a gate evidence. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "criterion_id": "G1.BUDGET_ENVELOPE", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assertion_rank": 4, "evidence_uri": "urn:xpms:documents:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Signed by the venue manager." }, "schema": { "$ref": "#/components/schemas/GateEvidenceCreate" } } } }, "responses": { "201": { "description": "The created gate evidence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "criterion_id": "G1.BUDGET_ENVELOPE", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attested_at": "2026-10-08T14:30:00Z", "assertion_rank": 4, "evidence_uri": "urn:xpms:documents:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Signed by the venue manager." }, "schema": { "$ref": "#/components/schemas/GateEvidence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/gate-evidence/{id}": { "get": { "operationId": "gateEvidence.get", "tags": ["Projects"], "x-xos-table": "app.gate_evidence", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a gate evidence", "description": "Evidence for a gate criterion. One evidence spine serves every criterion. Returns one gate evidence with its `ETag`. A gate evidence the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the gate evidence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the gate evidence.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The gate evidence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "criterion_id": "G1.BUDGET_ENVELOPE", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attested_at": "2026-10-08T14:30:00Z", "assertion_rank": 4, "evidence_uri": "urn:xpms:documents:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Signed by the venue manager." }, "schema": { "$ref": "#/components/schemas/GateEvidence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "gateEvidence.delete", "tags": ["Projects"], "x-xos-table": "app.gate_evidence", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a gate evidence", "description": "Evidence for a gate criterion. One evidence spine serves every criterion. Soft-deletes the gate evidence: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the gate evidence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the gate evidence.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The gate evidence moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/activity-events": { "get": { "operationId": "activityEvents.list", "tags": ["Activity"], "x-xos-table": "app.activity_events", "x-xos-capability": "activity.feed.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["activity"] }], "x-xos-order": { "by": ["occurred_at"], "numeric": false, "descending": true }, "summary": "List activity event rows", "description": "A user-facing activity feed entry, separate from the compliance audit ledger. Returns a cursor page of activity event rows the caller may see. The default order is `occurred_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of activity event rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "verb": "record.state_changed", "subject_urn": "urn:xpms:record:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "occurred_at": "2026-10-08T14:30:00Z", "summary": "Moved to Scheduled", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ActivityEventPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/activity-events/{id}": { "get": { "operationId": "activityEvents.get", "tags": ["Activity"], "x-xos-table": "app.activity_events", "x-xos-capability": "activity.feed.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["activity"] }], "summary": "Get an activity event", "description": "A user-facing activity feed entry, separate from the compliance audit ledger. Returns one activity event with its `ETag`. A activity event the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the activity event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the activity event.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The activity event.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "verb": "record.state_changed", "subject_urn": "urn:xpms:record:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "occurred_at": "2026-10-08T14:30:00Z", "summary": "Moved to Scheduled", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ActivityEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/schedule-baselines": { "get": { "operationId": "scheduleBaselines.list", "tags": ["Schedule"], "x-xos-table": "app.schedule_baselines", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List schedule baseline rows", "description": "A frozen schedule baseline for variance tracking. Returns a cursor page of schedule baseline rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of schedule baseline rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Baseline", "captured_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ScheduleBaselinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "scheduleBaselines.create", "tags": ["Schedule"], "x-xos-table": "app.schedule_baselines", "x-xos-capability": "schedule.baseline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Create a schedule baseline", "description": "A frozen schedule baseline for variance tracking. Creates a schedule baseline. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Baseline" }, "schema": { "$ref": "#/components/schemas/ScheduleBaselineCreate" } } } }, "responses": { "201": { "description": "The created schedule baseline.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Baseline", "captured_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ScheduleBaseline" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/schedule-baselines/{id}": { "get": { "operationId": "scheduleBaselines.get", "tags": ["Schedule"], "x-xos-table": "app.schedule_baselines", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Get a schedule baseline", "description": "A frozen schedule baseline for variance tracking. Returns one schedule baseline with its `ETag`. A schedule baseline the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the schedule baseline.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the schedule baseline.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The schedule baseline.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Baseline", "captured_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ScheduleBaseline" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "scheduleBaselines.delete", "tags": ["Schedule"], "x-xos-table": "app.schedule_baselines", "x-xos-capability": "schedule.baseline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Delete a schedule baseline", "description": "A frozen schedule baseline for variance tracking. Soft-deletes the schedule baseline: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the schedule baseline.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the schedule baseline.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The schedule baseline moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/schedule-actuals": { "get": { "operationId": "scheduleActuals.list", "tags": ["Schedule"], "x-xos-table": "app.schedule_actuals", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List schedule actual rows", "description": "Actual start and finish of a record. Returns a cursor page of schedule actual rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of schedule actual rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actual_start_at": "2026-10-08T14:30:00Z", "actual_end_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ScheduleActualPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "scheduleActuals.create", "tags": ["Schedule"], "x-xos-table": "app.schedule_actuals", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Create a schedule actual", "description": "Actual start and finish of a record. Creates a schedule actual. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actual_start_at": "2026-10-08T14:30:00Z", "actual_end_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ScheduleActualCreate" } } } }, "responses": { "201": { "description": "The created schedule actual.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actual_start_at": "2026-10-08T14:30:00Z", "actual_end_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ScheduleActual" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/schedule-actuals/{id}": { "get": { "operationId": "scheduleActuals.get", "tags": ["Schedule"], "x-xos-table": "app.schedule_actuals", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Get a schedule actual", "description": "Actual start and finish of a record. Returns one schedule actual with its `ETag`. A schedule actual the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the schedule actual.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the schedule actual.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The schedule actual.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actual_start_at": "2026-10-08T14:30:00Z", "actual_end_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ScheduleActual" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "scheduleActuals.update", "tags": ["Schedule"], "x-xos-table": "app.schedule_actuals", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Update a schedule actual", "description": "Actual start and finish of a record. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the schedule actual.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the schedule actual.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "actual_start_at": "2026-10-08T14:30:00Z", "actual_end_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ScheduleActualUpdate" } } } }, "responses": { "200": { "description": "The updated schedule actual.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actual_start_at": "2026-10-08T14:30:00Z", "actual_end_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ScheduleActual" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calendars": { "get": { "operationId": "calendars.list", "tags": ["Schedule"], "x-xos-table": "app.calendars", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List calendar rows", "description": "A working calendar with its time zone. Returns a cursor page of calendar rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of calendar rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Venue Working Days", "time_zone": "America/New_York", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CalendarPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "calendars.create", "tags": ["Schedule"], "x-xos-table": "app.calendars", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Create a calendar", "description": "A working calendar with its time zone. Creates a calendar. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Venue Working Days", "time_zone": "America/New_York", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CalendarCreate" } } } }, "responses": { "201": { "description": "The created calendar.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Venue Working Days", "time_zone": "America/New_York", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Calendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calendars/{id}": { "get": { "operationId": "calendars.get", "tags": ["Schedule"], "x-xos-table": "app.calendars", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Get a calendar", "description": "A working calendar with its time zone. Returns one calendar with its `ETag`. A calendar the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the calendar.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The calendar.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Venue Working Days", "time_zone": "America/New_York", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Calendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "calendars.update", "tags": ["Schedule"], "x-xos-table": "app.calendars", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Update a calendar", "description": "A working calendar with its time zone. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the calendar.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Venue Working Days", "time_zone": "America/New_York", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CalendarUpdate" } } } }, "responses": { "200": { "description": "The updated calendar.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Venue Working Days", "time_zone": "America/New_York", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Calendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "calendars.delete", "tags": ["Schedule"], "x-xos-table": "app.calendars", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Delete a calendar", "description": "A working calendar with its time zone. Soft-deletes the calendar: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the calendar.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The calendar moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-dependencies": { "get": { "operationId": "recordDependencies.list", "tags": ["Schedule"], "x-xos-table": "app.record_dependencies", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List record dependency rows", "description": "A dependency between two records. Returns a cursor page of record dependency rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record dependency rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "predecessor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "successor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dependency_type": "finish_to_start", "lag_minutes": 0 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordDependencyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "recordDependencies.create", "tags": ["Schedule"], "x-xos-table": "app.record_dependencies", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Create a record dependency", "description": "A dependency between two records. Creates a record dependency. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "predecessor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "successor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dependency_type": "finish_to_start", "lag_minutes": 0 }, "schema": { "$ref": "#/components/schemas/RecordDependencyCreate" } } } }, "responses": { "201": { "description": "The created record dependency.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "predecessor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "successor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dependency_type": "finish_to_start", "lag_minutes": 0 }, "schema": { "$ref": "#/components/schemas/RecordDependency" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-dependencies/{id}": { "get": { "operationId": "recordDependencies.get", "tags": ["Schedule"], "x-xos-table": "app.record_dependencies", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Get a record dependency", "description": "A dependency between two records. Returns one record dependency with its `ETag`. A record dependency the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record dependency.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record dependency.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The record dependency.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "predecessor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "successor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dependency_type": "finish_to_start", "lag_minutes": 0 }, "schema": { "$ref": "#/components/schemas/RecordDependency" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "recordDependencies.delete", "tags": ["Schedule"], "x-xos-table": "app.record_dependencies", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Delete a record dependency", "description": "A dependency between two records. Soft-deletes the record dependency: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record dependency.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record dependency.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The record dependency moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-recurrences": { "get": { "operationId": "recordRecurrences.list", "tags": ["Schedule"], "x-xos-table": "app.record_recurrences", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List record recurrence rows", "description": "A recurrence rule that generates records. Returns a cursor page of record recurrence rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record recurrence rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rrule": "FREQ=WEEKLY;BYDAY=SA", "time_zone": "America/New_York", "until": "2026-10-08" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordRecurrencePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "recordRecurrences.create", "tags": ["Schedule"], "x-xos-table": "app.record_recurrences", "x-xos-capability": "work.recurring.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a record recurrence", "description": "A recurrence rule that generates records. Creates a record recurrence. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rrule": "FREQ=WEEKLY;BYDAY=SA", "time_zone": "America/New_York", "until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RecordRecurrenceCreate" } } } }, "responses": { "201": { "description": "The created record recurrence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rrule": "FREQ=WEEKLY;BYDAY=SA", "time_zone": "America/New_York", "until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RecordRecurrence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-recurrences/{id}": { "get": { "operationId": "recordRecurrences.get", "tags": ["Schedule"], "x-xos-table": "app.record_recurrences", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a record recurrence", "description": "A recurrence rule that generates records. Returns one record recurrence with its `ETag`. A record recurrence the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record recurrence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record recurrence.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The record recurrence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rrule": "FREQ=WEEKLY;BYDAY=SA", "time_zone": "America/New_York", "until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RecordRecurrence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "recordRecurrences.update", "tags": ["Schedule"], "x-xos-table": "app.record_recurrences", "x-xos-capability": "work.recurring.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a record recurrence", "description": "A recurrence rule that generates records. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record recurrence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record recurrence.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "rrule": "FREQ=WEEKLY;BYDAY=SA", "time_zone": "America/New_York", "until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RecordRecurrenceUpdate" } } } }, "responses": { "200": { "description": "The updated record recurrence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rrule": "FREQ=WEEKLY;BYDAY=SA", "time_zone": "America/New_York", "until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RecordRecurrence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "recordRecurrences.delete", "tags": ["Schedule"], "x-xos-table": "app.record_recurrences", "x-xos-capability": "work.recurring.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a record recurrence", "description": "A recurrence rule that generates records. Soft-deletes the record recurrence: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record recurrence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record recurrence.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The record recurrence moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/records": { "get": { "operationId": "records.list", "tags": ["Work"], "x-xos-table": "app.records", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List record rows", "description": "A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`. Returns a cursor page of record rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_key": "NWL-24-118", "record_kind": "Task", "record_subtype": "Design", "record_class": "Work", "record_state": "Scheduled", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_code": "4000-T01", "assignee_membership_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "progress_pct": 40, "permit_identifier": "BP-2027-0611", "inspection_result_enum_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "records.create", "tags": ["Work"], "x-xos-table": "app.records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a record", "description": "A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`. Creates a record. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_kind": "Task", "record_subtype": "Design", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"] }, "schema": { "$ref": "#/components/schemas/RecordCreate" } } } }, "responses": { "201": { "description": "The created record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_key": "NWL-24-118", "record_kind": "Task", "record_subtype": "Design", "record_class": "Work", "record_state": "Scheduled", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_code": "4000-T01", "assignee_membership_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "progress_pct": 40, "permit_identifier": "BP-2027-0611", "inspection_result_enum_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/records/{id}": { "get": { "operationId": "records.get", "tags": ["Work"], "x-xos-table": "app.records", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a record", "description": "A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`. Returns one record with its `ETag`. A record the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_key": "NWL-24-118", "record_kind": "Task", "record_subtype": "Design", "record_class": "Work", "record_state": "Scheduled", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_code": "4000-T01", "assignee_membership_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "progress_pct": 40, "permit_identifier": "BP-2027-0611", "inspection_result_enum_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "records.update", "tags": ["Work"], "x-xos-table": "app.records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a record", "description": "A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_subtype": "Design", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_code": "4000-T01" }, "schema": { "$ref": "#/components/schemas/RecordUpdate" } } } }, "responses": { "200": { "description": "The updated record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_key": "NWL-24-118", "record_kind": "Task", "record_subtype": "Design", "record_class": "Work", "record_state": "Scheduled", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_code": "4000-T01", "assignee_membership_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "progress_pct": 40, "permit_identifier": "BP-2027-0611", "inspection_result_enum_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "records.delete", "tags": ["Work"], "x-xos-table": "app.records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a record", "description": "A record of any of the 26 kinds. Kind-specific attributes live in 1:1 extension tables keyed by `record_id`. Soft-deletes the record: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The record moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/records/{id}/transitions": { "post": { "operationId": "records.transition", "tags": ["Work"], "x-xos-table": "app.records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Transition a record state", "description": "Moves a record between the nine record states. Blocked requires `blocker_text`; Deferred requires `replan_reason`; from Scheduled onward every change is a logged replan. Canceled records are retained. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Scheduled", "to_state": "Scheduled", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend." }, "schema": { "$ref": "#/components/schemas/RecordTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_key": "NWL-24-118", "record_kind": "Task", "record_subtype": "Design", "record_class": "Work", "record_state": "Scheduled", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_code": "4000-T01", "assignee_membership_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "progress_pct": 40, "permit_identifier": "BP-2027-0611", "inspection_result_enum_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/records/{id}/duplicate": { "post": { "operationId": "records.duplicate", "tags": ["Work"], "x-xos-table": "app.records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Duplicate a record", "description": "Creates a copy of the record, with or without its children. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_key": "NWL-24-118", "record_kind": "Task", "record_subtype": "Design", "record_class": "Work", "record_state": "Scheduled", "title": "Install Main Stage Truss", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "phase_code": "SCP", "urid": "4000.01", "xyz": "X", "owner_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accountable_party_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "blocker_text": "Waiting on the rigging plot.", "replan_reason": "Moved to the second weekend.", "external_visibility": ["Vendor"], "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "wbs_code": "1.2.1", "description": "Rig the downstage truss.", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_code": "4000-T01", "assignee_membership_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "progress_pct": 40, "permit_identifier": "BP-2027-0611", "inspection_result_enum_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-state-transitions": { "get": { "operationId": "recordStateTransitions.list", "tags": ["Work"], "x-xos-table": "app.record_state_transitions", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["transitioned_at"], "numeric": false }, "summary": "List record state transition rows", "description": "An append-only record state transition. Returns a cursor page of record state transition rows the caller may see. The default order is `transitioned_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record state transition rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_state": "Scheduled", "to_state": "Scheduled", "transitioned_at": "2026-10-08T14:30:00Z", "transitioned_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordStateTransitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-state-transitions/{id}": { "get": { "operationId": "recordStateTransitions.get", "tags": ["Work"], "x-xos-table": "app.record_state_transitions", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a record state transition", "description": "An append-only record state transition. Returns one record state transition with its `ETag`. A record state transition the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record state transition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record state transition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The record state transition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_state": "Scheduled", "to_state": "Scheduled", "transitioned_at": "2026-10-08T14:30:00Z", "transitioned_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordStateTransition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-replans": { "get": { "operationId": "recordReplans.list", "tags": ["Work"], "x-xos-table": "app.record_replans", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["replanned_at"], "numeric": false }, "summary": "List record replan rows", "description": "An append-only replan entry, logged from Scheduled onward for every date or state change. Returns a cursor page of record replan rows the caller may see. The default order is `replanned_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record replan rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Moved to the second weekend.", "replanned_at": "2026-10-08T14:30:00Z", "from_state": "Scheduled", "to_state": "Deferred", "old_starts_at": "2026-10-08T14:30:00Z", "new_starts_at": "2026-10-08T14:30:00Z", "old_ends_at": "2026-10-08T14:30:00Z", "new_ends_at": "2026-10-08T14:30:00Z", "old_due_at": "2026-10-08T14:30:00Z", "new_due_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordReplanPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-replans/{id}": { "get": { "operationId": "recordReplans.get", "tags": ["Work"], "x-xos-table": "app.record_replans", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a record replan", "description": "An append-only replan entry, logged from Scheduled onward for every date or state change. Returns one record replan with its `ETag`. A record replan the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record replan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record replan.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The record replan.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Moved to the second weekend.", "replanned_at": "2026-10-08T14:30:00Z", "from_state": "Scheduled", "to_state": "Deferred", "old_starts_at": "2026-10-08T14:30:00Z", "new_starts_at": "2026-10-08T14:30:00Z", "old_ends_at": "2026-10-08T14:30:00Z", "new_ends_at": "2026-10-08T14:30:00Z", "old_due_at": "2026-10-08T14:30:00Z", "new_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RecordReplan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-checklist-items": { "get": { "operationId": "recordChecklistItems.list", "tags": ["Work"], "x-xos-table": "app.record_checklist_items", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["position"], "numeric": false }, "summary": "List record checklist item rows", "description": "One checklist item of a record. Items are rows, never array positions. Returns a cursor page of record checklist item rows the caller may see. The default order is `position` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record checklist item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "label": "Check the safety cables", "done": false, "done_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "done_at": "2026-10-08T14:30:00Z", "evidence_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordChecklistItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "recordChecklistItems.create", "tags": ["Work"], "x-xos-table": "app.record_checklist_items", "x-xos-capability": "work.punch_list.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a record checklist item", "description": "One checklist item of a record. Items are rows, never array positions. Creates a record checklist item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "label": "Check the safety cables", "done": false, "evidence_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordChecklistItemCreate" } } } }, "responses": { "201": { "description": "The created record checklist item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "label": "Check the safety cables", "done": false, "done_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "done_at": "2026-10-08T14:30:00Z", "evidence_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordChecklistItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-checklist-items/{id}": { "get": { "operationId": "recordChecklistItems.get", "tags": ["Work"], "x-xos-table": "app.record_checklist_items", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a record checklist item", "description": "One checklist item of a record. Items are rows, never array positions. Returns one record checklist item with its `ETag`. A record checklist item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record checklist item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record checklist item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The record checklist item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "label": "Check the safety cables", "done": false, "done_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "done_at": "2026-10-08T14:30:00Z", "evidence_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordChecklistItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "recordChecklistItems.update", "tags": ["Work"], "x-xos-table": "app.record_checklist_items", "x-xos-capability": "work.punch_list.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a record checklist item", "description": "One checklist item of a record. Items are rows, never array positions. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record checklist item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record checklist item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "position": 1, "label": "Check the safety cables", "done": false, "evidence_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordChecklistItemUpdate" } } } }, "responses": { "200": { "description": "The updated record checklist item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "label": "Check the safety cables", "done": false, "done_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "done_at": "2026-10-08T14:30:00Z", "evidence_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordChecklistItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "recordChecklistItems.delete", "tags": ["Work"], "x-xos-table": "app.record_checklist_items", "x-xos-capability": "work.punch_list.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a record checklist item", "description": "One checklist item of a record. Items are rows, never array positions. Soft-deletes the record checklist item: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record checklist item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record checklist item.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The record checklist item moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-watchers": { "get": { "operationId": "recordWatchers.list", "tags": ["Work"], "x-xos-table": "app.record_watchers", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List record watcher rows", "description": "A person watching a record for notifications. Returns a cursor page of record watcher rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record watcher rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordWatcherPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "recordWatchers.create", "tags": ["Work"], "x-xos-table": "app.record_watchers", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Create a record watcher", "description": "A person watching a record for notifications. Creates a record watcher. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordWatcherCreate" } } } }, "responses": { "201": { "description": "The created record watcher.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RecordWatcher" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-watchers/{id}": { "delete": { "operationId": "recordWatchers.delete", "tags": ["Work"], "x-xos-table": "app.record_watchers", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Delete a record watcher", "description": "A person watching a record for notifications. Soft-deletes the record watcher: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record watcher.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record watcher.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The record watcher moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-orders": { "get": { "operationId": "workOrders.list", "tags": ["Work"], "x-xos-table": "app.work_orders", "x-xos-capability": "work.work_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List work order rows", "description": "A work order issued against a record, open to bids. Returns a cursor page of work order rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of work order rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "urid": "4000.01", "work_order_state": "Proposed", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD", "work_order_number": 12, "location_text": "Main stage, stage left wing.", "scope_of_work": "Supply and hang 24 moving lights.", "scheduled_starts_at": "2026-10-08T14:30:00Z", "estimated_hours": 16 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkOrderPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workOrders.create", "tags": ["Work"], "x-xos-table": "app.work_orders", "x-xos-capability": "work.work_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a work order", "description": "A work order issued against a record, open to bids. Creates a work order. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "urid": "4000.01", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD" }, "schema": { "$ref": "#/components/schemas/WorkOrderCreate" } } } }, "responses": { "201": { "description": "The created work order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "urid": "4000.01", "work_order_state": "Proposed", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD", "work_order_number": 12, "location_text": "Main stage, stage left wing.", "scope_of_work": "Supply and hang 24 moving lights.", "scheduled_starts_at": "2026-10-08T14:30:00Z", "estimated_hours": 16 }, "schema": { "$ref": "#/components/schemas/WorkOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-orders/{id}": { "get": { "operationId": "workOrders.get", "tags": ["Work"], "x-xos-table": "app.work_orders", "x-xos-capability": "work.work_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a work order", "description": "A work order issued against a record, open to bids. Returns one work order with its `ETag`. A work order the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The work order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "urid": "4000.01", "work_order_state": "Proposed", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD", "work_order_number": 12, "location_text": "Main stage, stage left wing.", "scope_of_work": "Supply and hang 24 moving lights.", "scheduled_starts_at": "2026-10-08T14:30:00Z", "estimated_hours": 16 }, "schema": { "$ref": "#/components/schemas/WorkOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "workOrders.update", "tags": ["Work"], "x-xos-table": "app.work_orders", "x-xos-capability": "work.work_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a work order", "description": "A work order issued against a record, open to bids. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "urid": "4000.01", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD", "location_text": "Main stage, stage left wing.", "scope_of_work": "Supply and hang 24 moving lights.", "scheduled_starts_at": "2026-10-08T14:30:00Z", "estimated_hours": 16 }, "schema": { "$ref": "#/components/schemas/WorkOrderUpdate" } } } }, "responses": { "200": { "description": "The updated work order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "urid": "4000.01", "work_order_state": "Proposed", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD", "work_order_number": 12, "location_text": "Main stage, stage left wing.", "scope_of_work": "Supply and hang 24 moving lights.", "scheduled_starts_at": "2026-10-08T14:30:00Z", "estimated_hours": 16 }, "schema": { "$ref": "#/components/schemas/WorkOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "workOrders.delete", "tags": ["Work"], "x-xos-table": "app.work_orders", "x-xos-capability": "work.work_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a work order", "description": "A work order issued against a record, open to bids. Soft-deletes the work order: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work order.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The work order moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-orders/{id}/transitions": { "post": { "operationId": "workOrders.transition", "tags": ["Work"], "x-xos-table": "app.work_orders", "x-xos-capability": "work.work_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Transition the work order state", "description": "Moves the work order lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Proposed", "to_state": "Active", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/WorkOrderTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "urid": "4000.01", "work_order_state": "Proposed", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD", "work_order_number": 12, "location_text": "Main stage, stage left wing.", "scope_of_work": "Supply and hang 24 moving lights.", "scheduled_starts_at": "2026-10-08T14:30:00Z", "estimated_hours": 16 }, "schema": { "$ref": "#/components/schemas/WorkOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-order-bids": { "get": { "operationId": "workOrderBids.list", "tags": ["Work"], "x-xos-table": "app.work_order_bids", "x-xos-capability": "work.work_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List work order bid rows", "description": "A bid on a work order. Returns a cursor page of work order bid rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of work order bid rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "work_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bidder_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 790000, "currency": "USD", "bid_state": "Quoted", "notes": "Includes delivery and install." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkOrderBidPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workOrderBids.create", "tags": ["Work"], "x-xos-table": "app.work_order_bids", "x-xos-capability": "work.work_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a work order bid", "description": "A bid on a work order. Creates a work order bid. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "work_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bidder_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 790000, "currency": "USD", "notes": "Includes delivery and install." }, "schema": { "$ref": "#/components/schemas/WorkOrderBidCreate" } } } }, "responses": { "201": { "description": "The created work order bid.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "work_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bidder_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 790000, "currency": "USD", "bid_state": "Quoted", "notes": "Includes delivery and install." }, "schema": { "$ref": "#/components/schemas/WorkOrderBid" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-order-bids/{id}": { "get": { "operationId": "workOrderBids.get", "tags": ["Work"], "x-xos-table": "app.work_order_bids", "x-xos-capability": "work.work_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a work order bid", "description": "A bid on a work order. Returns one work order bid with its `ETag`. A work order bid the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work order bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work order bid.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The work order bid.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "work_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bidder_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 790000, "currency": "USD", "bid_state": "Quoted", "notes": "Includes delivery and install." }, "schema": { "$ref": "#/components/schemas/WorkOrderBid" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "workOrderBids.update", "tags": ["Work"], "x-xos-table": "app.work_order_bids", "x-xos-capability": "work.work_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a work order bid", "description": "A bid on a work order. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work order bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work order bid.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "amount_minor": 790000, "currency": "USD", "notes": "Includes delivery and install." }, "schema": { "$ref": "#/components/schemas/WorkOrderBidUpdate" } } } }, "responses": { "200": { "description": "The updated work order bid.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "work_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bidder_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 790000, "currency": "USD", "bid_state": "Quoted", "notes": "Includes delivery and install." }, "schema": { "$ref": "#/components/schemas/WorkOrderBid" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-order-bids/{id}/award": { "post": { "operationId": "workOrderBids.award", "tags": ["Work"], "x-xos-table": "app.work_order_bids", "x-xos-capability": "work.work_order.award", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Award a work order bid", "description": "Awards the work order to this bid and closes the other bids. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work order bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work order bid.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "work_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bidder_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 790000, "currency": "USD", "bid_state": "Quoted", "notes": "Includes delivery and install." }, "schema": { "$ref": "#/components/schemas/WorkOrderBid" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/run-of-show": { "get": { "operationId": "runsOfShow.list", "tags": ["Show"], "x-xos-table": "app.run_of_show", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List run of show rows", "description": "A run of show for one show scope node. Returns a cursor page of run of show rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of run of show rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Saturday Main Stage", "show_date": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RunOfShowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "runsOfShow.create", "tags": ["Show"], "x-xos-table": "app.run_of_show", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Create a run of show", "description": "A run of show for one show scope node. Creates a run of show. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Saturday Main Stage", "show_date": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RunOfShowCreate" } } } }, "responses": { "201": { "description": "The created run of show.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Saturday Main Stage", "show_date": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RunOfShow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/run-of-show/{id}": { "get": { "operationId": "runsOfShow.get", "tags": ["Show"], "x-xos-table": "app.run_of_show", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Get a run of show", "description": "A run of show for one show scope node. Returns one run of show with its `ETag`. A run of show the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the run of show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the run of show.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The run of show.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Saturday Main Stage", "show_date": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RunOfShow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "runsOfShow.update", "tags": ["Show"], "x-xos-table": "app.run_of_show", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Update a run of show", "description": "A run of show for one show scope node. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the run of show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the run of show.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Saturday Main Stage", "show_date": "2026-10-08", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RunOfShowUpdate" } } } }, "responses": { "200": { "description": "The updated run of show.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Saturday Main Stage", "show_date": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RunOfShow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "runsOfShow.delete", "tags": ["Show"], "x-xos-table": "app.run_of_show", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Delete a run of show", "description": "A run of show for one show scope node. Soft-deletes the run of show: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the run of show.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the run of show.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The run of show moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/cues": { "get": { "operationId": "cues.list", "tags": ["Show"], "x-xos-table": "app.cues", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "x-xos-order": { "by": ["position"], "numeric": false }, "summary": "List cue rows", "description": "A cue in a run of show. Returns a cursor page of cue rows the caller may see. The default order is `position` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of cue rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_of_show_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 10, "label": "Headliner Walk-On", "planned_at": "2026-10-08T14:30:00Z", "called_at": "2026-10-08T14:30:00Z", "duration": "00:05:00", "called_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "segment": "Act II, Official Opening and Remarks", "description": "House lights to half; walk-in music fades.", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CuePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "cues.create", "tags": ["Show"], "x-xos-table": "app.cues", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Create a cue", "description": "A cue in a run of show. Creates a cue. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "run_of_show_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 10, "label": "Headliner Walk-On", "planned_at": "2026-10-08T14:30:00Z", "duration": "00:05:00", "segment": "Act II, Official Opening and Remarks", "description": "House lights to half; walk-in music fades.", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CueCreate" } } } }, "responses": { "201": { "description": "The created cue.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_of_show_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 10, "label": "Headliner Walk-On", "planned_at": "2026-10-08T14:30:00Z", "called_at": "2026-10-08T14:30:00Z", "duration": "00:05:00", "called_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "segment": "Act II, Official Opening and Remarks", "description": "House lights to half; walk-in music fades.", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Cue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/cues/{id}": { "get": { "operationId": "cues.get", "tags": ["Show"], "x-xos-table": "app.cues", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Get a cue", "description": "A cue in a run of show. Returns one cue with its `ETag`. A cue the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cue.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The cue.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_of_show_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 10, "label": "Headliner Walk-On", "planned_at": "2026-10-08T14:30:00Z", "called_at": "2026-10-08T14:30:00Z", "duration": "00:05:00", "called_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "segment": "Act II, Official Opening and Remarks", "description": "House lights to half; walk-in music fades.", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Cue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "cues.update", "tags": ["Show"], "x-xos-table": "app.cues", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Update a cue", "description": "A cue in a run of show. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cue.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "position": 10, "label": "Headliner Walk-On", "planned_at": "2026-10-08T14:30:00Z", "duration": "00:05:00", "segment": "Act II, Official Opening and Remarks", "description": "House lights to half; walk-in music fades.", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CueUpdate" } } } }, "responses": { "200": { "description": "The updated cue.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_of_show_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 10, "label": "Headliner Walk-On", "planned_at": "2026-10-08T14:30:00Z", "called_at": "2026-10-08T14:30:00Z", "duration": "00:05:00", "called_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "segment": "Act II, Official Opening and Remarks", "description": "House lights to half; walk-in music fades.", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Cue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "cues.delete", "tags": ["Show"], "x-xos-table": "app.cues", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Delete a cue", "description": "A cue in a run of show. Soft-deletes the cue: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cue.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The cue moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/cues/{id}/fire": { "post": { "operationId": "cues.fire", "tags": ["Show"], "x-xos-table": "app.cues", "x-xos-capability": "show.cue.call", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Call a cue", "description": "Marks the cue as called now and advances the live run of show to the next cue. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cue.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_of_show_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 10, "label": "Headliner Walk-On", "planned_at": "2026-10-08T14:30:00Z", "called_at": "2026-10-08T14:30:00Z", "duration": "00:05:00", "called_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "segment": "Act II, Official Opening and Remarks", "description": "House lights to half; walk-in music fades.", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Cue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/day-sheets": { "get": { "operationId": "daySheets.list", "tags": ["Show"], "x-xos-table": "app.day_sheets", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List day sheet rows", "description": "A day sheet for one scope node and date. Returns a cursor page of day sheet rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of day sheet rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "body": "Doors at 18:00. Load-out after the encore.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DaySheetPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "daySheets.create", "tags": ["Show"], "x-xos-table": "app.day_sheets", "x-xos-capability": "show.day_sheet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Create a day sheet", "description": "A day sheet for one scope node and date. Creates a day sheet. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "day": "2026-10-08", "body": "Doors at 18:00. Load-out after the encore.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DaySheetCreate" } } } }, "responses": { "201": { "description": "The created day sheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "body": "Doors at 18:00. Load-out after the encore.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DaySheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/day-sheets/{id}": { "get": { "operationId": "daySheets.get", "tags": ["Show"], "x-xos-table": "app.day_sheets", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Get a day sheet", "description": "A day sheet for one scope node and date. Returns one day sheet with its `ETag`. A day sheet the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the day sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the day sheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The day sheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "body": "Doors at 18:00. Load-out after the encore.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DaySheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "daySheets.update", "tags": ["Show"], "x-xos-table": "app.day_sheets", "x-xos-capability": "show.day_sheet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Update a day sheet", "description": "A day sheet for one scope node and date. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the day sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the day sheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "day": "2026-10-08", "body": "Doors at 18:00. Load-out after the encore." }, "schema": { "$ref": "#/components/schemas/DaySheetUpdate" } } } }, "responses": { "200": { "description": "The updated day sheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "body": "Doors at 18:00. Load-out after the encore.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DaySheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "daySheets.delete", "tags": ["Show"], "x-xos-table": "app.day_sheets", "x-xos-capability": "show.day_sheet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Delete a day sheet", "description": "A day sheet for one scope node and date. Soft-deletes the day sheet: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the day sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the day sheet.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The day sheet moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/day-sheets/{id}/publish": { "post": { "operationId": "daySheets.publish", "tags": ["Show"], "x-xos-table": "app.day_sheets", "x-xos-capability": "show.call_sheet.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Publish a day sheet", "description": "Publishes the day sheet to its audience. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the day sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the day sheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "body": "Doors at 18:00. Load-out after the encore.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DaySheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/call-sheets": { "get": { "operationId": "callSheets.list", "tags": ["Show"], "x-xos-table": "app.call_sheets", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List call sheet rows", "description": "A call sheet listing call times for one scope node and date. Returns a cursor page of call sheet rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of call sheet rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CallSheetPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "callSheets.create", "tags": ["Show"], "x-xos-table": "app.call_sheets", "x-xos-capability": "show.day_sheet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Create a call sheet", "description": "A call sheet listing call times for one scope node and date. Creates a call sheet. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "day": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CallSheetCreate" } } } }, "responses": { "201": { "description": "The created call sheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/CallSheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/call-sheets/{id}": { "get": { "operationId": "callSheets.get", "tags": ["Show"], "x-xos-table": "app.call_sheets", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Get a call sheet", "description": "A call sheet listing call times for one scope node and date. Returns one call sheet with its `ETag`. A call sheet the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the call sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the call sheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The call sheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/CallSheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "callSheets.update", "tags": ["Show"], "x-xos-table": "app.call_sheets", "x-xos-capability": "show.day_sheet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Update a call sheet", "description": "A call sheet listing call times for one scope node and date. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the call sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the call sheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "day": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/CallSheetUpdate" } } } }, "responses": { "200": { "description": "The updated call sheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/CallSheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "callSheets.delete", "tags": ["Show"], "x-xos-table": "app.call_sheets", "x-xos-capability": "show.day_sheet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Delete a call sheet", "description": "A call sheet listing call times for one scope node and date. Soft-deletes the call sheet: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the call sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the call sheet.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The call sheet moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/call-sheets/{id}/publish": { "post": { "operationId": "callSheets.publish", "tags": ["Show"], "x-xos-table": "app.call_sheets", "x-xos-capability": "show.call_sheet.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Publish a call sheet", "description": "Publishes the call sheet to the called crew. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the call sheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the call sheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/CallSheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sops": { "get": { "operationId": "sops.list", "tags": ["Knowledge"], "x-xos-table": "app.sops", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List SOP rows", "description": "A standard operating procedure that members acknowledge. Returns a cursor page of SOP rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of SOP rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Working at Height", "body": "Confirm the dock slot, then stage by department.", "code": "SOP-001", "version": 1, "published_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SopPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sops.create", "tags": ["Knowledge"], "x-xos-table": "app.sops", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a SOP", "description": "A standard operating procedure that members acknowledge. Creates a SOP. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Working at Height", "body": "Confirm the dock slot, then stage by department.", "code": "SOP-001" }, "schema": { "$ref": "#/components/schemas/SopCreate" } } } }, "responses": { "201": { "description": "The created SOP.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Working at Height", "body": "Confirm the dock slot, then stage by department.", "code": "SOP-001", "version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Sop" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sops/{id}": { "get": { "operationId": "sops.get", "tags": ["Knowledge"], "x-xos-table": "app.sops", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a SOP", "description": "A standard operating procedure that members acknowledge. Returns one SOP with its `ETag`. A SOP the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sop.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sop.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The SOP.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Working at Height", "body": "Confirm the dock slot, then stage by department.", "code": "SOP-001", "version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Sop" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "sops.update", "tags": ["Knowledge"], "x-xos-table": "app.sops", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a SOP", "description": "A standard operating procedure that members acknowledge. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sop.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sop.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Working at Height", "body": "Confirm the dock slot, then stage by department." }, "schema": { "$ref": "#/components/schemas/SopUpdate" } } } }, "responses": { "200": { "description": "The updated SOP.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Working at Height", "body": "Confirm the dock slot, then stage by department.", "code": "SOP-001", "version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Sop" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "sops.delete", "tags": ["Knowledge"], "x-xos-table": "app.sops", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Delete a SOP", "description": "A standard operating procedure that members acknowledge. Soft-deletes the SOP: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sop.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sop.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The SOP moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sops/{id}/publish": { "post": { "operationId": "sops.publish", "tags": ["Knowledge"], "x-xos-table": "app.sops", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Publish an SOP", "description": "Publishes the SOP: the database stamps `published_at` and raises `version` when it was published before, so everyone is asked to acknowledge the new version. Needs knowledge.sop.publish. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sop.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sop.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Working at Height", "body": "Confirm the dock slot, then stage by department.", "code": "SOP-001", "version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Sop" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sop-acknowledgments": { "get": { "operationId": "sopAcknowledgments.list", "tags": ["Knowledge"], "x-xos-table": "app.sop_acknowledgments", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List SOP acknowledgment rows", "description": "A person's acknowledgment of an SOP version. Returns a cursor page of SOP acknowledgment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of SOP acknowledgment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "acknowledged_at": "2026-10-08T14:30:00Z", "sop_version": 2 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SopAcknowledgmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sopAcknowledgments.create", "tags": ["Knowledge"], "x-xos-table": "app.sop_acknowledgments", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a SOP acknowledgment", "description": "A person's acknowledgment of an SOP version. Creates a SOP acknowledgment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SopAcknowledgmentCreate" } } } }, "responses": { "201": { "description": "The created SOP acknowledgment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "acknowledged_at": "2026-10-08T14:30:00Z", "sop_version": 2 }, "schema": { "$ref": "#/components/schemas/SopAcknowledgment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sop-acknowledgments/{id}": { "get": { "operationId": "sopAcknowledgments.get", "tags": ["Knowledge"], "x-xos-table": "app.sop_acknowledgments", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a SOP acknowledgment", "description": "A person's acknowledgment of an SOP version. Returns one SOP acknowledgment with its `ETag`. A SOP acknowledgment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sop acknowledgment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sop acknowledgment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The SOP acknowledgment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sop_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "acknowledged_at": "2026-10-08T14:30:00Z", "sop_version": 2 }, "schema": { "$ref": "#/components/schemas/SopAcknowledgment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents": { "get": { "operationId": "documents.list", "tags": ["Knowledge"], "x-xos-table": "app.documents", "x-xos-capability": "knowledge.document.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List document rows", "description": "A document with versions. Files are stored in tenant-scoped storage. Returns a cursor page of document rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of document rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Venue Site Plan", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DocumentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "documents.create", "tags": ["Knowledge"], "x-xos-table": "app.documents", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a document", "description": "A document with versions. Files are stored in tenant-scoped storage. Creates a document. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Venue Site Plan", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DocumentCreate" } } } }, "responses": { "201": { "description": "The created document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Venue Site Plan", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/documents/{id}": { "get": { "operationId": "documents.get", "tags": ["Knowledge"], "x-xos-table": "app.documents", "x-xos-capability": "knowledge.document.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a document", "description": "A document with versions. Files are stored in tenant-scoped storage. Returns one document with its `ETag`. A document the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the document.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Venue Site Plan", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "documents.update", "tags": ["Knowledge"], "x-xos-table": "app.documents", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a document", "description": "A document with versions. Files are stored in tenant-scoped storage. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the document.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Venue Site Plan", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DocumentUpdate" } } } }, "responses": { "200": { "description": "The updated document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Venue Site Plan", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "documents.delete", "tags": ["Knowledge"], "x-xos-table": "app.documents", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Delete a document", "description": "A document with versions. Files are stored in tenant-scoped storage. Soft-deletes the document: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the document.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The document moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document-versions": { "get": { "operationId": "documentVersions.list", "tags": ["Knowledge"], "x-xos-table": "app.document_versions", "x-xos-capability": "knowledge.document.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List document version rows", "description": "An immutable version of a document. Returns a cursor page of document version rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of document version rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 3, "storage_uri": "https://files.example.com/site-plan-v3.pdf", "checksum_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DocumentVersionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "documentVersions.create", "tags": ["Knowledge"], "x-xos-table": "app.document_versions", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a document version", "description": "An immutable version of a document. Creates a document version. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "storage_uri": "https://files.example.com/site-plan-v3.pdf", "checksum_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/DocumentVersionCreate" } } } }, "responses": { "201": { "description": "The created document version.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 3, "storage_uri": "https://files.example.com/site-plan-v3.pdf", "checksum_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/DocumentVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/document-versions/{id}": { "get": { "operationId": "documentVersions.get", "tags": ["Knowledge"], "x-xos-table": "app.document_versions", "x-xos-capability": "knowledge.document.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a document version", "description": "An immutable version of a document. Returns one document version with its `ETag`. A document version the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the document version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the document version.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The document version.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 3, "storage_uri": "https://files.example.com/site-plan-v3.pdf", "checksum_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/DocumentVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verbiage-terms": { "get": { "operationId": "verbiageTerms.list", "tags": ["Knowledge"], "x-xos-table": "app.verbiage_terms", "x-xos-capability": "knowledge.verbiage.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List verbiage term rows", "description": "A controlled vocabulary term with casing rules. Em dashes are refused. Returns a cursor page of verbiage term rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of verbiage term rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "term": "Load-In", "casing_rule": "Title Case as a noun", "definition": "The arrival of equipment before a show." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VerbiageTermPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "verbiageTerms.create", "tags": ["Knowledge"], "x-xos-table": "app.verbiage_terms", "x-xos-capability": "knowledge.verbiage.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a verbiage term", "description": "A controlled vocabulary term with casing rules. Em dashes are refused. Creates a verbiage term. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "term": "Load-In", "casing_rule": "Title Case as a noun", "definition": "The arrival of equipment before a show." }, "schema": { "$ref": "#/components/schemas/VerbiageTermCreate" } } } }, "responses": { "201": { "description": "The created verbiage term.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "term": "Load-In", "casing_rule": "Title Case as a noun", "definition": "The arrival of equipment before a show." }, "schema": { "$ref": "#/components/schemas/VerbiageTerm" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verbiage-terms/{id}": { "get": { "operationId": "verbiageTerms.get", "tags": ["Knowledge"], "x-xos-table": "app.verbiage_terms", "x-xos-capability": "knowledge.verbiage.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a verbiage term", "description": "A controlled vocabulary term with casing rules. Em dashes are refused. Returns one verbiage term with its `ETag`. A verbiage term the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verbiage term.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verbiage term.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The verbiage term.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "term": "Load-In", "casing_rule": "Title Case as a noun", "definition": "The arrival of equipment before a show." }, "schema": { "$ref": "#/components/schemas/VerbiageTerm" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "verbiageTerms.update", "tags": ["Knowledge"], "x-xos-table": "app.verbiage_terms", "x-xos-capability": "knowledge.verbiage.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a verbiage term", "description": "A controlled vocabulary term with casing rules. Em dashes are refused. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verbiage term.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verbiage term.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "term": "Load-In", "casing_rule": "Title Case as a noun", "definition": "The arrival of equipment before a show." }, "schema": { "$ref": "#/components/schemas/VerbiageTermUpdate" } } } }, "responses": { "200": { "description": "The updated verbiage term.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "term": "Load-In", "casing_rule": "Title Case as a noun", "definition": "The arrival of equipment before a show." }, "schema": { "$ref": "#/components/schemas/VerbiageTerm" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "verbiageTerms.delete", "tags": ["Knowledge"], "x-xos-table": "app.verbiage_terms", "x-xos-capability": "knowledge.verbiage.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Delete a verbiage term", "description": "A controlled vocabulary term with casing rules. Em dashes are refused. Soft-deletes the verbiage term: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verbiage term.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verbiage term.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The verbiage term moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/venues": { "get": { "operationId": "venues.list", "tags": ["Places"], "x-xos-table": "app.venues", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List venue rows", "description": "A venue. Returns a cursor page of venue rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of venue rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Lawn", "street_address": "100 Harbor Way", "locality": "Miami", "postal_code": "33132", "jurisdiction_id": "US-FL", "time_zone": "America/New_York", "latitude": 25.7617, "longitude": -80.1918 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VenuePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "venues.create", "tags": ["Places"], "x-xos-table": "app.venues", "x-xos-capability": "places.venue.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Create a venue", "description": "A venue. Creates a venue. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harborfront Lawn", "street_address": "100 Harbor Way", "locality": "Miami", "postal_code": "33132", "jurisdiction_id": "US-FL", "time_zone": "America/New_York", "latitude": 25.7617, "longitude": -80.1918 }, "schema": { "$ref": "#/components/schemas/VenueCreate" } } } }, "responses": { "201": { "description": "The created venue.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Lawn", "street_address": "100 Harbor Way", "locality": "Miami", "postal_code": "33132", "jurisdiction_id": "US-FL", "time_zone": "America/New_York", "latitude": 25.7617, "longitude": -80.1918 }, "schema": { "$ref": "#/components/schemas/Venue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/venues/{id}": { "get": { "operationId": "venues.get", "tags": ["Places"], "x-xos-table": "app.venues", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Get a venue", "description": "A venue. Returns one venue with its `ETag`. A venue the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the venue.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The venue.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Lawn", "street_address": "100 Harbor Way", "locality": "Miami", "postal_code": "33132", "jurisdiction_id": "US-FL", "time_zone": "America/New_York", "latitude": 25.7617, "longitude": -80.1918 }, "schema": { "$ref": "#/components/schemas/Venue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "venues.update", "tags": ["Places"], "x-xos-table": "app.venues", "x-xos-capability": "places.venue.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Update a venue", "description": "A venue. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the venue.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harborfront Lawn", "street_address": "100 Harbor Way", "locality": "Miami", "postal_code": "33132", "jurisdiction_id": "US-FL", "time_zone": "America/New_York", "latitude": 25.7617, "longitude": -80.1918 }, "schema": { "$ref": "#/components/schemas/VenueUpdate" } } } }, "responses": { "200": { "description": "The updated venue.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Lawn", "street_address": "100 Harbor Way", "locality": "Miami", "postal_code": "33132", "jurisdiction_id": "US-FL", "time_zone": "America/New_York", "latitude": 25.7617, "longitude": -80.1918 }, "schema": { "$ref": "#/components/schemas/Venue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "venues.delete", "tags": ["Places"], "x-xos-table": "app.venues", "x-xos-capability": "places.venue.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Delete a venue", "description": "A venue. Soft-deletes the venue: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the venue.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the venue.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The venue moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/spaces": { "get": { "operationId": "spaces.list", "tags": ["Places"], "x-xos-table": "app.spaces", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List space rows", "description": "A space within a venue. Returns a cursor page of space rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of space rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "North Lawn", "capacity": 2500, "area_sq_ft": 18000, "urid": "4000.01.01", "description": "Backstage green room for talent." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SpacePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "spaces.create", "tags": ["Places"], "x-xos-table": "app.spaces", "x-xos-capability": "places.space.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Create a space", "description": "A space within a venue. Creates a space. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "North Lawn", "capacity": 2500, "area_sq_ft": 18000, "urid": "4000.01.01", "description": "Backstage green room for talent." }, "schema": { "$ref": "#/components/schemas/SpaceCreate" } } } }, "responses": { "201": { "description": "The created space.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "North Lawn", "capacity": 2500, "area_sq_ft": 18000, "urid": "4000.01.01", "description": "Backstage green room for talent." }, "schema": { "$ref": "#/components/schemas/Space" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/spaces/{id}": { "get": { "operationId": "spaces.get", "tags": ["Places"], "x-xos-table": "app.spaces", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Get a space", "description": "A space within a venue. Returns one space with its `ETag`. A space the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the space.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the space.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The space.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "North Lawn", "capacity": 2500, "area_sq_ft": 18000, "urid": "4000.01.01", "description": "Backstage green room for talent." }, "schema": { "$ref": "#/components/schemas/Space" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "spaces.update", "tags": ["Places"], "x-xos-table": "app.spaces", "x-xos-capability": "places.space.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Update a space", "description": "A space within a venue. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the space.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the space.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "North Lawn", "capacity": 2500, "area_sq_ft": 18000, "urid": "4000.01.01", "description": "Backstage green room for talent." }, "schema": { "$ref": "#/components/schemas/SpaceUpdate" } } } }, "responses": { "200": { "description": "The updated space.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "North Lawn", "capacity": 2500, "area_sq_ft": 18000, "urid": "4000.01.01", "description": "Backstage green room for talent." }, "schema": { "$ref": "#/components/schemas/Space" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "spaces.delete", "tags": ["Places"], "x-xos-table": "app.spaces", "x-xos-capability": "places.space.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Delete a space", "description": "A space within a venue. Soft-deletes the space: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the space.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the space.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The space moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/zones": { "get": { "operationId": "zones.list", "tags": ["Places"], "x-xos-table": "app.zones", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List zone rows", "description": "An access or operations zone within a space. Returns a cursor page of zone rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of zone rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Backstage", "code": "BS", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ZonePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "zones.create", "tags": ["Places"], "x-xos-table": "app.zones", "x-xos-capability": "places.space.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Create a zone", "description": "An access or operations zone within a space. Creates a zone. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Backstage", "code": "BS", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ZoneCreate" } } } }, "responses": { "201": { "description": "The created zone.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Backstage", "code": "BS", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Zone" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/zones/{id}": { "get": { "operationId": "zones.get", "tags": ["Places"], "x-xos-table": "app.zones", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Get a zone", "description": "An access or operations zone within a space. Returns one zone with its `ETag`. A zone the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the zone.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The zone.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Backstage", "code": "BS", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Zone" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "zones.update", "tags": ["Places"], "x-xos-table": "app.zones", "x-xos-capability": "places.space.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Update a zone", "description": "An access or operations zone within a space. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the zone.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Backstage", "code": "BS", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ZoneUpdate" } } } }, "responses": { "200": { "description": "The updated zone.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Backstage", "code": "BS", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Zone" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "zones.delete", "tags": ["Places"], "x-xos-table": "app.zones", "x-xos-capability": "places.space.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Delete a zone", "description": "An access or operations zone within a space. Soft-deletes the zone: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the zone.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the zone.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The zone moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/capability-documents": { "get": { "operationId": "capabilityDocuments.list", "tags": ["Places"], "x-xos-table": "app.capability_documents", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List capability document rows", "description": "A venue capability document with a validity window. A frozen document cannot change. Returns a cursor page of capability document rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of capability document rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "frozen": false, "title": "Tech Pack 2027", "document_uri": "https://docs.example.com/tech-pack.pdf" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CapabilityDocumentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "capabilityDocuments.create", "tags": ["Places"], "x-xos-table": "app.capability_documents", "x-xos-capability": "places.capability_document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Create a capability document", "description": "A venue capability document with a validity window. A frozen document cannot change. Creates a capability document. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "title": "Tech Pack 2027", "document_uri": "https://docs.example.com/tech-pack.pdf" }, "schema": { "$ref": "#/components/schemas/CapabilityDocumentCreate" } } } }, "responses": { "201": { "description": "The created capability document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "frozen": false, "title": "Tech Pack 2027", "document_uri": "https://docs.example.com/tech-pack.pdf" }, "schema": { "$ref": "#/components/schemas/CapabilityDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/capability-documents/{id}": { "get": { "operationId": "capabilityDocuments.get", "tags": ["Places"], "x-xos-table": "app.capability_documents", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Get a capability document", "description": "A venue capability document with a validity window. A frozen document cannot change. Returns one capability document with its `ETag`. A capability document the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the capability document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the capability document.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The capability document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "frozen": false, "title": "Tech Pack 2027", "document_uri": "https://docs.example.com/tech-pack.pdf" }, "schema": { "$ref": "#/components/schemas/CapabilityDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "capabilityDocuments.update", "tags": ["Places"], "x-xos-table": "app.capability_documents", "x-xos-capability": "places.capability_document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Update a capability document", "description": "A venue capability document with a validity window. A frozen document cannot change. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the capability document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the capability document.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_from": "2026-10-08", "valid_to": "2026-10-08", "title": "Tech Pack 2027", "document_uri": "https://docs.example.com/tech-pack.pdf" }, "schema": { "$ref": "#/components/schemas/CapabilityDocumentUpdate" } } } }, "responses": { "200": { "description": "The updated capability document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "frozen": false, "title": "Tech Pack 2027", "document_uri": "https://docs.example.com/tech-pack.pdf" }, "schema": { "$ref": "#/components/schemas/CapabilityDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "capabilityDocuments.delete", "tags": ["Places"], "x-xos-table": "app.capability_documents", "x-xos-capability": "places.capability_document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Delete a capability document", "description": "A venue capability document with a validity window. A frozen document cannot change. Soft-deletes the capability document: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the capability document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the capability document.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The capability document moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/capability-documents/{id}/freeze": { "post": { "operationId": "capabilityDocuments.freeze", "tags": ["Places"], "x-xos-table": "app.capability_documents", "x-xos-capability": "places.capability_document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Freeze a capability document", "description": "Freezes the document so its content and validity window can no longer change. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the capability document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the capability document.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "frozen": false, "title": "Tech Pack 2027", "document_uri": "https://docs.example.com/tech-pack.pdf" }, "schema": { "$ref": "#/components/schemas/CapabilityDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/site-plans": { "get": { "operationId": "sitePlans.list", "tags": ["Places"], "x-xos-table": "app.site_plans", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List site plan rows", "description": "A site plan drawing for a venue. Returns a cursor page of site plan rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of site plan rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Festival Layout", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "image_uri": "plans/ground.png" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SitePlanPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sitePlans.create", "tags": ["Places"], "x-xos-table": "app.site_plans", "x-xos-capability": "places.site_plan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Create a site plan", "description": "A site plan drawing for a venue. Creates a site plan. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Festival Layout", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "image_uri": "plans/ground.png" }, "schema": { "$ref": "#/components/schemas/SitePlanCreate" } } } }, "responses": { "201": { "description": "The created site plan.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Festival Layout", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "image_uri": "plans/ground.png" }, "schema": { "$ref": "#/components/schemas/SitePlan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/site-plans/{id}": { "get": { "operationId": "sitePlans.get", "tags": ["Places"], "x-xos-table": "app.site_plans", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Get a site plan", "description": "A site plan drawing for a venue. Returns one site plan with its `ETag`. A site plan the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the site plan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the site plan.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The site plan.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Festival Layout", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "image_uri": "plans/ground.png" }, "schema": { "$ref": "#/components/schemas/SitePlan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "sitePlans.update", "tags": ["Places"], "x-xos-table": "app.site_plans", "x-xos-capability": "places.site_plan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Update a site plan", "description": "A site plan drawing for a venue. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the site plan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the site plan.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Festival Layout", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "image_uri": "plans/ground.png" }, "schema": { "$ref": "#/components/schemas/SitePlanUpdate" } } } }, "responses": { "200": { "description": "The updated site plan.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Festival Layout", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "image_uri": "plans/ground.png" }, "schema": { "$ref": "#/components/schemas/SitePlan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "sitePlans.delete", "tags": ["Places"], "x-xos-table": "app.site_plans", "x-xos-capability": "places.site_plan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Delete a site plan", "description": "A site plan drawing for a venue. Soft-deletes the site plan: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the site plan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the site plan.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The site plan moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/site-plan-pins": { "get": { "operationId": "sitePlanPins.list", "tags": ["Places"], "x-xos-table": "app.site_plan_pins", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List site plan pin rows", "description": "A pin on a site plan. Returns a cursor page of site plan pin rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of site plan pin rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "site_plan_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "First Aid", "x": 0.42, "y": 0.71, "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SitePlanPinPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sitePlanPins.create", "tags": ["Places"], "x-xos-table": "app.site_plan_pins", "x-xos-capability": "places.site_plan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Create a site plan pin", "description": "A pin on a site plan. Creates a site plan pin. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "site_plan_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "First Aid", "x": 0.42, "y": 0.71, "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SitePlanPinCreate" } } } }, "responses": { "201": { "description": "The created site plan pin.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "site_plan_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "First Aid", "x": 0.42, "y": 0.71, "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SitePlanPin" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/site-plan-pins/{id}": { "get": { "operationId": "sitePlanPins.get", "tags": ["Places"], "x-xos-table": "app.site_plan_pins", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Get a site plan pin", "description": "A pin on a site plan. Returns one site plan pin with its `ETag`. A site plan pin the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the site plan pin.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the site plan pin.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The site plan pin.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "site_plan_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "First Aid", "x": 0.42, "y": 0.71, "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SitePlanPin" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "sitePlanPins.update", "tags": ["Places"], "x-xos-table": "app.site_plan_pins", "x-xos-capability": "places.site_plan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Update a site plan pin", "description": "A pin on a site plan. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the site plan pin.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the site plan pin.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "label": "First Aid", "x": 0.42, "y": 0.71, "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SitePlanPinUpdate" } } } }, "responses": { "200": { "description": "The updated site plan pin.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "site_plan_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "First Aid", "x": 0.42, "y": 0.71, "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SitePlanPin" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "sitePlanPins.delete", "tags": ["Places"], "x-xos-table": "app.site_plan_pins", "x-xos-capability": "places.site_plan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Delete a site plan pin", "description": "A pin on a site plan. Soft-deletes the site plan pin: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the site plan pin.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the site plan pin.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The site plan pin moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/geofences": { "get": { "operationId": "geofences.list", "tags": ["Places"], "x-xos-table": "app.geofences", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List geofence rows", "description": "A geofence used for Compass clock in. Returns a cursor page of geofence rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of geofence rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Site", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "boundary": { "type": "Polygon", "coordinates": [ [ [-80.19, 25.77], [-80.18, 25.77], [-80.18, 25.78], [-80.19, 25.77] ] ] } } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/GeofencePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "geofences.create", "tags": ["Places"], "x-xos-table": "app.geofences", "x-xos-capability": "org.time_attendance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a geofence", "description": "A geofence used for Compass clock in. Creates a geofence. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harborfront Site", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "boundary": { "type": "Polygon", "coordinates": [ [ [-80.19, 25.77], [-80.18, 25.77], [-80.18, 25.78], [-80.19, 25.77] ] ] } }, "schema": { "$ref": "#/components/schemas/GeofenceCreate" } } } }, "responses": { "201": { "description": "The created geofence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Site", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "boundary": { "type": "Polygon", "coordinates": [ [ [-80.19, 25.77], [-80.18, 25.77], [-80.18, 25.78], [-80.19, 25.77] ] ] } }, "schema": { "$ref": "#/components/schemas/Geofence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/geofences/{id}": { "get": { "operationId": "geofences.get", "tags": ["Places"], "x-xos-table": "app.geofences", "x-xos-capability": "places.venue.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["places"] }], "summary": "Get a geofence", "description": "A geofence used for Compass clock in. Returns one geofence with its `ETag`. A geofence the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the geofence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the geofence.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The geofence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Site", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "boundary": { "type": "Polygon", "coordinates": [ [ [-80.19, 25.77], [-80.18, 25.77], [-80.18, 25.78], [-80.19, 25.77] ] ] } }, "schema": { "$ref": "#/components/schemas/Geofence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "geofences.update", "tags": ["Places"], "x-xos-table": "app.geofences", "x-xos-capability": "org.time_attendance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a geofence", "description": "A geofence used for Compass clock in. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the geofence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the geofence.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harborfront Site", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "boundary": { "type": "Polygon", "coordinates": [ [ [-80.19, 25.77], [-80.18, 25.77], [-80.18, 25.78], [-80.19, 25.77] ] ] } }, "schema": { "$ref": "#/components/schemas/GeofenceUpdate" } } } }, "responses": { "200": { "description": "The updated geofence.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Harborfront Site", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "boundary": { "type": "Polygon", "coordinates": [ [ [-80.19, 25.77], [-80.18, 25.77], [-80.18, 25.78], [-80.19, 25.77] ] ] } }, "schema": { "$ref": "#/components/schemas/Geofence" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "geofences.delete", "tags": ["Places"], "x-xos-table": "app.geofences", "x-xos-capability": "org.time_attendance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a geofence", "description": "A geofence used for Compass clock in. Soft-deletes the geofence: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the geofence.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the geofence.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The geofence moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/requirements": { "get": { "operationId": "requirements.list", "tags": ["Places"], "x-xos-table": "app.capability_statements", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List requirement rows", "description": "A requirement or a capability: one shape with a direction facet, so reconciliation is a join. Returns a cursor page of requirement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of requirement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Require", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Three-phase 400 A power at stage left.", "quantity": 1, "unit_basis": "each", "is_critical": true, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assertion_word": "DOCUMENTED" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RequirementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "requirements.create", "tags": ["Places"], "x-xos-table": "app.capability_statements", "x-xos-capability": "projects.scope.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a requirement", "description": "A requirement or a capability: one shape with a direction facet, so reconciliation is a join. Creates a requirement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "direction": "Require", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Three-phase 400 A power at stage left.", "quantity": 1, "unit_basis": "each", "is_critical": true, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assertion_word": "DOCUMENTED" }, "schema": { "$ref": "#/components/schemas/RequirementCreate" } } } }, "responses": { "201": { "description": "The created requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Require", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Three-phase 400 A power at stage left.", "quantity": 1, "unit_basis": "each", "is_critical": true, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assertion_word": "DOCUMENTED" }, "schema": { "$ref": "#/components/schemas/Requirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/requirements/{id}": { "get": { "operationId": "requirements.get", "tags": ["Places"], "x-xos-table": "app.capability_statements", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a requirement", "description": "A requirement or a capability: one shape with a direction facet, so reconciliation is a join. Returns one requirement with its `ETag`. A requirement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Require", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Three-phase 400 A power at stage left.", "quantity": 1, "unit_basis": "each", "is_critical": true, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assertion_word": "DOCUMENTED" }, "schema": { "$ref": "#/components/schemas/Requirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "requirements.update", "tags": ["Places"], "x-xos-table": "app.capability_statements", "x-xos-capability": "projects.scope.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a requirement", "description": "A requirement or a capability: one shape with a direction facet, so reconciliation is a join. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Three-phase 400 A power at stage left.", "quantity": 1, "unit_basis": "each", "is_critical": true, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assertion_word": "DOCUMENTED" }, "schema": { "$ref": "#/components/schemas/RequirementUpdate" } } } }, "responses": { "200": { "description": "The updated requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Require", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Three-phase 400 A power at stage left.", "quantity": 1, "unit_basis": "each", "is_critical": true, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assertion_word": "DOCUMENTED" }, "schema": { "$ref": "#/components/schemas/Requirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "requirements.delete", "tags": ["Places"], "x-xos-table": "app.capability_statements", "x-xos-capability": "projects.scope.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a requirement", "description": "A requirement or a capability: one shape with a direction facet, so reconciliation is a join. Soft-deletes the requirement: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requirement.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The requirement moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reconciliations": { "get": { "operationId": "reconciliations.list", "tags": ["Places"], "x-xos-table": "app.reconciliations", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List reconciliation rows", "description": "A reconciliation run of requirements against capabilities. Returns a cursor page of reconciliation rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of reconciliation rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_at": "2026-10-08T14:30:00Z", "met_count": 18, "gap_count": 2, "unknown_count": 1, "note": "Venue walk." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReconciliationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "reconciliations.create", "tags": ["Places"], "x-xos-table": "app.reconciliations", "x-xos-capability": "advancing.reconciliation.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create a reconciliation", "description": "A reconciliation run of requirements against capabilities. Creates a reconciliation. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Venue walk." }, "schema": { "$ref": "#/components/schemas/ReconciliationCreate" } } } }, "responses": { "201": { "description": "The created reconciliation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_at": "2026-10-08T14:30:00Z", "met_count": 18, "gap_count": 2, "unknown_count": 1, "note": "Venue walk." }, "schema": { "$ref": "#/components/schemas/Reconciliation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reconciliations/{id}": { "get": { "operationId": "reconciliations.get", "tags": ["Places"], "x-xos-table": "app.reconciliations", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get a reconciliation", "description": "A reconciliation run of requirements against capabilities. Returns one reconciliation with its `ETag`. A reconciliation the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the reconciliation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the reconciliation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The reconciliation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "run_at": "2026-10-08T14:30:00Z", "met_count": 18, "gap_count": 2, "unknown_count": 1, "note": "Venue walk." }, "schema": { "$ref": "#/components/schemas/Reconciliation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reconciliation-lines": { "get": { "operationId": "reconciliationLines.list", "tags": ["Places"], "x-xos-table": "app.reconciliation_lines", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List reconciliation line rows", "description": "One requirement's reconciliation result. Returns a cursor page of reconciliation line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of reconciliation line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reconciliation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requirement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "result": "Met" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReconciliationLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reconciliation-lines/{id}": { "get": { "operationId": "reconciliationLines.get", "tags": ["Places"], "x-xos-table": "app.reconciliation_lines", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get a reconciliation line", "description": "One requirement's reconciliation result. Returns one reconciliation line with its `ETag`. A reconciliation line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the reconciliation line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the reconciliation line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The reconciliation line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reconciliation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requirement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "result": "Met" }, "schema": { "$ref": "#/components/schemas/ReconciliationLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shipments": { "get": { "operationId": "shipments.list", "tags": ["Logistics"], "x-xos-table": "app.shipments", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "x-xos-order": { "by": ["ships_at"], "numeric": false }, "summary": "List shipment rows", "description": "A shipment into or out of a venue. Returns a cursor page of shipment rows the caller may see. The default order is `ships_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of shipment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tracking_identifier": "CF123456789", "direction": "inbound", "ships_at": "2026-10-08T14:30:00Z", "carrier_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "freight_type_enum_id": "ENM-041", "arrives_at": "2026-10-08T14:30:00Z", "shipment_number": 7, "urid": "4000.01.01", "description": "Two pallets of truss and motors.", "origin": "Orlando, FL", "sender_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pallet_count": 2, "piece_count": 14, "length_ft": 48, "width_ft": 8.5, "height_ft": 9, "weight_lb": 12000, "trailer_license": "FL TRL-4410", "seal_identifier": "SL-778120", "bill_of_lading_identifier": "BOL-2027-0611" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ShipmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "shipments.create", "tags": ["Logistics"], "x-xos-table": "app.shipments", "x-xos-capability": "logistics.shipment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Create a shipment", "description": "A shipment into or out of a venue. Creates a shipment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tracking_identifier": "CF123456789", "direction": "inbound", "ships_at": "2026-10-08T14:30:00Z", "carrier_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "freight_type_enum_id": "ENM-041", "arrives_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01", "description": "Two pallets of truss and motors.", "origin": "Orlando, FL", "sender_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pallet_count": 2, "piece_count": 14, "length_ft": 48, "width_ft": 8.5, "height_ft": 9, "weight_lb": 12000, "trailer_license": "FL TRL-4410", "seal_identifier": "SL-778120", "bill_of_lading_identifier": "BOL-2027-0611" }, "schema": { "$ref": "#/components/schemas/ShipmentCreate" } } } }, "responses": { "201": { "description": "The created shipment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tracking_identifier": "CF123456789", "direction": "inbound", "ships_at": "2026-10-08T14:30:00Z", "carrier_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "freight_type_enum_id": "ENM-041", "arrives_at": "2026-10-08T14:30:00Z", "shipment_number": 7, "urid": "4000.01.01", "description": "Two pallets of truss and motors.", "origin": "Orlando, FL", "sender_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pallet_count": 2, "piece_count": 14, "length_ft": 48, "width_ft": 8.5, "height_ft": 9, "weight_lb": 12000, "trailer_license": "FL TRL-4410", "seal_identifier": "SL-778120", "bill_of_lading_identifier": "BOL-2027-0611" }, "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shipments/{id}": { "get": { "operationId": "shipments.get", "tags": ["Logistics"], "x-xos-table": "app.shipments", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Get a shipment", "description": "A shipment into or out of a venue. Returns one shipment with its `ETag`. A shipment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shipment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The shipment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tracking_identifier": "CF123456789", "direction": "inbound", "ships_at": "2026-10-08T14:30:00Z", "carrier_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "freight_type_enum_id": "ENM-041", "arrives_at": "2026-10-08T14:30:00Z", "shipment_number": 7, "urid": "4000.01.01", "description": "Two pallets of truss and motors.", "origin": "Orlando, FL", "sender_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pallet_count": 2, "piece_count": 14, "length_ft": 48, "width_ft": 8.5, "height_ft": 9, "weight_lb": 12000, "trailer_license": "FL TRL-4410", "seal_identifier": "SL-778120", "bill_of_lading_identifier": "BOL-2027-0611" }, "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "shipments.update", "tags": ["Logistics"], "x-xos-table": "app.shipments", "x-xos-capability": "logistics.shipment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Update a shipment", "description": "A shipment into or out of a venue. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shipment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "tracking_identifier": "CF123456789", "direction": "inbound", "ships_at": "2026-10-08T14:30:00Z", "carrier_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "freight_type_enum_id": "ENM-041", "arrives_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01", "description": "Two pallets of truss and motors.", "origin": "Orlando, FL", "sender_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pallet_count": 2, "piece_count": 14, "length_ft": 48, "width_ft": 8.5, "height_ft": 9, "weight_lb": 12000, "trailer_license": "FL TRL-4410", "seal_identifier": "SL-778120", "bill_of_lading_identifier": "BOL-2027-0611" }, "schema": { "$ref": "#/components/schemas/ShipmentUpdate" } } } }, "responses": { "200": { "description": "The updated shipment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tracking_identifier": "CF123456789", "direction": "inbound", "ships_at": "2026-10-08T14:30:00Z", "carrier_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "freight_type_enum_id": "ENM-041", "arrives_at": "2026-10-08T14:30:00Z", "shipment_number": 7, "urid": "4000.01.01", "description": "Two pallets of truss and motors.", "origin": "Orlando, FL", "sender_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pallet_count": 2, "piece_count": 14, "length_ft": 48, "width_ft": 8.5, "height_ft": 9, "weight_lb": 12000, "trailer_license": "FL TRL-4410", "seal_identifier": "SL-778120", "bill_of_lading_identifier": "BOL-2027-0611" }, "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "shipments.delete", "tags": ["Logistics"], "x-xos-table": "app.shipments", "x-xos-capability": "logistics.shipment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Delete a shipment", "description": "A shipment into or out of a venue. Soft-deletes the shipment: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shipment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shipment.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The shipment moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shipment-lines": { "get": { "operationId": "shipmentLines.list", "tags": ["Logistics"], "x-xos-table": "app.shipment_lines", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List shipment line rows", "description": "A line on a shipping manifest. Returns a cursor page of shipment line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of shipment line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Truss sections, 10 ft", "quantity": 24, "element_id": "4000.01.01-XPMS-001" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ShipmentLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "shipmentLines.create", "tags": ["Logistics"], "x-xos-table": "app.shipment_lines", "x-xos-capability": "logistics.shipment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Create a shipment line", "description": "A line on a shipping manifest. Creates a shipment line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Truss sections, 10 ft", "quantity": 24, "element_id": "4000.01.01-XPMS-001" }, "schema": { "$ref": "#/components/schemas/ShipmentLineCreate" } } } }, "responses": { "201": { "description": "The created shipment line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Truss sections, 10 ft", "quantity": 24, "element_id": "4000.01.01-XPMS-001" }, "schema": { "$ref": "#/components/schemas/ShipmentLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shipment-lines/{id}": { "get": { "operationId": "shipmentLines.get", "tags": ["Logistics"], "x-xos-table": "app.shipment_lines", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Get a shipment line", "description": "A line on a shipping manifest. Returns one shipment line with its `ETag`. A shipment line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shipment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shipment line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The shipment line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Truss sections, 10 ft", "quantity": 24, "element_id": "4000.01.01-XPMS-001" }, "schema": { "$ref": "#/components/schemas/ShipmentLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "shipmentLines.update", "tags": ["Logistics"], "x-xos-table": "app.shipment_lines", "x-xos-capability": "logistics.shipment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Update a shipment line", "description": "A line on a shipping manifest. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shipment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shipment line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Truss sections, 10 ft", "quantity": 24, "element_id": "4000.01.01-XPMS-001" }, "schema": { "$ref": "#/components/schemas/ShipmentLineUpdate" } } } }, "responses": { "200": { "description": "The updated shipment line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Truss sections, 10 ft", "quantity": 24, "element_id": "4000.01.01-XPMS-001" }, "schema": { "$ref": "#/components/schemas/ShipmentLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "shipmentLines.delete", "tags": ["Logistics"], "x-xos-table": "app.shipment_lines", "x-xos-capability": "logistics.shipment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Delete a shipment line", "description": "A line on a shipping manifest. Soft-deletes the shipment line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shipment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shipment line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The shipment line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dock-slots": { "get": { "operationId": "dockSlots.list", "tags": ["Logistics"], "x-xos-table": "app.dock_slots", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List dock slot rows", "description": "A dock slot booking. Returns a cursor page of dock slot rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of dock slot rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "checked_in_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DockSlotPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "dockSlots.create", "tags": ["Logistics"], "x-xos-table": "app.dock_slots", "x-xos-capability": "logistics.dock_slot.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Create a dock slot", "description": "A dock slot booking. Creates a dock slot. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DockSlotCreate" } } } }, "responses": { "201": { "description": "The created dock slot.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "checked_in_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DockSlot" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dock-slots/{id}": { "get": { "operationId": "dockSlots.get", "tags": ["Logistics"], "x-xos-table": "app.dock_slots", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Get a dock slot", "description": "A dock slot booking. Returns one dock slot with its `ETag`. A dock slot the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dock slot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dock slot.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The dock slot.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "checked_in_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DockSlot" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "dockSlots.update", "tags": ["Logistics"], "x-xos-table": "app.dock_slots", "x-xos-capability": "logistics.dock_slot.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Update a dock slot", "description": "A dock slot booking. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dock slot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dock slot.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DockSlotUpdate" } } } }, "responses": { "200": { "description": "The updated dock slot.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "checked_in_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DockSlot" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "dockSlots.delete", "tags": ["Logistics"], "x-xos-table": "app.dock_slots", "x-xos-capability": "logistics.dock_slot.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Delete a dock slot", "description": "A dock slot booking. Soft-deletes the dock slot: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dock slot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dock slot.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The dock slot moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dock-slots/{id}/check-in": { "post": { "operationId": "dockSlots.checkIn", "tags": ["Logistics"], "x-xos-table": "app.dock_slots", "x-xos-capability": "logistics.yard.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Check in at a dock slot", "description": "Records the vehicle's check-in at the dock slot. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dock slot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dock slot.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "checked_in_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DockSlot" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/gate-queue": { "get": { "operationId": "gateQueueEntries.list", "tags": ["Logistics"], "x-xos-table": "app.gate_queue", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List gate queue entry rows", "description": "A vehicle waiting at the venue gate. Returns a cursor page of gate queue entry rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of gate queue entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_identifier": "FL TRK-2231", "arrived_at": "2026-10-08T14:30:00Z", "released_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "released_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_type": "53ft Tractor-Trailer", "driver_name": "Luis Ortega" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/GateQueueEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "gateQueueEntries.create", "tags": ["Logistics"], "x-xos-table": "app.gate_queue", "x-xos-capability": "logistics.yard.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Create a gate queue entry", "description": "A vehicle waiting at the venue gate. Creates a gate queue entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "vehicle_identifier": "FL TRK-2231", "arrived_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_type": "53ft Tractor-Trailer", "driver_name": "Luis Ortega" }, "schema": { "$ref": "#/components/schemas/GateQueueEntryCreate" } } } }, "responses": { "201": { "description": "The created gate queue entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_identifier": "FL TRK-2231", "arrived_at": "2026-10-08T14:30:00Z", "released_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "released_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_type": "53ft Tractor-Trailer", "driver_name": "Luis Ortega" }, "schema": { "$ref": "#/components/schemas/GateQueueEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/gate-queue/{id}": { "get": { "operationId": "gateQueueEntries.get", "tags": ["Logistics"], "x-xos-table": "app.gate_queue", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Get a gate queue entry", "description": "A vehicle waiting at the venue gate. Returns one gate queue entry with its `ETag`. A gate queue entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the gate queue entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the gate queue entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The gate queue entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_identifier": "FL TRK-2231", "arrived_at": "2026-10-08T14:30:00Z", "released_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "released_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_type": "53ft Tractor-Trailer", "driver_name": "Luis Ortega" }, "schema": { "$ref": "#/components/schemas/GateQueueEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "gateQueueEntries.update", "tags": ["Logistics"], "x-xos-table": "app.gate_queue", "x-xos-capability": "logistics.yard.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Update a gate queue entry", "description": "A vehicle waiting at the venue gate. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the gate queue entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the gate queue entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "vehicle_identifier": "FL TRK-2231", "arrived_at": "2026-10-08T14:30:00Z", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_type": "53ft Tractor-Trailer", "driver_name": "Luis Ortega" }, "schema": { "$ref": "#/components/schemas/GateQueueEntryUpdate" } } } }, "responses": { "200": { "description": "The updated gate queue entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_identifier": "FL TRK-2231", "arrived_at": "2026-10-08T14:30:00Z", "released_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "released_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_type": "53ft Tractor-Trailer", "driver_name": "Luis Ortega" }, "schema": { "$ref": "#/components/schemas/GateQueueEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/gate-queue/{id}/release": { "post": { "operationId": "gateQueueEntries.release", "tags": ["Logistics"], "x-xos-table": "app.gate_queue", "x-xos-capability": "logistics.release.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Release a vehicle", "description": "Releases the vehicle from the gate queue to its dock. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the gate queue entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the gate queue entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_identifier": "FL TRK-2231", "arrived_at": "2026-10-08T14:30:00Z", "released_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "released_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vehicle_type": "53ft Tractor-Trailer", "driver_name": "Luis Ortega" }, "schema": { "$ref": "#/components/schemas/GateQueueEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/marshalling-log": { "get": { "operationId": "marshallingLogEntries.list", "tags": ["Logistics"], "x-xos-table": "app.marshalling_log", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "x-xos-order": { "by": ["logged_at"], "numeric": false }, "summary": "List marshalling log entry rows", "description": "A marshalling yard log entry: staging and release. Returns a cursor page of marshalling log entry rows the caller may see. The default order is `logged_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of marshalling log entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry": "Staged in lane 2.", "logged_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01.01" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MarshallingLogEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "marshallingLogEntries.create", "tags": ["Logistics"], "x-xos-table": "app.marshalling_log", "x-xos-capability": "logistics.yard.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Create a marshalling log entry", "description": "A marshalling yard log entry: staging and release. Creates a marshalling log entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "entry": "Staged in lane 2.", "logged_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/MarshallingLogEntryCreate" } } } }, "responses": { "201": { "description": "The created marshalling log entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry": "Staged in lane 2.", "logged_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/MarshallingLogEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/marshalling-log/{id}": { "get": { "operationId": "marshallingLogEntries.get", "tags": ["Logistics"], "x-xos-table": "app.marshalling_log", "x-xos-capability": "logistics.shipment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["logistics"] }], "summary": "Get a marshalling log entry", "description": "A marshalling yard log entry: staging and release. Returns one marshalling log entry with its `ETag`. A marshalling log entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the marshalling log entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the marshalling log entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The marshalling log entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry": "Staged in lane 2.", "logged_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shipment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/MarshallingLogEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-packets": { "get": { "operationId": "advancePackets.list", "tags": ["Advancing"], "x-xos-table": "app.advance_packets", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List advance packet rows", "description": "An advance packet sent to parties for one project. Returns a cursor page of advance packet rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of advance packet rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Headliner Advance", "due_at": "2026-10-08T14:30:00Z", "sent_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AdvancePacketPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "advancePackets.create", "tags": ["Advancing"], "x-xos-table": "app.advance_packets", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create an advance packet", "description": "An advance packet sent to parties for one project. Creates an advance packet. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Headliner Advance", "due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AdvancePacketCreate" } } } }, "responses": { "201": { "description": "The created advance packet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Headliner Advance", "due_at": "2026-10-08T14:30:00Z", "sent_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AdvancePacket" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-packets/{id}": { "get": { "operationId": "advancePackets.get", "tags": ["Advancing"], "x-xos-table": "app.advance_packets", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get an advance packet", "description": "An advance packet sent to parties for one project. Returns one advance packet with its `ETag`. A advance packet the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance packet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The advance packet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Headliner Advance", "due_at": "2026-10-08T14:30:00Z", "sent_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AdvancePacket" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "advancePackets.update", "tags": ["Advancing"], "x-xos-table": "app.advance_packets", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Update an advance packet", "description": "An advance packet sent to parties for one project. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance packet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Headliner Advance", "due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AdvancePacketUpdate" } } } }, "responses": { "200": { "description": "The updated advance packet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Headliner Advance", "due_at": "2026-10-08T14:30:00Z", "sent_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AdvancePacket" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "advancePackets.delete", "tags": ["Advancing"], "x-xos-table": "app.advance_packets", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Delete an advance packet", "description": "An advance packet sent to parties for one project. Soft-deletes the advance packet: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance packet.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The advance packet moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-packets/{id}/send": { "post": { "operationId": "advancePackets.send", "tags": ["Advancing"], "x-xos-table": "app.advance_packets", "x-xos-capability": "advancing.packet.send", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Send an advance packet", "description": "Sends the packet to every recipient. Recipients without an account receive a token link and access code. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance packet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance packet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Headliner Advance", "due_at": "2026-10-08T14:30:00Z", "sent_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AdvancePacket" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-sections": { "get": { "operationId": "advanceSections.list", "tags": ["Advancing"], "x-xos-table": "app.advance_sections", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["position"], "numeric": false }, "summary": "List advance section rows", "description": "A section of an advance packet. Returns a cursor page of advance section rows the caller may see. The default order is `position` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of advance section rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Hospitality", "prompt": "When does the party arrive?" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AdvanceSectionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "advanceSections.create", "tags": ["Advancing"], "x-xos-table": "app.advance_sections", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create an advance section", "description": "A section of an advance packet. Creates an advance section. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Hospitality", "prompt": "When does the party arrive?" }, "schema": { "$ref": "#/components/schemas/AdvanceSectionCreate" } } } }, "responses": { "201": { "description": "The created advance section.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Hospitality", "prompt": "When does the party arrive?" }, "schema": { "$ref": "#/components/schemas/AdvanceSection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-sections/{id}": { "get": { "operationId": "advanceSections.get", "tags": ["Advancing"], "x-xos-table": "app.advance_sections", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get an advance section", "description": "A section of an advance packet. Returns one advance section with its `ETag`. A advance section the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance section.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The advance section.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Hospitality", "prompt": "When does the party arrive?" }, "schema": { "$ref": "#/components/schemas/AdvanceSection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "advanceSections.update", "tags": ["Advancing"], "x-xos-table": "app.advance_sections", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Update an advance section", "description": "A section of an advance packet. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance section.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "position": 1, "title": "Hospitality", "prompt": "When does the party arrive?" }, "schema": { "$ref": "#/components/schemas/AdvanceSectionUpdate" } } } }, "responses": { "200": { "description": "The updated advance section.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Hospitality", "prompt": "When does the party arrive?" }, "schema": { "$ref": "#/components/schemas/AdvanceSection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "advanceSections.delete", "tags": ["Advancing"], "x-xos-table": "app.advance_sections", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Delete an advance section", "description": "A section of an advance packet. Soft-deletes the advance section: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance section.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The advance section moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-recipients": { "get": { "operationId": "advanceRecipients.list", "tags": ["Advancing"], "x-xos-table": "app.advance_recipients", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List advance recipient rows", "description": "A party bound to an advance packet. Recipients without an account use a token and access code. Returns a cursor page of advance recipient rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of advance recipient rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AdvanceRecipientPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "advanceRecipients.create", "tags": ["Advancing"], "x-xos-table": "app.advance_recipients", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create an advance recipient", "description": "A party bound to an advance packet. Recipients without an account use a token and access code. Creates an advance recipient. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AdvanceRecipientCreate" } } } }, "responses": { "201": { "description": "The created advance recipient.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AdvanceRecipient" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-recipients/{id}": { "get": { "operationId": "advanceRecipients.get", "tags": ["Advancing"], "x-xos-table": "app.advance_recipients", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get an advance recipient", "description": "A party bound to an advance packet. Recipients without an account use a token and access code. Returns one advance recipient with its `ETag`. A advance recipient the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance recipient.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The advance recipient.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_packet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AdvanceRecipient" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "advanceRecipients.delete", "tags": ["Advancing"], "x-xos-table": "app.advance_recipients", "x-xos-capability": "advancing.packet.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Delete an advance recipient", "description": "A party bound to an advance packet. Recipients without an account use a token and access code. Soft-deletes the advance recipient: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance recipient.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The advance recipient moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-submissions": { "get": { "operationId": "advanceSubmissions.list", "tags": ["Advancing"], "x-xos-table": "app.advance_submissions", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List advance submission rows", "description": "A recipient's submission for one section. Returns a cursor page of advance submission rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of advance submission rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_recipient_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_at": "2026-10-08T14:30:00Z", "body": "Party of 8 lands at 14:20.", "reviewed_at": "2026-10-08T14:30:00Z", "reviewed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "review_outcome": "Accepted", "return_reason": "Please add the flight number.", "via_link": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AdvanceSubmissionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "advanceSubmissions.create", "tags": ["Advancing"], "x-xos-table": "app.advance_submissions", "x-xos-capability": "advancing.submission.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create an advance submission", "description": "A recipient's submission for one section. Creates an advance submission. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "advance_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_recipient_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Party of 8 lands at 14:20." }, "schema": { "$ref": "#/components/schemas/AdvanceSubmissionCreate" } } } }, "responses": { "201": { "description": "The created advance submission.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_recipient_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_at": "2026-10-08T14:30:00Z", "body": "Party of 8 lands at 14:20.", "reviewed_at": "2026-10-08T14:30:00Z", "reviewed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "review_outcome": "Accepted", "return_reason": "Please add the flight number.", "via_link": false }, "schema": { "$ref": "#/components/schemas/AdvanceSubmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-submissions/{id}": { "get": { "operationId": "advanceSubmissions.get", "tags": ["Advancing"], "x-xos-table": "app.advance_submissions", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get an advance submission", "description": "A recipient's submission for one section. Returns one advance submission with its `ETag`. A advance submission the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance submission.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The advance submission.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_recipient_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_at": "2026-10-08T14:30:00Z", "body": "Party of 8 lands at 14:20.", "reviewed_at": "2026-10-08T14:30:00Z", "reviewed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "review_outcome": "Accepted", "return_reason": "Please add the flight number.", "via_link": false }, "schema": { "$ref": "#/components/schemas/AdvanceSubmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-submissions/{id}/review": { "post": { "operationId": "advanceSubmissions.review", "tags": ["Advancing"], "x-xos-table": "app.advance_submissions", "x-xos-capability": "advancing.submission.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Review an advance answer", "description": "Records the one review of an answer: Accepted, or Returned with a reason the recipient reads. The database stamps the reviewer and time and refuses the person who submitted it (sod_advance_submitter) or a second review (422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance submission.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "outcome": "Returned", "return_reason": "Please add the flight number." }, "schema": { "$ref": "#/components/schemas/AdvanceSubmissionReviewRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_recipient_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_at": "2026-10-08T14:30:00Z", "body": "Party of 8 lands at 14:20.", "reviewed_at": "2026-10-08T14:30:00Z", "reviewed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "review_outcome": "Accepted", "return_reason": "Please add the flight number.", "via_link": false }, "schema": { "$ref": "#/components/schemas/AdvanceSubmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-promotions": { "get": { "operationId": "advancePromotions.list", "tags": ["Advancing"], "x-xos-table": "app.advance_promotions", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List advance promotion rows", "description": "A submission promoted into project records, such as a requirement or a fulfillment. Returns a cursor page of advance promotion rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of advance promotion rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_submission_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AdvancePromotionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "advancePromotions.create", "tags": ["Advancing"], "x-xos-table": "app.advance_promotions", "x-xos-capability": "advancing.submission.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create an advance promotion", "description": "A submission promoted into project records, such as a requirement or a fulfillment. Creates an advance promotion. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "advance_submission_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AdvancePromotionCreate" } } } }, "responses": { "201": { "description": "The created advance promotion.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_submission_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AdvancePromotion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/advance-promotions/{id}": { "get": { "operationId": "advancePromotions.get", "tags": ["Advancing"], "x-xos-table": "app.advance_promotions", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get an advance promotion", "description": "A submission promoted into project records, such as a requirement or a fulfillment. Returns one advance promotion with its `ETag`. A advance promotion the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the advance promotion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the advance promotion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The advance promotion.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "advance_submission_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AdvancePromotion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/riders": { "get": { "operationId": "riders.list", "tags": ["Advancing"], "x-xos-table": "app.riders", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List rider rows", "description": "A technical or hospitality rider for an engagement. Returns a cursor page of rider rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of rider rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Technical Rider 2026", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RiderPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "riders.create", "tags": ["Advancing"], "x-xos-table": "app.riders", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create a rider", "description": "A technical or hospitality rider for an engagement. Creates a rider. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Technical Rider 2026", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RiderCreate" } } } }, "responses": { "201": { "description": "The created rider.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Technical Rider 2026", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Rider" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/riders/{id}": { "get": { "operationId": "riders.get", "tags": ["Advancing"], "x-xos-table": "app.riders", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get a rider", "description": "A technical or hospitality rider for an engagement. Returns one rider with its `ETag`. A rider the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rider.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The rider.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Technical Rider 2026", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Rider" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "riders.update", "tags": ["Advancing"], "x-xos-table": "app.riders", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Update a rider", "description": "A technical or hospitality rider for an engagement. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rider.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Technical Rider 2026", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RiderUpdate" } } } }, "responses": { "200": { "description": "The updated rider.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Technical Rider 2026", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Rider" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "riders.delete", "tags": ["Advancing"], "x-xos-table": "app.riders", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Delete a rider", "description": "A technical or hospitality rider for an engagement. Soft-deletes the rider: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rider.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rider.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The rider moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rider-lines": { "get": { "operationId": "riderLines.list", "tags": ["Advancing"], "x-xos-table": "app.rider_lines", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List rider line rows", "description": "A rider line, reconciled against capabilities. Returns a cursor page of rider line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of rider line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 2, "description": "Two wedge monitors per vocalist.", "element_id": "5000.02.01-NWL-001", "fulfilled_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RiderLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "riderLines.create", "tags": ["Advancing"], "x-xos-table": "app.rider_lines", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create a rider line", "description": "A rider line, reconciled against capabilities. Creates a rider line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "rider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 2, "description": "Two wedge monitors per vocalist.", "element_id": "5000.02.01-NWL-001", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RiderLineCreate" } } } }, "responses": { "201": { "description": "The created rider line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 2, "description": "Two wedge monitors per vocalist.", "element_id": "5000.02.01-NWL-001", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RiderLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rider-lines/{id}": { "get": { "operationId": "riderLines.get", "tags": ["Advancing"], "x-xos-table": "app.rider_lines", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get a rider line", "description": "A rider line, reconciled against capabilities. Returns one rider line with its `ETag`. A rider line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rider line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rider line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The rider line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 2, "description": "Two wedge monitors per vocalist.", "element_id": "5000.02.01-NWL-001", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RiderLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "riderLines.update", "tags": ["Advancing"], "x-xos-table": "app.rider_lines", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Update a rider line", "description": "A rider line, reconciled against capabilities. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rider line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rider line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "quantity": 2, "description": "Two wedge monitors per vocalist.", "element_id": "5000.02.01-NWL-001", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RiderLineUpdate" } } } }, "responses": { "200": { "description": "The updated rider line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 2, "description": "Two wedge monitors per vocalist.", "element_id": "5000.02.01-NWL-001", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RiderLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "riderLines.delete", "tags": ["Advancing"], "x-xos-table": "app.rider_lines", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Delete a rider line", "description": "A rider line, reconciled against capabilities. Soft-deletes the rider line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rider line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rider line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The rider line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fulfillments": { "get": { "operationId": "fulfillments.list", "tags": ["Hospitality"], "x-xos-table": "app.fulfillments", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List fulfillment rows", "description": "A lodging, catering, travel or amenity fulfillment. Returns a cursor page of fulfillment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of fulfillment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_kind": "Lodging", "title": "Headliner Hotel Block", "fulfillment_state": "Proposed", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_number": 3 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/FulfillmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "fulfillments.create", "tags": ["Hospitality"], "x-xos-table": "app.fulfillments", "x-xos-capability": "hospitality.fulfillment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Create a fulfillment", "description": "A lodging, catering, travel or amenity fulfillment. Creates a fulfillment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_kind": "Lodging", "title": "Headliner Hotel Block", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FulfillmentCreate" } } } }, "responses": { "201": { "description": "The created fulfillment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_kind": "Lodging", "title": "Headliner Hotel Block", "fulfillment_state": "Proposed", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_number": 3 }, "schema": { "$ref": "#/components/schemas/Fulfillment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fulfillments/{id}": { "get": { "operationId": "fulfillments.get", "tags": ["Hospitality"], "x-xos-table": "app.fulfillments", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Get a fulfillment", "description": "A lodging, catering, travel or amenity fulfillment. Returns one fulfillment with its `ETag`. A fulfillment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the fulfillment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The fulfillment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_kind": "Lodging", "title": "Headliner Hotel Block", "fulfillment_state": "Proposed", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_number": 3 }, "schema": { "$ref": "#/components/schemas/Fulfillment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "fulfillments.update", "tags": ["Hospitality"], "x-xos-table": "app.fulfillments", "x-xos-capability": "hospitality.fulfillment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Update a fulfillment", "description": "A lodging, catering, travel or amenity fulfillment. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the fulfillment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "fulfillment_kind": "Lodging", "title": "Headliner Hotel Block", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FulfillmentUpdate" } } } }, "responses": { "200": { "description": "The updated fulfillment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_kind": "Lodging", "title": "Headliner Hotel Block", "fulfillment_state": "Proposed", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_number": 3 }, "schema": { "$ref": "#/components/schemas/Fulfillment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "fulfillments.delete", "tags": ["Hospitality"], "x-xos-table": "app.fulfillments", "x-xos-capability": "hospitality.fulfillment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Delete a fulfillment", "description": "A lodging, catering, travel or amenity fulfillment. Soft-deletes the fulfillment: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the fulfillment.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The fulfillment moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fulfillments/{id}/transitions": { "post": { "operationId": "fulfillments.transition", "tags": ["Hospitality"], "x-xos-table": "app.fulfillments", "x-xos-capability": "hospitality.fulfillment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Transition the fulfillment state", "description": "Moves the fulfillment lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the fulfillment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Proposed", "to_state": "Active", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/FulfillmentTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_kind": "Lodging", "title": "Headliner Hotel Block", "fulfillment_state": "Proposed", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_number": 3 }, "schema": { "$ref": "#/components/schemas/Fulfillment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fulfillment-lines": { "get": { "operationId": "fulfillmentLines.list", "tags": ["Hospitality"], "x-xos-table": "app.fulfillment_lines", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List fulfillment line rows", "description": "A line of a fulfillment. Returns a cursor page of fulfillment line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of fulfillment line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "King room, 3 nights", "quantity": 4, "unit_price_minor": 32900, "currency_code": "USD", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/FulfillmentLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "fulfillmentLines.create", "tags": ["Hospitality"], "x-xos-table": "app.fulfillment_lines", "x-xos-capability": "hospitality.fulfillment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Create a fulfillment line", "description": "A line of a fulfillment. Creates a fulfillment line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "King room, 3 nights", "quantity": 4, "unit_price_minor": 32900, "currency_code": "USD", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FulfillmentLineCreate" } } } }, "responses": { "201": { "description": "The created fulfillment line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "King room, 3 nights", "quantity": 4, "unit_price_minor": 32900, "currency_code": "USD", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FulfillmentLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fulfillment-lines/{id}": { "get": { "operationId": "fulfillmentLines.get", "tags": ["Hospitality"], "x-xos-table": "app.fulfillment_lines", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Get a fulfillment line", "description": "A line of a fulfillment. Returns one fulfillment line with its `ETag`. A fulfillment line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the fulfillment line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The fulfillment line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "King room, 3 nights", "quantity": 4, "unit_price_minor": 32900, "currency_code": "USD", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FulfillmentLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "fulfillmentLines.update", "tags": ["Hospitality"], "x-xos-table": "app.fulfillment_lines", "x-xos-capability": "hospitality.fulfillment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Update a fulfillment line", "description": "A line of a fulfillment. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the fulfillment line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "King room, 3 nights", "quantity": 4, "unit_price_minor": 32900, "currency_code": "USD", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FulfillmentLineUpdate" } } } }, "responses": { "200": { "description": "The updated fulfillment line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "King room, 3 nights", "quantity": 4, "unit_price_minor": 32900, "currency_code": "USD", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FulfillmentLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "fulfillmentLines.delete", "tags": ["Hospitality"], "x-xos-table": "app.fulfillment_lines", "x-xos-capability": "hospitality.fulfillment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Delete a fulfillment line", "description": "A line of a fulfillment. Soft-deletes the fulfillment line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the fulfillment line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the fulfillment line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The fulfillment line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/beos": { "get": { "operationId": "beos.list", "tags": ["Hospitality"], "x-xos-table": "app.beos", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List BEO rows", "description": "A banquet event order. Returns a cursor page of BEO rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of BEO rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_at": "2026-10-08T14:30:00Z", "guest_count": 140, "beo_number": 4, "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BeoPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "beos.create", "tags": ["Hospitality"], "x-xos-table": "app.beos", "x-xos-capability": "hospitality.beo.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Create a BEO", "description": "A banquet event order. Creates a BEO. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_at": "2026-10-08T14:30:00Z", "guest_count": 140 }, "schema": { "$ref": "#/components/schemas/BeoCreate" } } } }, "responses": { "201": { "description": "The created BEO.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_at": "2026-10-08T14:30:00Z", "guest_count": 140, "beo_number": 4, "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Beo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/beos/{id}": { "get": { "operationId": "beos.get", "tags": ["Hospitality"], "x-xos-table": "app.beos", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Get a BEO", "description": "A banquet event order. Returns one BEO with its `ETag`. A BEO the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the beo.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the beo.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The BEO.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_at": "2026-10-08T14:30:00Z", "guest_count": 140, "beo_number": 4, "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Beo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "beos.update", "tags": ["Hospitality"], "x-xos-table": "app.beos", "x-xos-capability": "hospitality.beo.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Update a BEO", "description": "A banquet event order. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the beo.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the beo.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_at": "2026-10-08T14:30:00Z", "guest_count": 140 }, "schema": { "$ref": "#/components/schemas/BeoUpdate" } } } }, "responses": { "200": { "description": "The updated BEO.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "fulfillment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_at": "2026-10-08T14:30:00Z", "guest_count": 140, "beo_number": 4, "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Beo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "beos.delete", "tags": ["Hospitality"], "x-xos-table": "app.beos", "x-xos-capability": "hospitality.beo.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Delete a BEO", "description": "A banquet event order. Soft-deletes the BEO: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the beo.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the beo.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The BEO moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/beo-lines": { "get": { "operationId": "beoLines.list", "tags": ["Hospitality"], "x-xos-table": "app.beo_lines", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List BEO line rows", "description": "A line of a banquet event order. Returns a cursor page of BEO line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of BEO line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "beo_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Grilled vegetable wraps", "quantity": 140, "unit_price_minor": 1450, "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BeoLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "beoLines.create", "tags": ["Hospitality"], "x-xos-table": "app.beo_lines", "x-xos-capability": "hospitality.beo.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Create a BEO line", "description": "A line of a banquet event order. Creates a BEO line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "beo_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Grilled vegetable wraps", "quantity": 140, "unit_price_minor": 1450, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/BeoLineCreate" } } } }, "responses": { "201": { "description": "The created BEO line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "beo_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Grilled vegetable wraps", "quantity": 140, "unit_price_minor": 1450, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/BeoLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/beo-lines/{id}": { "get": { "operationId": "beoLines.get", "tags": ["Hospitality"], "x-xos-table": "app.beo_lines", "x-xos-capability": "hospitality.fulfillment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Get a BEO line", "description": "A line of a banquet event order. Returns one BEO line with its `ETag`. A BEO line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the beo line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the beo line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The BEO line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "beo_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Grilled vegetable wraps", "quantity": 140, "unit_price_minor": 1450, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/BeoLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "beoLines.update", "tags": ["Hospitality"], "x-xos-table": "app.beo_lines", "x-xos-capability": "hospitality.beo.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Update a BEO line", "description": "A line of a banquet event order. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the beo line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the beo line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Grilled vegetable wraps", "quantity": 140, "unit_price_minor": 1450, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/BeoLineUpdate" } } } }, "responses": { "200": { "description": "The updated BEO line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "beo_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Grilled vegetable wraps", "quantity": 140, "unit_price_minor": 1450, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/BeoLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "beoLines.delete", "tags": ["Hospitality"], "x-xos-table": "app.beo_lines", "x-xos-capability": "hospitality.beo.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["hospitality"] }], "summary": "Delete a BEO line", "description": "A line of a banquet event order. Soft-deletes the BEO line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the beo line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the beo line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The BEO line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-classes": { "get": { "operationId": "assetClasses.list", "tags": ["Assets"], "x-xos-table": "app.asset_classes", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List asset class rows", "description": "An asset class bound to a catalog element (class grain). Returns a cursor page of asset class rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of asset class rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Truss Section 10 ft", "element_id": "5000.02.02-XPMS-003" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AssetClassPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "assetClasses.create", "tags": ["Assets"], "x-xos-table": "app.asset_classes", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Create an asset class", "description": "An asset class bound to a catalog element (class grain). Creates an asset class. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Truss Section 10 ft", "element_id": "5000.02.02-XPMS-003" }, "schema": { "$ref": "#/components/schemas/AssetClassCreate" } } } }, "responses": { "201": { "description": "The created asset class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Truss Section 10 ft", "element_id": "5000.02.02-XPMS-003" }, "schema": { "$ref": "#/components/schemas/AssetClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-classes/{id}": { "get": { "operationId": "assetClasses.get", "tags": ["Assets"], "x-xos-table": "app.asset_classes", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Get an asset class", "description": "An asset class bound to a catalog element (class grain). Returns one asset class with its `ETag`. A asset class the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset class.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The asset class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Truss Section 10 ft", "element_id": "5000.02.02-XPMS-003" }, "schema": { "$ref": "#/components/schemas/AssetClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "assetClasses.update", "tags": ["Assets"], "x-xos-table": "app.asset_classes", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Update an asset class", "description": "An asset class bound to a catalog element (class grain). Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset class.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Truss Section 10 ft", "element_id": "5000.02.02-XPMS-003" }, "schema": { "$ref": "#/components/schemas/AssetClassUpdate" } } } }, "responses": { "200": { "description": "The updated asset class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Truss Section 10 ft", "element_id": "5000.02.02-XPMS-003" }, "schema": { "$ref": "#/components/schemas/AssetClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "assetClasses.delete", "tags": ["Assets"], "x-xos-table": "app.asset_classes", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Delete an asset class", "description": "An asset class bound to a catalog element (class grain). Soft-deletes the asset class: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset class.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The asset class moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-units": { "get": { "operationId": "assetUnits.list", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List asset unit rows", "description": "An individual asset tracked by serial or asset tag (unit grain), with a nine-value lifecycle. Returns a cursor page of asset unit rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of asset unit rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_tag": "NWL-TR-0042", "asset_state": "Available", "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AssetUnitPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "assetUnits.create", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Create an asset unit", "description": "An individual asset tracked by serial or asset tag (unit grain), with a nine-value lifecycle. Creates an asset unit. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_tag": "NWL-TR-0042", "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetUnitCreate" } } } }, "responses": { "201": { "description": "The created asset unit.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_tag": "NWL-TR-0042", "asset_state": "Available", "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetUnit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-units/{id}": { "get": { "operationId": "assetUnits.get", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Get an asset unit", "description": "An individual asset tracked by serial or asset tag (unit grain), with a nine-value lifecycle. Returns one asset unit with its `ETag`. A asset unit the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset unit.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The asset unit.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_tag": "NWL-TR-0042", "asset_state": "Available", "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetUnit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "assetUnits.update", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Update an asset unit", "description": "An individual asset tracked by serial or asset tag (unit grain), with a nine-value lifecycle. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset unit.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetUnitUpdate" } } } }, "responses": { "200": { "description": "The updated asset unit.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_tag": "NWL-TR-0042", "asset_state": "Available", "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetUnit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "assetUnits.delete", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Delete an asset unit", "description": "An individual asset tracked by serial or asset tag (unit grain), with a nine-value lifecycle. Soft-deletes the asset unit: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset unit.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The asset unit moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-units/{id}/transitions": { "post": { "operationId": "assetUnits.transition", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.write_off.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Transition the asset state", "description": "Moves the asset lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset unit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset unit.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Active", "to_state": "In Review", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/AssetTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_tag": "NWL-TR-0042", "asset_state": "Available", "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetUnit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-units/scan": { "post": { "operationId": "assetUnits.scan", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Resolve a scanned asset", "description": "Resolves a scanned barcode, QR or NFC payload to an asset unit. An unknown code returns a 422 `NO_ANSWER` refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "NWL-TR-0042", "symbology": "code128" }, "schema": { "$ref": "#/components/schemas/ScanRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_tag": "NWL-TR-0042", "asset_state": "Available", "condition_enum_id": "ENM-017", "home_venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetUnit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-units/scans": { "post": { "operationId": "assetUnits.applyScan", "tags": ["Assets"], "x-xos-table": "app.asset_units", "x-xos-capability": "assets.custody.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-rpc": "app.apply_asset_scan", "summary": "Apply a scan event", "description": "Applies one scanned custody move in one transaction (app.apply_asset_scan): resolves the code to a unit or lot, writes the custody entry or lot movement under the device's event id, and moves the unit's state. Replaying an event id returns `duplicate` and changes nothing. A unit someone else moved meanwhile is refused (422, asset_scan_state_conflict); a code no item carries is refused with NO_ANSWER. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e70", "code": "NWL-RAD-014", "action": "check-out", "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Stage left radio.", "quantity": 12 }, "schema": { "$ref": "#/components/schemas/AssetScanEvent" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "applied", "subject_kind": "unit", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ledger_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_state": "Available", "on_hand": 72 }, "schema": { "$ref": "#/components/schemas/AssetScanResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-lots": { "get": { "operationId": "assetLots.list", "tags": ["Assets"], "x-xos-table": "app.asset_lots", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List asset lot rows", "description": "A quantity of an asset class at a place (lot grain). Returns a cursor page of asset lot rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of asset lot rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 36, "on_hand": 34 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AssetLotPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "assetLots.create", "tags": ["Assets"], "x-xos-table": "app.asset_lots", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Create an asset lot", "description": "A quantity of an asset class at a place (lot grain). Creates an asset lot. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 36 }, "schema": { "$ref": "#/components/schemas/AssetLotCreate" } } } }, "responses": { "201": { "description": "The created asset lot.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 36, "on_hand": 34 }, "schema": { "$ref": "#/components/schemas/AssetLot" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-lots/{id}": { "get": { "operationId": "assetLots.get", "tags": ["Assets"], "x-xos-table": "app.asset_lots", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Get an asset lot", "description": "A quantity of an asset class at a place (lot grain). Returns one asset lot with its `ETag`. A asset lot the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset lot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset lot.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The asset lot.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 36, "on_hand": 34 }, "schema": { "$ref": "#/components/schemas/AssetLot" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "assetLots.update", "tags": ["Assets"], "x-xos-table": "app.asset_lots", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Update an asset lot", "description": "A quantity of an asset class at a place (lot grain). Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset lot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset lot.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetLotUpdate" } } } }, "responses": { "200": { "description": "The updated asset lot.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity": 36, "on_hand": 34 }, "schema": { "$ref": "#/components/schemas/AssetLot" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "assetLots.delete", "tags": ["Assets"], "x-xos-table": "app.asset_lots", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Delete an asset lot", "description": "A quantity of an asset class at a place (lot grain). Soft-deletes the asset lot: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset lot.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset lot.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The asset lot moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-identifiers": { "get": { "operationId": "assetIdentifiers.list", "tags": ["Assets"], "x-xos-table": "app.asset_identifiers", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List asset identifier rows", "description": "An external identifier recorded against an asset unit, such as a GTIN or an NFC tag. Returns a cursor page of asset identifier rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of asset identifier rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identifier_class": "gtin", "value": "00012345678905", "scheme": "serial" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AssetIdentifierPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "assetIdentifiers.create", "tags": ["Assets"], "x-xos-table": "app.asset_identifiers", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Create an asset identifier", "description": "An external identifier recorded against an asset unit, such as a GTIN or an NFC tag. Creates an asset identifier. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value": "00012345678905", "scheme": "serial" }, "schema": { "$ref": "#/components/schemas/AssetIdentifierCreate" } } } }, "responses": { "201": { "description": "The created asset identifier.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identifier_class": "gtin", "value": "00012345678905", "scheme": "serial" }, "schema": { "$ref": "#/components/schemas/AssetIdentifier" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-identifiers/{id}": { "get": { "operationId": "assetIdentifiers.get", "tags": ["Assets"], "x-xos-table": "app.asset_identifiers", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Get an asset identifier", "description": "An external identifier recorded against an asset unit, such as a GTIN or an NFC tag. Returns one asset identifier with its `ETag`. A asset identifier the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset identifier.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset identifier.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The asset identifier.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identifier_class": "gtin", "value": "00012345678905", "scheme": "serial" }, "schema": { "$ref": "#/components/schemas/AssetIdentifier" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "assetIdentifiers.delete", "tags": ["Assets"], "x-xos-table": "app.asset_identifiers", "x-xos-capability": "assets.asset.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Delete an asset identifier", "description": "An external identifier recorded against an asset unit, such as a GTIN or an NFC tag. Soft-deletes the asset identifier: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset identifier.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset identifier.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The asset identifier moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-custody": { "get": { "operationId": "assetCustodyEntries.list", "tags": ["Assets"], "x-xos-table": "app.asset_custody", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-order": { "by": ["id"], "numeric": false }, "summary": "List asset custody rows", "description": "An append-only custody ledger entry. Returns a cursor page of asset custody rows the caller may see. The default order is `id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of asset custody rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Issued for load-in." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AssetCustodyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "assetCustodyEntries.create", "tags": ["Assets"], "x-xos-table": "app.asset_custody", "x-xos-capability": "assets.custody.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Create an asset custody", "description": "An append-only custody ledger entry. Creates an asset custody. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Issued for load-in." }, "schema": { "$ref": "#/components/schemas/AssetCustodyCreate" } } } }, "responses": { "201": { "description": "The created asset custody.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Issued for load-in." }, "schema": { "$ref": "#/components/schemas/AssetCustody" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-custody/{id}": { "get": { "operationId": "assetCustodyEntries.get", "tags": ["Assets"], "x-xos-table": "app.asset_custody", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Get an asset custody", "description": "An append-only custody ledger entry. Returns one asset custody with its `ETag`. A asset custody the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset custody.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset custody.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The asset custody.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custodian_engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Issued for load-in." }, "schema": { "$ref": "#/components/schemas/AssetCustody" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-maintenance": { "get": { "operationId": "assetMaintenanceEvents.list", "tags": ["Assets"], "x-xos-table": "app.asset_maintenance", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List asset maintenance rows", "description": "A maintenance event for an asset unit. Returns a cursor page of asset maintenance rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of asset maintenance rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "performed_on": "2026-10-08", "description": "Replaced the spigots.", "cost_minor": 12000, "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AssetMaintenancePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "assetMaintenanceEvents.create", "tags": ["Assets"], "x-xos-table": "app.asset_maintenance", "x-xos-capability": "assets.maintenance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Create an asset maintenance", "description": "A maintenance event for an asset unit. Creates an asset maintenance. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "performed_on": "2026-10-08", "description": "Replaced the spigots.", "cost_minor": 12000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/AssetMaintenanceCreate" } } } }, "responses": { "201": { "description": "The created asset maintenance.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "performed_on": "2026-10-08", "description": "Replaced the spigots.", "cost_minor": 12000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/AssetMaintenance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-maintenance/{id}": { "get": { "operationId": "assetMaintenanceEvents.get", "tags": ["Assets"], "x-xos-table": "app.asset_maintenance", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Get an asset maintenance", "description": "A maintenance event for an asset unit. Returns one asset maintenance with its `ETag`. A asset maintenance the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset maintenance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset maintenance.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The asset maintenance.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "performed_on": "2026-10-08", "description": "Replaced the spigots.", "cost_minor": 12000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/AssetMaintenance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "assetMaintenanceEvents.update", "tags": ["Assets"], "x-xos-table": "app.asset_maintenance", "x-xos-capability": "assets.maintenance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Update an asset maintenance", "description": "A maintenance event for an asset unit. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset maintenance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset maintenance.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "performed_on": "2026-10-08", "description": "Replaced the spigots.", "cost_minor": 12000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/AssetMaintenanceUpdate" } } } }, "responses": { "200": { "description": "The updated asset maintenance.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "performed_on": "2026-10-08", "description": "Replaced the spigots.", "cost_minor": 12000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/AssetMaintenance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "assetMaintenanceEvents.delete", "tags": ["Assets"], "x-xos-table": "app.asset_maintenance", "x-xos-capability": "assets.maintenance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Delete an asset maintenance", "description": "A maintenance event for an asset unit. Soft-deletes the asset maintenance: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset maintenance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset maintenance.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The asset maintenance moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-damage": { "get": { "operationId": "assetDamageReports.list", "tags": ["Assets"], "x-xos-table": "app.asset_damage", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List asset damage rows", "description": "A damage report for an asset unit. Returns a cursor page of asset damage rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of asset damage rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reported_at": "2026-10-08T14:30:00Z", "description": "Bent chord on one end.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "responsible_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AssetDamagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "assetDamageReports.create", "tags": ["Assets"], "x-xos-table": "app.asset_damage", "x-xos-capability": "assets.damage.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Create an asset damage", "description": "A damage report for an asset unit. Creates an asset damage. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reported_at": "2026-10-08T14:30:00Z", "description": "Bent chord on one end.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "responsible_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetDamageCreate" } } } }, "responses": { "201": { "description": "The created asset damage.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reported_at": "2026-10-08T14:30:00Z", "description": "Bent chord on one end.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "responsible_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetDamage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/asset-damage/{id}": { "get": { "operationId": "assetDamageReports.get", "tags": ["Assets"], "x-xos-table": "app.asset_damage", "x-xos-capability": "assets.asset.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Get an asset damage", "description": "A damage report for an asset unit. Returns one asset damage with its `ETag`. A asset damage the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset damage.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset damage.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The asset damage.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reported_at": "2026-10-08T14:30:00Z", "description": "Bent chord on one end.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "responsible_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetDamage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "assetDamageReports.update", "tags": ["Assets"], "x-xos-table": "app.asset_damage", "x-xos-capability": "assets.damage.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Update an asset damage", "description": "A damage report for an asset unit. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset damage.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset damage.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reported_at": "2026-10-08T14:30:00Z", "description": "Bent chord on one end.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "responsible_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetDamageUpdate" } } } }, "responses": { "200": { "description": "The updated asset damage.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "asset_unit_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reported_at": "2026-10-08T14:30:00Z", "description": "Bent chord on one end.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "responsible_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssetDamage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "assetDamageReports.delete", "tags": ["Assets"], "x-xos-table": "app.asset_damage", "x-xos-capability": "assets.damage.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["assets"] }], "summary": "Delete an asset damage", "description": "A damage report for an asset unit. Soft-deletes the asset damage: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the asset damage.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the asset damage.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The asset damage moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/role-assignments": { "get": { "operationId": "roleAssignments.list", "tags": ["People"], "x-xos-table": "app.role_assignments", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List role assignment rows", "description": "A canon workforce role staffed on a project, with its staffing ratio basis. Returns a cursor page of role assignment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of role assignment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "staffing_basis": "Declared", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "assignment_state": "Proposed" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RoleAssignmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "roleAssignments.create", "tags": ["People"], "x-xos-table": "app.role_assignments", "x-xos-capability": "people.role.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Create a role assignment", "description": "A canon workforce role staffed on a project, with its staffing ratio basis. Creates a role assignment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "staffing_basis": "Declared", "starts_on": "2026-10-08", "ends_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RoleAssignmentCreate" } } } }, "responses": { "201": { "description": "The created role assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "staffing_basis": "Declared", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "assignment_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/role-assignments/{id}": { "get": { "operationId": "roleAssignments.get", "tags": ["People"], "x-xos-table": "app.role_assignments", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get a role assignment", "description": "A canon workforce role staffed on a project, with its staffing ratio basis. Returns one role assignment with its `ETag`. A role assignment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The role assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "staffing_basis": "Declared", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "assignment_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "roleAssignments.update", "tags": ["People"], "x-xos-table": "app.role_assignments", "x-xos-capability": "people.role.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Update a role assignment", "description": "A canon workforce role staffed on a project, with its staffing ratio basis. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "staffing_basis": "Declared", "starts_on": "2026-10-08", "ends_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RoleAssignmentUpdate" } } } }, "responses": { "200": { "description": "The updated role assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "staffing_basis": "Declared", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "assignment_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/RoleAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "roleAssignments.delete", "tags": ["People"], "x-xos-table": "app.role_assignments", "x-xos-capability": "people.role.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Delete a role assignment", "description": "A canon workforce role staffed on a project, with its staffing ratio basis. Soft-deletes the role assignment: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role assignment.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The role assignment moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/requisitions": { "get": { "operationId": "requisitions.list", "tags": ["People"], "x-xos-table": "app.requisitions", "x-xos-capability": "people.requisition.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List requisition rows", "description": "A staffing or purchase requisition, approved before an opportunity is published. Returns a cursor page of requisition rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of requisition rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "requisition_state": "Proposed", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RequisitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "requisitions.create", "tags": ["People"], "x-xos-table": "app.requisitions", "x-xos-capability": "people.requisition.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Create a requisition", "description": "A staffing or purchase requisition, approved before an opportunity is published. Creates a requisition. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival." }, "schema": { "$ref": "#/components/schemas/RequisitionCreate" } } } }, "responses": { "201": { "description": "The created requisition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "requisition_state": "Proposed", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Requisition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/requisitions/{id}": { "get": { "operationId": "requisitions.get", "tags": ["People"], "x-xos-table": "app.requisitions", "x-xos-capability": "people.requisition.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get a requisition", "description": "A staffing or purchase requisition, approved before an opportunity is published. Returns one requisition with its `ETag`. A requisition the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requisition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requisition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The requisition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "requisition_state": "Proposed", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Requisition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "requisitions.update", "tags": ["People"], "x-xos-table": "app.requisitions", "x-xos-capability": "people.requisition.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Update a requisition", "description": "A staffing or purchase requisition, approved before an opportunity is published. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requisition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requisition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_code": "5000.50.01", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival." }, "schema": { "$ref": "#/components/schemas/RequisitionUpdate" } } } }, "responses": { "200": { "description": "The updated requisition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "requisition_state": "Proposed", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Requisition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "requisitions.delete", "tags": ["People"], "x-xos-table": "app.requisitions", "x-xos-capability": "people.requisition.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Delete a requisition", "description": "A staffing or purchase requisition, approved before an opportunity is published. Soft-deletes the requisition: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requisition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requisition.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The requisition moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/requisitions/{id}/transitions": { "post": { "operationId": "requisitions.transition", "tags": ["People"], "x-xos-table": "app.requisitions", "x-xos-capability": "people.requisition.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Transition the requisition state", "description": "Moves the requisition lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requisition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requisition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Approved", "to_state": "Filled", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/RequisitionTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "requisition_state": "Proposed", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Requisition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/requisitions/{id}/approve": { "post": { "operationId": "requisitions.approve", "tags": ["People"], "x-xos-table": "app.requisitions", "x-xos-capability": "people.requisition.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Approve a requisition", "description": "Records an approval decision on the requisition. Spend authority applies before an opportunity can be published. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the requisition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the requisition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "requisition_state": "Proposed", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "headcount": 12, "units_per_head": 10, "rate_minor": 4500, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "justification": "Second stage added for the festival.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Requisition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offers": { "get": { "operationId": "offers.list", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "people.profile.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List offer rows", "description": "Terms issued to a person or organization: accepted, countered or declined. Returns a cursor page of offer rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of offer rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OfferPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "offers.create", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "opportunities.offer.send", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an offer", "description": "Terms issued to a person or organization: accepted, countered or declined. Creates an offer. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/OfferCreate" } } } }, "responses": { "201": { "description": "The created offer.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offers/{id}": { "get": { "operationId": "offers.get", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "people.profile.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get an offer", "description": "Terms issued to a person or organization: accepted, countered or declined. Returns one offer with its `ETag`. A offer the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The offer.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "offers.update", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "opportunities.offer.send", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update an offer", "description": "Terms issued to a person or organization: accepted, countered or declined. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/OfferUpdate" } } } }, "responses": { "200": { "description": "The updated offer.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offers/{id}/accept": { "post": { "operationId": "offers.accept", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Accept an offer", "description": "Accepts the offer as the offered party and creates the engagement. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offers/{id}/decline": { "post": { "operationId": "offers.decline", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Decline an offer", "description": "The applicant side declines the organization's terms; the offer and the application become Declined. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "The dates conflict with another booking." }, "schema": { "$ref": "#/components/schemas/OfferDeclineRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offers/{id}/counter": { "post": { "operationId": "offers.counter", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Counter an offer", "description": "The applicant side counters the terms in force with its own, as a new version; the offer becomes Countered. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "rate_type": "Day", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/OfferCounterRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offers/{id}/withdraw": { "post": { "operationId": "offers.withdraw", "tags": ["People"], "x-xos-table": "app.offers", "x-xos-capability": "opportunities.offer.send", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Withdraw an offer", "description": "The organization withdraws an offer that is Sent or Countered; the application becomes Not Selected. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "The position was filled internally." }, "schema": { "$ref": "#/components/schemas/OfferWithdrawRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "expires_at": "2026-10-08T14:30:00Z", "offer_state": "Active", "responded_at": "2026-10-08T14:30:00Z", "version_number": 1, "proposed_side": "Organization", "amount_minor": 45000, "currency_code": "USD", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "message": "Rate includes the load-in day." }, "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/agreements": { "get": { "operationId": "agreements.list", "tags": ["People"], "x-xos-table": "app.agreements", "x-xos-capability": "people.profile.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List agreement rows", "description": "A contractor MSA, offer letter or crew agreement with token signing. A signed agreement cannot be revoked or unsigned. Returns a cursor page of agreement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of agreement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Crew Agreement 2026", "agreement_state": "Proposed", "signed_at": "2026-10-08T14:30:00Z", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token_expires_at": "2026-10-08T14:30:00Z", "signed_name": "Alex Rivera", "signed_body_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AgreementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "agreements.create", "tags": ["People"], "x-xos-table": "app.agreements", "x-xos-capability": "people.agreement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Create an agreement", "description": "A contractor MSA, offer letter or crew agreement with token signing. A signed agreement cannot be revoked or unsigned. Creates an agreement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Crew Agreement 2026", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AgreementCreate" } } } }, "responses": { "201": { "description": "The created agreement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Crew Agreement 2026", "agreement_state": "Proposed", "signed_at": "2026-10-08T14:30:00Z", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token_expires_at": "2026-10-08T14:30:00Z", "signed_name": "Alex Rivera", "signed_body_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/agreements/{id}": { "get": { "operationId": "agreements.get", "tags": ["People"], "x-xos-table": "app.agreements", "x-xos-capability": "people.profile.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get an agreement", "description": "A contractor MSA, offer letter or crew agreement with token signing. A signed agreement cannot be revoked or unsigned. Returns one agreement with its `ETag`. A agreement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the agreement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The agreement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Crew Agreement 2026", "agreement_state": "Proposed", "signed_at": "2026-10-08T14:30:00Z", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token_expires_at": "2026-10-08T14:30:00Z", "signed_name": "Alex Rivera", "signed_body_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "agreements.update", "tags": ["People"], "x-xos-table": "app.agreements", "x-xos-capability": "people.agreement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Update an agreement", "description": "A contractor MSA, offer letter or crew agreement with token signing. A signed agreement cannot be revoked or unsigned. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the agreement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Crew Agreement 2026", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AgreementUpdate" } } } }, "responses": { "200": { "description": "The updated agreement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Crew Agreement 2026", "agreement_state": "Proposed", "signed_at": "2026-10-08T14:30:00Z", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token_expires_at": "2026-10-08T14:30:00Z", "signed_name": "Alex Rivera", "signed_body_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/agreements/{id}/sign": { "post": { "operationId": "agreements.sign", "tags": ["People"], "x-xos-table": "app.agreements", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "sign_agreement", "summary": "Sign an agreement", "description": "The person the agreement names signs it with their typed name and the SHA-256 of the text they read. A signed agreement cannot be revoked or unsigned; a second signature, a changed text or an agreement that is not Sent is refused (422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the agreement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the agreement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "signed_name": "Alex Rivera", "body_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/AgreementSignRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Crew Agreement 2026", "agreement_state": "Proposed", "signed_at": "2026-10-08T14:30:00Z", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token_expires_at": "2026-10-08T14:30:00Z", "signed_name": "Alex Rivera", "signed_body_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shifts": { "get": { "operationId": "shifts.list", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.shift.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["starts_at"], "numeric": false }, "summary": "List shift rows", "description": "A staffed crew block. A shift cannot end before it starts. Returns a cursor page of shift rows the caller may see. The default order is `starts_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of shift rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Draft", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ShiftPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "shifts.create", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.shift.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a shift", "description": "A staffed crew block. A shift cannot end before it starts. Creates a shift. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/ShiftCreate" } } } }, "responses": { "201": { "description": "The created shift.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Draft", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/Shift" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shifts/{id}": { "get": { "operationId": "shifts.get", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.shift.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a shift", "description": "A staffed crew block. A shift cannot end before it starts. Returns one shift with its `ETag`. A shift the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The shift.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Draft", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/Shift" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "shifts.update", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.shift.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Update a shift", "description": "A staffed crew block. A shift cannot end before it starts. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/ShiftUpdate" } } } }, "responses": { "200": { "description": "The updated shift.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Draft", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/Shift" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "shifts.delete", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.shift.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Delete a shift", "description": "A staffed crew block. A shift cannot end before it starts. Soft-deletes the shift: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The shift moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shifts/{id}/transitions": { "post": { "operationId": "shifts.transition", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.shift.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Transition the shift state", "description": "Moves the shift lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Draft", "to_state": "Published", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/ShiftTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Draft", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/Shift" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shifts/{id}/accept": { "post": { "operationId": "shifts.accept", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.swap.request", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Accept a shift", "description": "Accepts the shift as the assigned person. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Draft", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/Shift" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shifts/{id}/claim": { "post": { "operationId": "shifts.claim", "tags": ["Crew"], "x-xos-table": "app.shifts", "x-xos-capability": "crew.shift.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Claim an open shift", "description": "Claims a published shift that has no one on it for the caller's own membership, under the project's claiming rule (scheduling.open_shift_claiming). Under first-come the caller gets the shift at once: it becomes Accepted and `claim` is null. Under approval, the default, or seniority the claim waits for a supervisor: the shift stays Published with no one on it and `claim` carries the waiting claim. A second claim on the shift while the caller's first one waits is refused (422, shift_claim_waiting). A held, unpublished or overlapping shift is refused (422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "engagement_id": null, "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "shift_state": "Published", "membership_id": null, "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "scheduled_break_minutes": 30, "claim": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "claim_state": "Requested" } }, "schema": { "$ref": "#/components/schemas/ShiftClaimResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shift-swaps": { "get": { "operationId": "shiftSwaps.list", "tags": ["Crew"], "x-xos-table": "app.shift_swaps", "x-xos-capability": "crew.shift.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List shift swap rows", "description": "A swap request. A crew member cannot approve their own swap. Returns a cursor page of shift swap rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of shift swap rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "swap_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ShiftSwapPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "shiftSwaps.create", "tags": ["Crew"], "x-xos-table": "app.shift_swaps", "x-xos-capability": "crew.swap.request", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a shift swap", "description": "A swap request. A crew member cannot approve their own swap. Creates a shift swap. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShiftSwapCreate" } } } }, "responses": { "201": { "description": "The created shift swap.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "swap_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShiftSwap" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shift-swaps/{id}": { "get": { "operationId": "shiftSwaps.get", "tags": ["Crew"], "x-xos-table": "app.shift_swaps", "x-xos-capability": "crew.shift.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a shift swap", "description": "A swap request. A crew member cannot approve their own swap. Returns one shift swap with its `ETag`. A shift swap the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift swap.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift swap.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The shift swap.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "swap_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShiftSwap" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shift-swaps/{id}/approve": { "post": { "operationId": "shiftSwaps.approve", "tags": ["Crew"], "x-xos-table": "app.shift_swaps", "x-xos-capability": "crew.swap.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Approve a shift swap", "description": "Records an approval decision on the shift swap. A crew member cannot approve their own swap. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift swap.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift swap.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "swap_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShiftSwap" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shift-swaps/{id}/decline": { "post": { "operationId": "shiftSwaps.decline", "tags": ["Crew"], "x-xos-table": "app.shift_swaps", "x-xos-capability": "crew.swap.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Decline a shift swap", "description": "Declines the swap request. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift swap.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift swap.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "swap_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShiftSwap" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shift-swaps/{id}/withdraw": { "post": { "operationId": "shiftSwaps.withdraw", "tags": ["Crew"], "x-xos-table": "app.shift_swaps", "x-xos-capability": "crew.swap.request", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Withdraw a shift swap", "description": "Withdraws the caller's own swap request. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shift swap.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shift swap.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "swap_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShiftSwap" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entries": { "get": { "operationId": "timeEntries.list", "tags": ["Crew"], "x-xos-table": "app.time_entries", "x-xos-capability": "crew.time_entry.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["clock_in"], "numeric": false }, "summary": "List time entry rows", "description": "A time entry. Entries cannot overlap for one person; forgotten clock-outs close at 16 hours and are flagged. Returns a cursor page of time entry rows the caller may see. The default order is `clock_in` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of time entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "clock_in": "2026-10-08T14:30:00Z", "clock_out": "2026-10-08T14:30:00Z", "break_minutes": 30, "kiosk_device_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "Web", "auto_closed_at": "2026-10-08T14:30:00Z", "needs_review": false, "meal_out_at": "2026-10-08T14:30:00Z", "meal_in_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TimeEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entries/{id}": { "get": { "operationId": "timeEntries.get", "tags": ["Crew"], "x-xos-table": "app.time_entries", "x-xos-capability": "crew.time_entry.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a time entry", "description": "A time entry. Entries cannot overlap for one person; forgotten clock-outs close at 16 hours and are flagged. Returns one time entry with its `ETag`. A time entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The time entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "clock_in": "2026-10-08T14:30:00Z", "clock_out": "2026-10-08T14:30:00Z", "break_minutes": 30, "kiosk_device_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "Web", "auto_closed_at": "2026-10-08T14:30:00Z", "needs_review": false, "meal_out_at": "2026-10-08T14:30:00Z", "meal_in_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TimeEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entries/clock-in": { "post": { "operationId": "timeEntries.clockIn", "tags": ["Crew"], "x-xos-table": "app.time_entries", "x-xos-capability": "crew.time_entry.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Clock in", "description": "Opens a time entry inside the shift geofence. Protects against double clock-in across devices; an overlapping entry is refused. Compass replays queued punches with the same Idempotency-Key. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "punch_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_time": "2026-10-08T14:30:00Z", "monotonic_offset_ms": 0, "latitude": 25.7617, "longitude": -80.1918, "accuracy_m": 12, "geofence_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TimeEntryClockInRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "clock_in": "2026-10-08T14:30:00Z", "clock_out": "2026-10-08T14:30:00Z", "break_minutes": 30, "kiosk_device_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "Web", "auto_closed_at": "2026-10-08T14:30:00Z", "needs_review": false, "meal_out_at": "2026-10-08T14:30:00Z", "meal_in_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TimeEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entries/{id}/clock-out": { "post": { "operationId": "timeEntries.clockOut", "tags": ["Crew"], "x-xos-table": "app.time_entries", "x-xos-capability": "crew.time_entry.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Clock out", "description": "Closes the open time entry. Forgotten clock-outs close automatically at 16 hours and are flagged. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "clock_in": "2026-10-08T14:30:00Z", "clock_out": "2026-10-08T14:30:00Z", "break_minutes": 30, "kiosk_device_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "Web", "auto_closed_at": "2026-10-08T14:30:00Z", "needs_review": false, "meal_out_at": "2026-10-08T14:30:00Z", "meal_in_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TimeEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entry-corrections": { "get": { "operationId": "timeEntryCorrections.list", "tags": ["Crew"], "x-xos-table": "app.time_entry_corrections", "x-xos-capability": "crew.time_entry.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List time entry correction rows", "description": "A requested correction to a time entry. Returns a cursor page of time entry correction rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of time entry correction rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Forgot to clock out at wrap.", "correction_state": "Proposed", "proposed_clock_in": "2026-10-08T14:30:00Z", "proposed_clock_out": "2026-10-08T14:30:00Z", "proposed_break_minutes": 30, "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TimeEntryCorrectionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "timeEntryCorrections.create", "tags": ["Crew"], "x-xos-table": "app.time_entry_corrections", "x-xos-capability": "crew.time_entry.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a time entry correction", "description": "A requested correction to a time entry. Creates a time entry correction. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "time_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Forgot to clock out at wrap.", "proposed_clock_in": "2026-10-08T14:30:00Z", "proposed_clock_out": "2026-10-08T14:30:00Z", "proposed_break_minutes": 30 }, "schema": { "$ref": "#/components/schemas/TimeEntryCorrectionCreate" } } } }, "responses": { "201": { "description": "The created time entry correction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Forgot to clock out at wrap.", "correction_state": "Proposed", "proposed_clock_in": "2026-10-08T14:30:00Z", "proposed_clock_out": "2026-10-08T14:30:00Z", "proposed_break_minutes": 30, "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TimeEntryCorrection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entry-corrections/{id}": { "get": { "operationId": "timeEntryCorrections.get", "tags": ["Crew"], "x-xos-table": "app.time_entry_corrections", "x-xos-capability": "crew.time_entry.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a time entry correction", "description": "A requested correction to a time entry. Returns one time entry correction with its `ETag`. A time entry correction the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time entry correction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time entry correction.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The time entry correction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Forgot to clock out at wrap.", "correction_state": "Proposed", "proposed_clock_in": "2026-10-08T14:30:00Z", "proposed_clock_out": "2026-10-08T14:30:00Z", "proposed_break_minutes": 30, "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TimeEntryCorrection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entry-corrections/{id}/approve": { "post": { "operationId": "timeEntryCorrections.approve", "tags": ["Crew"], "x-xos-table": "app.time_entry_corrections", "x-xos-capability": "crew.timesheet.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Approve a time entry correction", "description": "Records an approval decision on the time entry correction. The submitter cannot approve their own correction. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time entry correction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time entry correction.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Forgot to clock out at wrap.", "correction_state": "Proposed", "proposed_clock_in": "2026-10-08T14:30:00Z", "proposed_clock_out": "2026-10-08T14:30:00Z", "proposed_break_minutes": 30, "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TimeEntryCorrection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entry-audit": { "get": { "operationId": "timeEntryAuditEntries.list", "tags": ["Crew"], "x-xos-table": "app.time_entry_audit", "x-xos-capability": "crew.time_entry.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List time entry audit rows", "description": "An append-only audit row for a time entry change. Returns a cursor page of time entry audit rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of time entry audit rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "old_values": { "type": "doc" }, "new_values": { "type": "doc" } } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TimeEntryAuditPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-entry-audit/{id}": { "get": { "operationId": "timeEntryAuditEntries.get", "tags": ["Crew"], "x-xos-table": "app.time_entry_audit", "x-xos-capability": "crew.time_entry.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a time entry audit", "description": "An append-only audit row for a time entry change. Returns one time entry audit with its `ETag`. A time entry audit the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time entry audit.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time entry audit.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The time entry audit.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "old_values": { "type": "doc" }, "new_values": { "type": "doc" } }, "schema": { "$ref": "#/components/schemas/TimeEntryAudit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/timesheets": { "get": { "operationId": "timesheets.list", "tags": ["Crew"], "x-xos-table": "app.timesheets", "x-xos-capability": "crew.timesheet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List timesheet rows", "description": "A timesheet for one person and pay period. An approval is voided when its hours change. Returns a cursor page of timesheet rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of timesheet rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "timesheet_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "period_end": "2026-10-08", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TimesheetPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "timesheets.create", "tags": ["Crew"], "x-xos-table": "app.timesheets", "x-xos-capability": "crew.timesheet.submit", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a timesheet", "description": "A timesheet for one person and pay period. An approval is voided when its hours change. Creates a timesheet. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "period_end": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/TimesheetCreate" } } } }, "responses": { "201": { "description": "The created timesheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "timesheet_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "period_end": "2026-10-08", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Timesheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/timesheets/{id}": { "get": { "operationId": "timesheets.get", "tags": ["Crew"], "x-xos-table": "app.timesheets", "x-xos-capability": "crew.timesheet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a timesheet", "description": "A timesheet for one person and pay period. An approval is voided when its hours change. Returns one timesheet with its `ETag`. A timesheet the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the timesheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the timesheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The timesheet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "timesheet_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "period_end": "2026-10-08", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Timesheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/timesheets/{id}/submit": { "post": { "operationId": "timesheets.submit", "tags": ["Crew"], "x-xos-table": "app.timesheets", "x-xos-capability": "crew.timesheet.submit", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Submit a timesheet", "description": "Submits the timesheet for approval. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the timesheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the timesheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "timesheet_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "period_end": "2026-10-08", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Timesheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/timesheets/{id}/approve": { "post": { "operationId": "timesheets.approve", "tags": ["Crew"], "x-xos-table": "app.timesheets", "x-xos-capability": "crew.timesheet.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Approve a timesheet", "description": "Records an approval decision on the timesheet. The submitter cannot approve it, and an approval is voided when its hours change. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the timesheet.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the timesheet.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "timesheet_state": "Proposed", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "period_end": "2026-10-08", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Timesheet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/timesheet-approvals": { "get": { "operationId": "timesheetApprovals.list", "tags": ["Crew"], "x-xos-table": "app.timesheet_approvals", "x-xos-capability": "crew.timesheet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List timesheet approval rows", "description": "An approval decision on a timesheet. The submitter cannot approve it. Returns a cursor page of timesheet approval rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of timesheet approval rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "timesheet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved_minutes": 2490, "voided_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TimesheetApprovalPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/timesheet-approvals/{id}": { "get": { "operationId": "timesheetApprovals.get", "tags": ["Crew"], "x-xos-table": "app.timesheet_approvals", "x-xos-capability": "crew.timesheet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a timesheet approval", "description": "An approval decision on a timesheet. The submitter cannot approve it. Returns one timesheet approval with its `ETag`. A timesheet approval the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the timesheet approval.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the timesheet approval.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The timesheet approval.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "timesheet_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved_minutes": 2490, "voided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TimesheetApproval" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/kiosk-devices": { "get": { "operationId": "kioskDevices.list", "tags": ["Crew"], "x-xos-table": "app.kiosk_devices", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List kiosk device rows", "description": "A shared device in kiosk mode. Worker PINs are stored hashed and never returned. Returns a cursor page of kiosk device rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of kiosk device rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate A Kiosk", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_key": "xkio_9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b", "last_seen_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/KioskDevicePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "kioskDevices.create", "tags": ["Crew"], "x-xos-table": "app.kiosk_devices", "x-xos-capability": "org.time_attendance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a kiosk device", "description": "A shared device in kiosk mode. Worker PINs are stored hashed and never returned. Creates a kiosk device. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Gate A Kiosk", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/KioskDeviceCreate" } } } }, "responses": { "201": { "description": "The created kiosk device.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate A Kiosk", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_key": "xkio_9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b", "last_seen_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/KioskDevice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/kiosk-devices/{id}": { "get": { "operationId": "kioskDevices.get", "tags": ["Crew"], "x-xos-table": "app.kiosk_devices", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a kiosk device", "description": "A shared device in kiosk mode. Worker PINs are stored hashed and never returned. Returns one kiosk device with its `ETag`. A kiosk device the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the kiosk device.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the kiosk device.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The kiosk device.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate A Kiosk", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_key": "xkio_9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b", "last_seen_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/KioskDevice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "kioskDevices.update", "tags": ["Crew"], "x-xos-table": "app.kiosk_devices", "x-xos-capability": "org.time_attendance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a kiosk device", "description": "A shared device in kiosk mode. Worker PINs are stored hashed and never returned. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the kiosk device.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the kiosk device.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Gate A Kiosk", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/KioskDeviceUpdate" } } } }, "responses": { "200": { "description": "The updated kiosk device.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate A Kiosk", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_key": "xkio_9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b", "last_seen_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/KioskDevice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "kioskDevices.delete", "tags": ["Crew"], "x-xos-table": "app.kiosk_devices", "x-xos-capability": "org.time_attendance.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a kiosk device", "description": "A shared device in kiosk mode. Worker PINs are stored hashed and never returned. Soft-deletes the kiosk device: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the kiosk device.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the kiosk device.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The kiosk device moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rate-cards": { "get": { "operationId": "rateCards.list", "tags": ["Crew"], "x-xos-table": "app.rate_cards", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List rate card rows", "description": "A labor rate card. Returns a cursor page of rate card rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of rate card rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Local Stagehand Rates 2026", "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RateCardPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "rateCards.create", "tags": ["Crew"], "x-xos-table": "app.rate_cards", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a rate card", "description": "A labor rate card. Creates a rate card. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Local Stagehand Rates 2026", "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RateCardCreate" } } } }, "responses": { "201": { "description": "The created rate card.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Local Stagehand Rates 2026", "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RateCard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rate-cards/{id}": { "get": { "operationId": "rateCards.get", "tags": ["Crew"], "x-xos-table": "app.rate_cards", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a rate card", "description": "A labor rate card. Returns one rate card with its `ETag`. A rate card the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rate card.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rate card.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The rate card.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Local Stagehand Rates 2026", "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RateCard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "rateCards.update", "tags": ["Crew"], "x-xos-table": "app.rate_cards", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Update a rate card", "description": "A labor rate card. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rate card.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rate card.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Local Stagehand Rates 2026", "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RateCardUpdate" } } } }, "responses": { "200": { "description": "The updated rate card.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Local Stagehand Rates 2026", "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RateCard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "rateCards.delete", "tags": ["Crew"], "x-xos-table": "app.rate_cards", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Delete a rate card", "description": "A labor rate card. Soft-deletes the rate card: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rate card.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rate card.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The rate card moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rate-card-lines": { "get": { "operationId": "rateCardLines.list", "tags": ["Crew"], "x-xos-table": "app.rate_card_lines", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List rate card line rows", "description": "A rate card line by role. Returns a cursor page of rate card line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of rate card line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_card_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 4500, "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "overtime_rule_id": "OTR-001", "canon_rate_card_id": "LRC-001" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RateCardLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "rateCardLines.create", "tags": ["Crew"], "x-xos-table": "app.rate_card_lines", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a rate card line", "description": "A rate card line by role. Creates a rate card line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "rate_card_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 4500, "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "overtime_rule_id": "OTR-001", "canon_rate_card_id": "LRC-001" }, "schema": { "$ref": "#/components/schemas/RateCardLineCreate" } } } }, "responses": { "201": { "description": "The created rate card line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_card_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 4500, "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "overtime_rule_id": "OTR-001", "canon_rate_card_id": "LRC-001" }, "schema": { "$ref": "#/components/schemas/RateCardLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rate-card-lines/{id}": { "get": { "operationId": "rateCardLines.get", "tags": ["Crew"], "x-xos-table": "app.rate_card_lines", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a rate card line", "description": "A rate card line by role. Returns one rate card line with its `ETag`. A rate card line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rate card line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rate card line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The rate card line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_card_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 4500, "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "overtime_rule_id": "OTR-001", "canon_rate_card_id": "LRC-001" }, "schema": { "$ref": "#/components/schemas/RateCardLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "rateCardLines.update", "tags": ["Crew"], "x-xos-table": "app.rate_card_lines", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Update a rate card line", "description": "A rate card line by role. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rate card line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rate card line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_code": "5000.50.01", "rate_minor": 4500, "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "overtime_rule_id": "OTR-001", "canon_rate_card_id": "LRC-001" }, "schema": { "$ref": "#/components/schemas/RateCardLineUpdate" } } } }, "responses": { "200": { "description": "The updated rate card line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_card_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 4500, "worker_classification": "EMPLOYEE", "pay_basis": "Hourly", "arrangement": "Per Engagement", "overtime_rule_id": "OTR-001", "canon_rate_card_id": "LRC-001" }, "schema": { "$ref": "#/components/schemas/RateCardLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "rateCardLines.delete", "tags": ["Crew"], "x-xos-table": "app.rate_card_lines", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Delete a rate card line", "description": "A rate card line by role. Soft-deletes the rate card line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rate card line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rate card line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The rate card line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pay-rates": { "get": { "operationId": "payRates.list", "tags": ["Crew"], "x-xos-table": "app.pay_rates", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["effective_from"], "numeric": false }, "summary": "List pay rate rows", "description": "An append-only pay rate ledger entry for a person. Restricted. Returns a cursor page of pay rate rows the caller may see. The default order is `effective_from` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of pay rate rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 5200, "effective_from": "2026-10-08", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PayRatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "payRates.create", "tags": ["Crew"], "x-xos-table": "app.pay_rates", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a pay rate", "description": "An append-only pay rate ledger entry for a person. Restricted. Creates a pay rate. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_code": "5000.50.01", "rate_minor": 5200, "effective_from": "2026-10-08", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayRateCreate" } } } }, "responses": { "201": { "description": "The created pay rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 5200, "effective_from": "2026-10-08", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pay-rates/{id}": { "get": { "operationId": "payRates.get", "tags": ["Crew"], "x-xos-table": "app.pay_rates", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a pay rate", "description": "An append-only pay rate ledger entry for a person. Restricted. Returns one pay rate with its `ETag`. A pay rate the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the pay rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the pay rate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The pay rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_code": "5000.50.01", "rate_minor": 5200, "effective_from": "2026-10-08", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/overtime-rules": { "get": { "operationId": "overtimeRules.list", "tags": ["Crew"], "x-xos-table": "xpms.wage_hour_rule", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["jurisdiction_id"], "numeric": false }, "summary": "List overtime rule rows", "description": "A jurisdiction's wage and hour rule from canon: daily and weekly overtime thresholds and minimum multipliers. A lower jurisdiction inherits its parent's rule. Returns a cursor page of overtime rule rows the caller may see. The default order is `jurisdiction_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of overtime rule rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "jurisdiction_id": "US-FL", "source": "Fair Labor Standards Act, 29 U.S.C. 207", "weekly_ot_after_hours": 40, "daily_ot_after_hours": 8, "daily_dt_after_hours": 12, "min_ot_multiplier": 1.5, "min_dt_multiplier": 2 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OvertimeRulePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/overtime-rules/{jurisdiction_id}": { "get": { "operationId": "overtimeRules.get", "tags": ["Crew"], "x-xos-table": "xpms.wage_hour_rule", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get an overtime rule", "description": "A jurisdiction's wage and hour rule from canon: daily and weekly overtime thresholds and minimum multipliers. A lower jurisdiction inherits its parent's rule. Returns one overtime rule with its `ETag`. A overtime rule the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/JurisdictionId" }, "required": true, "description": "Jurisdiction identifier from `xpms.dim_jurisdiction`. An unpopulated jurisdiction returns no answer.", "name": "jurisdiction_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The overtime rule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "jurisdiction_id": "US-FL", "source": "Fair Labor Standards Act, 29 U.S.C. 207", "weekly_ot_after_hours": 40, "daily_ot_after_hours": 8, "daily_dt_after_hours": 12, "min_ot_multiplier": 1.5, "min_dt_multiplier": 2 }, "schema": { "$ref": "#/components/schemas/OvertimeRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/union-local-rates": { "get": { "operationId": "unionLocalRates.list", "tags": ["Crew"], "x-xos-table": "app.union_local_rates", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List union local rate rows", "description": "A union local's scale rate for a role. Returns a cursor page of union local rate rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of union local rate rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "union_local": "Local 500", "role_code": "5000.50.01", "rate_minor": 5600, "currency_code": "USD", "effective_from": "2026-10-08", "fringe_minor": 1200, "effective_to": "2026-10-08" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/UnionLocalRatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "unionLocalRates.create", "tags": ["Crew"], "x-xos-table": "app.union_local_rates", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create an union local rate", "description": "A union local's scale rate for a role. Creates an union local rate. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "union_local": "Local 500", "role_code": "5000.50.01", "rate_minor": 5600, "currency_code": "USD", "effective_from": "2026-10-08", "fringe_minor": 1200, "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/UnionLocalRateCreate" } } } }, "responses": { "201": { "description": "The created union local rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "union_local": "Local 500", "role_code": "5000.50.01", "rate_minor": 5600, "currency_code": "USD", "effective_from": "2026-10-08", "fringe_minor": 1200, "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/UnionLocalRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/union-local-rates/{id}": { "get": { "operationId": "unionLocalRates.get", "tags": ["Crew"], "x-xos-table": "app.union_local_rates", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get an union local rate", "description": "A union local's scale rate for a role. Returns one union local rate with its `ETag`. A union local rate the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the union local rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the union local rate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The union local rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "union_local": "Local 500", "role_code": "5000.50.01", "rate_minor": 5600, "currency_code": "USD", "effective_from": "2026-10-08", "fringe_minor": 1200, "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/UnionLocalRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "unionLocalRates.update", "tags": ["Crew"], "x-xos-table": "app.union_local_rates", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Update an union local rate", "description": "A union local's scale rate for a role. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the union local rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the union local rate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "union_local": "Local 500", "role_code": "5000.50.01", "rate_minor": 5600, "currency_code": "USD", "effective_from": "2026-10-08", "fringe_minor": 1200, "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/UnionLocalRateUpdate" } } } }, "responses": { "200": { "description": "The updated union local rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "union_local": "Local 500", "role_code": "5000.50.01", "rate_minor": 5600, "currency_code": "USD", "effective_from": "2026-10-08", "fringe_minor": 1200, "effective_to": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/UnionLocalRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "unionLocalRates.delete", "tags": ["Crew"], "x-xos-table": "app.union_local_rates", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Delete an union local rate", "description": "A union local's scale rate for a role. Soft-deletes the union local rate: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the union local rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the union local rate.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The union local rate moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wage-determinations": { "get": { "operationId": "wageDeterminations.list", "tags": ["Crew"], "x-xos-table": "app.wage_determinations", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List wage determination rows", "description": "A prevailing wage determination by jurisdiction. Returns a cursor page of wage determination rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of wage determination rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "role_code": "5000.50.01", "minimum_rate_minor": 4800, "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08", "source": "FL20260001" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WageDeterminationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "wageDeterminations.create", "tags": ["Crew"], "x-xos-table": "app.wage_determinations", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a wage determination", "description": "A prevailing wage determination by jurisdiction. Creates a wage determination. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "jurisdiction_id": "US-FL", "role_code": "5000.50.01", "minimum_rate_minor": 4800, "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08", "source": "FL20260001" }, "schema": { "$ref": "#/components/schemas/WageDeterminationCreate" } } } }, "responses": { "201": { "description": "The created wage determination.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "role_code": "5000.50.01", "minimum_rate_minor": 4800, "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08", "source": "FL20260001" }, "schema": { "$ref": "#/components/schemas/WageDetermination" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wage-determinations/{id}": { "get": { "operationId": "wageDeterminations.get", "tags": ["Crew"], "x-xos-table": "app.wage_determinations", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a wage determination", "description": "A prevailing wage determination by jurisdiction. Returns one wage determination with its `ETag`. A wage determination the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the wage determination.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the wage determination.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The wage determination.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "role_code": "5000.50.01", "minimum_rate_minor": 4800, "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08", "source": "FL20260001" }, "schema": { "$ref": "#/components/schemas/WageDetermination" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "wageDeterminations.update", "tags": ["Crew"], "x-xos-table": "app.wage_determinations", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Update a wage determination", "description": "A prevailing wage determination by jurisdiction. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the wage determination.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the wage determination.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "jurisdiction_id": "US-FL", "role_code": "5000.50.01", "minimum_rate_minor": 4800, "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08", "source": "FL20260001" }, "schema": { "$ref": "#/components/schemas/WageDeterminationUpdate" } } } }, "responses": { "200": { "description": "The updated wage determination.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "role_code": "5000.50.01", "minimum_rate_minor": 4800, "currency_code": "USD", "effective_from": "2026-10-08", "effective_to": "2026-10-08", "source": "FL20260001" }, "schema": { "$ref": "#/components/schemas/WageDetermination" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "wageDeterminations.delete", "tags": ["Crew"], "x-xos-table": "app.wage_determinations", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Delete a wage determination", "description": "A prevailing wage determination by jurisdiction. Soft-deletes the wage determination: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the wage determination.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the wage determination.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The wage determination moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pay-periods": { "get": { "operationId": "payPeriods.list", "tags": ["Crew"], "x-xos-table": "app.pay_periods", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List pay period rows", "description": "A pay period. A posted pay period cannot reopen. Returns a cursor page of pay period rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of pay period rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_period_state": "Open" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PayPeriodPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "payPeriods.create", "tags": ["Crew"], "x-xos-table": "app.pay_periods", "x-xos-capability": "crew.pay_period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a pay period", "description": "A pay period. A posted pay period cannot reopen. Creates a pay period. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "starts_on": "2026-10-08", "ends_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/PayPeriodCreate" } } } }, "responses": { "201": { "description": "The created pay period.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_period_state": "Open" }, "schema": { "$ref": "#/components/schemas/PayPeriod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pay-periods/{id}": { "get": { "operationId": "payPeriods.get", "tags": ["Crew"], "x-xos-table": "app.pay_periods", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a pay period", "description": "A pay period. A posted pay period cannot reopen. Returns one pay period with its `ETag`. A pay period the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the pay period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the pay period.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The pay period.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_period_state": "Open" }, "schema": { "$ref": "#/components/schemas/PayPeriod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "payPeriods.update", "tags": ["Crew"], "x-xos-table": "app.pay_periods", "x-xos-capability": "crew.pay_period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Update a pay period", "description": "A pay period. A posted pay period cannot reopen. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the pay period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the pay period.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "starts_on": "2026-10-08", "ends_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/PayPeriodUpdate" } } } }, "responses": { "200": { "description": "The updated pay period.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_period_state": "Open" }, "schema": { "$ref": "#/components/schemas/PayPeriod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pay-periods/{id}/transitions": { "post": { "operationId": "payPeriods.transition", "tags": ["Crew"], "x-xos-table": "app.pay_periods", "x-xos-capability": "crew.pay_period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Transition the pay period state", "description": "Moves the pay period lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the pay period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the pay period.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Open", "to_state": "Closed", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/PayPeriodTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_period_state": "Open" }, "schema": { "$ref": "#/components/schemas/PayPeriod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-runs": { "get": { "operationId": "payrollRuns.list", "tags": ["Crew"], "x-xos-table": "app.payroll_runs", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List payroll run rows", "description": "A payroll run. It cannot jump from Draft to Accepted. Returns a cursor page of payroll run rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of payroll run rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pay_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_state": "Draft", "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PayrollRunPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "payrollRuns.create", "tags": ["Crew"], "x-xos-table": "app.payroll_runs", "x-xos-capability": "crew.pay_period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a payroll run", "description": "A payroll run. It cannot jump from Draft to Accepted. Creates a payroll run. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "pay_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayrollRunCreate" } } } }, "responses": { "201": { "description": "The created payroll run.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pay_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_state": "Draft", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayrollRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-runs/{id}": { "get": { "operationId": "payrollRuns.get", "tags": ["Crew"], "x-xos-table": "app.payroll_runs", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a payroll run", "description": "A payroll run. It cannot jump from Draft to Accepted. Returns one payroll run with its `ETag`. A payroll run the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payroll run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The payroll run.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pay_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_state": "Draft", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayrollRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-runs/{id}/transitions": { "post": { "operationId": "payrollRuns.transition", "tags": ["Crew"], "x-xos-table": "app.payroll_runs", "x-xos-capability": "crew.pay_period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Transition the payroll run state", "description": "Moves the payroll run lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payroll run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Exported", "to_state": "Accepted", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/PayrollRunTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pay_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_state": "Draft", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayrollRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-runs/{id}/calculate": { "post": { "operationId": "payrollRuns.calculate", "tags": ["Crew"], "x-xos-table": "app.payroll_runs", "x-xos-capability": "crew.pay_period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Calculate a payroll run", "description": "Replaces the run's lines from the approved member timesheets of its pay period, splitting overtime by the canon wage and hour rule of each project's jurisdiction; the run becomes Calculated. A missing earning code, rate or rule is refused (422) and names it. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payroll run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pay_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_state": "Draft", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayrollRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-runs/{id}/approve": { "post": { "operationId": "payrollRuns.approve", "tags": ["Crew"], "x-xos-table": "app.payroll_runs", "x-xos-capability": "crew.pay_period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Approve a payroll run", "description": "Records an approval on a Calculated run under spend authority for Payroll Run, never by the run's creator; the run becomes Approved once fully approved. A refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payroll run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payroll run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pay_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_state": "Draft", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PayrollRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-lines": { "get": { "operationId": "payrollLines.list", "tags": ["Crew"], "x-xos-table": "app.payroll_line_amounts", "x-xos-capability": "data.restricted.read.payroll", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["id"], "numeric": false }, "summary": "List payroll line rows", "description": "A payroll line, derived from approved timesheets. Returns a cursor page of payroll line rows the caller may see. The default order is `id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of payroll line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "earning_code_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 8, "amount_minor": 41600, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_minor": 5200, "role_code": "5000.50.01", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PayrollLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-lines/{id}": { "get": { "operationId": "payrollLines.get", "tags": ["Crew"], "x-xos-table": "app.payroll_line_amounts", "x-xos-capability": "data.restricted.read.payroll", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get a payroll line", "description": "A payroll line, derived from approved timesheets. Returns one payroll line with its `ETag`. A payroll line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payroll line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payroll line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The payroll line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "earning_code_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 8, "amount_minor": 41600, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_minor": 5200, "role_code": "5000.50.01", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PayrollLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-exports": { "get": { "operationId": "payrollExports.list", "tags": ["Crew"], "x-xos-table": "app.payroll_exports", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List payroll export rows", "description": "A payroll export file for a payroll provider. Returns a cursor page of payroll export rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of payroll export rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "payroll_csv", "file_uri": "payroll-exports/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f.csv", "checksum_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PayrollExportPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "payrollExports.create", "tags": ["Crew"], "x-xos-table": "app.payroll_exports", "x-xos-capability": "crew.payroll.export", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a payroll export", "description": "A payroll export file for a payroll provider. Creates a payroll export. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "payroll_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "payroll_csv" }, "schema": { "$ref": "#/components/schemas/PayrollExportCreate" } } } }, "responses": { "201": { "description": "The created payroll export.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "payroll_csv", "file_uri": "payroll-exports/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f.csv", "checksum_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/PayrollExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-exports/{id}": { "get": { "operationId": "payrollExports.get", "tags": ["Crew"], "x-xos-table": "app.payroll_exports", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a payroll export", "description": "A payroll export file for a payroll provider. Returns one payroll export with its `ETag`. A payroll export the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payroll export.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payroll export.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The payroll export.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payroll_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "payroll_csv", "file_uri": "payroll-exports/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f.csv", "checksum_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/PayrollExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/earning-codes": { "get": { "operationId": "earningCodes.list", "tags": ["Crew"], "x-xos-table": "app.earning_codes", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["code"], "numeric": true }, "summary": "List earning code rows", "description": "An earning code mapped to the payroll provider. Returns a cursor page of earning code rows the caller may see. Coded list: the default order is numeric code order by `code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of earning code rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "010", "name": "Regular Hours", "is_overtime": false }, { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "020", "name": "Regular Hours", "is_overtime": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EarningCodePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "earningCodes.create", "tags": ["Crew"], "x-xos-table": "app.earning_codes", "x-xos-capability": "org.payroll.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an earning code", "description": "An earning code mapped to the payroll provider. Creates an earning code. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "REG", "name": "Regular Hours", "is_overtime": false }, "schema": { "$ref": "#/components/schemas/EarningCodeCreate" } } } }, "responses": { "201": { "description": "The created earning code.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "REG", "name": "Regular Hours", "is_overtime": false }, "schema": { "$ref": "#/components/schemas/EarningCode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/earning-codes/{id}": { "get": { "operationId": "earningCodes.get", "tags": ["Crew"], "x-xos-table": "app.earning_codes", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get an earning code", "description": "An earning code mapped to the payroll provider. Returns one earning code with its `ETag`. A earning code the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the earning code.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the earning code.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The earning code.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "REG", "name": "Regular Hours", "is_overtime": false }, "schema": { "$ref": "#/components/schemas/EarningCode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "earningCodes.update", "tags": ["Crew"], "x-xos-table": "app.earning_codes", "x-xos-capability": "org.payroll.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an earning code", "description": "An earning code mapped to the payroll provider. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the earning code.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the earning code.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "REG", "name": "Regular Hours", "is_overtime": false }, "schema": { "$ref": "#/components/schemas/EarningCodeUpdate" } } } }, "responses": { "200": { "description": "The updated earning code.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "REG", "name": "Regular Hours", "is_overtime": false }, "schema": { "$ref": "#/components/schemas/EarningCode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "earningCodes.delete", "tags": ["Crew"], "x-xos-table": "app.earning_codes", "x-xos-capability": "org.payroll.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an earning code", "description": "An earning code mapped to the payroll provider. Soft-deletes the earning code: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the earning code.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the earning code.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The earning code moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/per-diems": { "get": { "operationId": "perDiems.list", "tags": ["Crew"], "x-xos-table": "app.per_diems", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List per diem rows", "description": "A per diem allowance for an engagement. Returns a cursor page of per diem rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of per diem rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "amount_minor": 6500, "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PerDiemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "perDiems.create", "tags": ["Crew"], "x-xos-table": "app.per_diems", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a per diem", "description": "A per diem allowance for an engagement. Creates a per diem. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "amount_minor": 6500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PerDiemCreate" } } } }, "responses": { "201": { "description": "The created per diem.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "amount_minor": 6500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PerDiem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/per-diems/{id}": { "get": { "operationId": "perDiems.get", "tags": ["Crew"], "x-xos-table": "app.per_diems", "x-xos-capability": "crew.rate_card.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a per diem", "description": "A per diem allowance for an engagement. Returns one per diem with its `ETag`. A per diem the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the per diem.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the per diem.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The per diem.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "amount_minor": 6500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PerDiem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "perDiems.update", "tags": ["Crew"], "x-xos-table": "app.per_diems", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Update a per diem", "description": "A per diem allowance for an engagement. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the per diem.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the per diem.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "amount_minor": 6500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PerDiemUpdate" } } } }, "responses": { "200": { "description": "The updated per diem.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "day": "2026-10-08", "amount_minor": 6500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PerDiem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "perDiems.delete", "tags": ["Crew"], "x-xos-table": "app.per_diems", "x-xos-capability": "crew.rate_card.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Delete a per diem", "description": "A per diem allowance for an engagement. Soft-deletes the per diem: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the per diem.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the per diem.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The per diem moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-off-policies": { "get": { "operationId": "timeOffPolicies.list", "tags": ["Crew"], "x-xos-table": "app.time_off_policies", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List time off policy rows", "description": "A time off policy. Returns a cursor page of time off policy rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of time off policy rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Paid Time Off", "accrual_hours_per_period": 3.08 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TimeOffPolicyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "timeOffPolicies.create", "tags": ["Crew"], "x-xos-table": "app.time_off_policies", "x-xos-capability": "org.payroll.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a time off policy", "description": "A time off policy. Creates a time off policy. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Paid Time Off", "accrual_hours_per_period": 3.08 }, "schema": { "$ref": "#/components/schemas/TimeOffPolicyCreate" } } } }, "responses": { "201": { "description": "The created time off policy.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Paid Time Off", "accrual_hours_per_period": 3.08 }, "schema": { "$ref": "#/components/schemas/TimeOffPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-off-policies/{id}": { "get": { "operationId": "timeOffPolicies.get", "tags": ["Crew"], "x-xos-table": "app.time_off_policies", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a time off policy", "description": "A time off policy. Returns one time off policy with its `ETag`. A time off policy the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time off policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time off policy.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The time off policy.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Paid Time Off", "accrual_hours_per_period": 3.08 }, "schema": { "$ref": "#/components/schemas/TimeOffPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "timeOffPolicies.update", "tags": ["Crew"], "x-xos-table": "app.time_off_policies", "x-xos-capability": "org.payroll.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a time off policy", "description": "A time off policy. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time off policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time off policy.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Paid Time Off", "accrual_hours_per_period": 3.08 }, "schema": { "$ref": "#/components/schemas/TimeOffPolicyUpdate" } } } }, "responses": { "200": { "description": "The updated time off policy.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Paid Time Off", "accrual_hours_per_period": 3.08 }, "schema": { "$ref": "#/components/schemas/TimeOffPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "timeOffPolicies.delete", "tags": ["Crew"], "x-xos-table": "app.time_off_policies", "x-xos-capability": "org.payroll.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a time off policy", "description": "A time off policy. Soft-deletes the time off policy: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time off policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time off policy.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The time off policy moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-off-requests": { "get": { "operationId": "timeOffRequests.list", "tags": ["Crew"], "x-xos-table": "app.time_off_requests", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List time off request rows", "description": "A time off request. The submitter cannot approve it. Returns a cursor page of time off request rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of time off request rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_off_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_off_state": "Proposed", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 16 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TimeOffRequestPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "timeOffRequests.create", "tags": ["Crew"], "x-xos-table": "app.time_off_requests", "x-xos-capability": "crew.time_off.request", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Create a time off request", "description": "A time off request. The submitter cannot approve it. Creates a time off request. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "time_off_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 16 }, "schema": { "$ref": "#/components/schemas/TimeOffRequestCreate" } } } }, "responses": { "201": { "description": "The created time off request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_off_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_off_state": "Proposed", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 16 }, "schema": { "$ref": "#/components/schemas/TimeOffRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-off-requests/{id}": { "get": { "operationId": "timeOffRequests.get", "tags": ["Crew"], "x-xos-table": "app.time_off_requests", "x-xos-capability": "crew.schedule.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Get a time off request", "description": "A time off request. The submitter cannot approve it. Returns one time off request with its `ETag`. A time off request the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time off request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time off request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The time off request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_off_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_off_state": "Proposed", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 16 }, "schema": { "$ref": "#/components/schemas/TimeOffRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-off-requests/{id}/approve": { "post": { "operationId": "timeOffRequests.approve", "tags": ["Crew"], "x-xos-table": "app.time_off_requests", "x-xos-capability": "crew.time_off.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Approve a time off request", "description": "Records an approval decision on the time off request. The submitter cannot approve it. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time off request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time off request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_off_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_off_state": "Proposed", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 16 }, "schema": { "$ref": "#/components/schemas/TimeOffRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/time-off-requests/{id}/decline": { "post": { "operationId": "timeOffRequests.decline", "tags": ["Crew"], "x-xos-table": "app.time_off_requests", "x-xos-capability": "crew.time_off.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["crew"] }], "summary": "Decline a time off request", "description": "Declines the request. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the time off request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the time off request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_off_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "time_off_state": "Proposed", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hours": 16 }, "schema": { "$ref": "#/components/schemas/TimeOffRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/credential-categories": { "get": { "operationId": "credentialCategories.list", "tags": ["Credentials"], "x-xos-table": "app.credential_categories", "x-xos-capability": "credentials.credential.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "x-xos-order": { "by": ["code"], "numeric": false }, "summary": "List credential category rows", "description": "A credential category, such as All Access or Artist. Returns a cursor page of credential category rows the caller may see. The default order is `code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of credential category rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "All Access", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "ALL-ACCESS" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CredentialCategoryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "credentialCategories.create", "tags": ["Credentials"], "x-xos-table": "app.credential_categories", "x-xos-capability": "credentials.category.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Create a credential category", "description": "A credential category, such as All Access or Artist. Creates a credential category. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "All Access", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "ALL-ACCESS" }, "schema": { "$ref": "#/components/schemas/CredentialCategoryCreate" } } } }, "responses": { "201": { "description": "The created credential category.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "All Access", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "ALL-ACCESS" }, "schema": { "$ref": "#/components/schemas/CredentialCategory" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/credential-categories/{id}": { "get": { "operationId": "credentialCategories.get", "tags": ["Credentials"], "x-xos-table": "app.credential_categories", "x-xos-capability": "credentials.credential.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Get a credential category", "description": "A credential category, such as All Access or Artist. Returns one credential category with its `ETag`. A credential category the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the credential category.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The credential category.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "All Access", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "ALL-ACCESS" }, "schema": { "$ref": "#/components/schemas/CredentialCategory" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "credentialCategories.update", "tags": ["Credentials"], "x-xos-table": "app.credential_categories", "x-xos-capability": "credentials.category.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Update a credential category", "description": "A credential category, such as All Access or Artist. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the credential category.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "All Access", "code": "ALL-ACCESS" }, "schema": { "$ref": "#/components/schemas/CredentialCategoryUpdate" } } } }, "responses": { "200": { "description": "The updated credential category.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "All Access", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "ALL-ACCESS" }, "schema": { "$ref": "#/components/schemas/CredentialCategory" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "credentialCategories.delete", "tags": ["Credentials"], "x-xos-table": "app.credential_categories", "x-xos-capability": "credentials.category.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Delete a credential category", "description": "A credential category, such as All Access or Artist. Soft-deletes the credential category: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the credential category.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the credential category.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The credential category moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/credentials": { "get": { "operationId": "credentials.list", "tags": ["Credentials"], "x-xos-table": "app.credentials", "x-xos-capability": "credentials.credential.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List credential rows", "description": "An issued credential. Credentials cannot be self-issued. Returns a cursor page of credential rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of credential rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "holder_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_number": "CR-000123", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CredentialPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "credentials.create", "tags": ["Credentials"], "x-xos-table": "app.credentials", "x-xos-capability": "credentials.credential.issue", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Create a credential", "description": "An issued credential. Credentials cannot be self-issued. Creates a credential. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "holder_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CredentialCreate" } } } }, "responses": { "201": { "description": "The created credential.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "holder_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_number": "CR-000123", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/credentials/{id}": { "get": { "operationId": "credentials.get", "tags": ["Credentials"], "x-xos-table": "app.credentials", "x-xos-capability": "credentials.credential.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Get a credential", "description": "An issued credential. Credentials cannot be self-issued. Returns one credential with its `ETag`. A credential the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the credential.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the credential.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The credential.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "holder_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_number": "CR-000123", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/credentials/{id}/revoke": { "post": { "operationId": "credentials.revoke", "tags": ["Credentials"], "x-xos-table": "app.credentials", "x-xos-capability": "credentials.credential.revoke", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Revoke a credential", "description": "Revokes the credential; scans after revocation are refused. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the credential.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the credential.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "holder_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_number": "CR-000123", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-grid": { "get": { "operationId": "accessGridEntries.list", "tags": ["Credentials"], "x-xos-table": "app.access_grid", "x-xos-capability": "credentials.credential.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List access grid entry rows", "description": "A zone by credential category access rule with a time window. Returns a cursor page of access grid entry rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of access grid entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_level_enum_id": "ENM-036", "window_starts_at": "2026-10-08T14:30:00Z", "window_ends_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AccessGridEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "accessGridEntries.create", "tags": ["Credentials"], "x-xos-table": "app.access_grid", "x-xos-capability": "credentials.access_grid.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Create an access grid entry", "description": "A zone by credential category access rule with a time window. Creates an access grid entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_level_enum_id": "ENM-036", "window_starts_at": "2026-10-08T14:30:00Z", "window_ends_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccessGridEntryCreate" } } } }, "responses": { "201": { "description": "The created access grid entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_level_enum_id": "ENM-036", "window_starts_at": "2026-10-08T14:30:00Z", "window_ends_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AccessGridEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-grid/{id}": { "get": { "operationId": "accessGridEntries.get", "tags": ["Credentials"], "x-xos-table": "app.access_grid", "x-xos-capability": "credentials.credential.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Get an access grid entry", "description": "A zone by credential category access rule with a time window. Returns one access grid entry with its `ETag`. A access grid entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access grid entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access grid entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The access grid entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_level_enum_id": "ENM-036", "window_starts_at": "2026-10-08T14:30:00Z", "window_ends_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AccessGridEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "accessGridEntries.update", "tags": ["Credentials"], "x-xos-table": "app.access_grid", "x-xos-capability": "credentials.access_grid.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Update an access grid entry", "description": "A zone by credential category access rule with a time window. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access grid entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access grid entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "access_level_enum_id": "ENM-036", "window_starts_at": "2026-10-08T14:30:00Z", "window_ends_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccessGridEntryUpdate" } } } }, "responses": { "200": { "description": "The updated access grid entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_category_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_level_enum_id": "ENM-036", "window_starts_at": "2026-10-08T14:30:00Z", "window_ends_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AccessGridEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "accessGridEntries.delete", "tags": ["Credentials"], "x-xos-table": "app.access_grid", "x-xos-capability": "credentials.access_grid.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Delete an access grid entry", "description": "A zone by credential category access rule with a time window. Soft-deletes the access grid entry: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access grid entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access grid entry.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The access grid entry moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-scans": { "get": { "operationId": "accessScans.list", "tags": ["Credentials"], "x-xos-table": "app.access_scans", "x-xos-capability": "credentials.scan_log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "x-xos-order": { "by": ["scanned_at"], "numeric": false }, "summary": "List access scan rows", "description": "A credential scan at an access point, validated against the Access Grid. Returns a cursor page of access scan rows the caller may see. The default order is `scanned_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of access scan rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scanned_at": "2026-10-08T14:30:00Z", "result": "Granted", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_scanned_at": "2026-10-08T14:30:00Z", "offline_result": "Granted" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AccessScanPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "accessScans.create", "tags": ["Credentials"], "x-xos-table": "app.access_scans", "x-xos-capability": "credentials.scan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Create an access scan", "description": "A credential scan at an access point, validated against the Access Grid. Creates an access scan. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_scanned_at": "2026-10-08T14:30:00Z", "offline_result": "Granted" }, "schema": { "$ref": "#/components/schemas/AccessScanCreate" } } } }, "responses": { "201": { "description": "The created access scan.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scanned_at": "2026-10-08T14:30:00Z", "result": "Granted", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_scanned_at": "2026-10-08T14:30:00Z", "offline_result": "Granted" }, "schema": { "$ref": "#/components/schemas/AccessScan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-scans/{id}": { "get": { "operationId": "accessScans.get", "tags": ["Credentials"], "x-xos-table": "app.access_scans", "x-xos-capability": "credentials.scan_log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Get an access scan", "description": "A credential scan at an access point, validated against the Access Grid. Returns one access scan with its `ETag`. A access scan the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access scan.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access scan.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The access scan.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "credential_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scanned_at": "2026-10-08T14:30:00Z", "result": "Granted", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "device_scanned_at": "2026-10-08T14:30:00Z", "offline_result": "Granted" }, "schema": { "$ref": "#/components/schemas/AccessScan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/certifications": { "get": { "operationId": "certifications.list", "tags": ["Credentials"], "x-xos-table": "app.certifications", "x-xos-capability": "people.certification.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List certification rows", "description": "A certification type, linked to canon compliance tags. Returns a cursor page of certification rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of certification rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "OSHA 10", "issuing_body": "OSHA" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CertificationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "certifications.create", "tags": ["Credentials"], "x-xos-table": "app.certifications", "x-xos-capability": "people.role.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Create a certification", "description": "A certification type, linked to canon compliance tags. Creates a certification. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "OSHA 10", "issuing_body": "OSHA" }, "schema": { "$ref": "#/components/schemas/CertificationCreate" } } } }, "responses": { "201": { "description": "The created certification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "OSHA 10", "issuing_body": "OSHA" }, "schema": { "$ref": "#/components/schemas/Certification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/certifications/{id}": { "get": { "operationId": "certifications.get", "tags": ["Credentials"], "x-xos-table": "app.certifications", "x-xos-capability": "people.certification.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get a certification", "description": "A certification type, linked to canon compliance tags. Returns one certification with its `ETag`. A certification the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the certification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The certification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "OSHA 10", "issuing_body": "OSHA" }, "schema": { "$ref": "#/components/schemas/Certification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "certifications.update", "tags": ["Credentials"], "x-xos-table": "app.certifications", "x-xos-capability": "people.role.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Update a certification", "description": "A certification type, linked to canon compliance tags. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the certification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "OSHA 10", "issuing_body": "OSHA" }, "schema": { "$ref": "#/components/schemas/CertificationUpdate" } } } }, "responses": { "200": { "description": "The updated certification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "OSHA 10", "issuing_body": "OSHA" }, "schema": { "$ref": "#/components/schemas/Certification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "certifications.delete", "tags": ["Credentials"], "x-xos-table": "app.certifications", "x-xos-capability": "people.role.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Delete a certification", "description": "A certification type, linked to canon compliance tags. Soft-deletes the certification: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the certification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the certification.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The certification moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/certification-holders": { "get": { "operationId": "certificationHolders.list", "tags": ["Credentials"], "x-xos-table": "app.certification_holders", "x-xos-capability": "people.certification.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List certification holder rows", "description": "A person's certification with evidence and expiry. It cannot be self-verified and verifies publicly only with consent. Returns a cursor page of certification holder rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of certification holder rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_on": "2026-10-08", "verified_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_on": "2026-10-08", "public_verification_consented": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CertificationHolderPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "certificationHolders.create", "tags": ["Credentials"], "x-xos-table": "app.certification_holders", "x-xos-capability": "people.certification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Create a certification holder", "description": "A person's certification with evidence and expiry. It cannot be self-verified and verifies publicly only with consent. Creates a certification holder. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_on": "2026-10-08", "issued_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/CertificationHolderCreate" } } } }, "responses": { "201": { "description": "The created certification holder.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_on": "2026-10-08", "verified_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_on": "2026-10-08", "public_verification_consented": false }, "schema": { "$ref": "#/components/schemas/CertificationHolder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/certification-holders/{id}": { "get": { "operationId": "certificationHolders.get", "tags": ["Credentials"], "x-xos-table": "app.certification_holders", "x-xos-capability": "people.certification.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get a certification holder", "description": "A person's certification with evidence and expiry. It cannot be self-verified and verifies publicly only with consent. Returns one certification holder with its `ETag`. A certification holder the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the certification holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the certification holder.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The certification holder.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_on": "2026-10-08", "verified_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_on": "2026-10-08", "public_verification_consented": false }, "schema": { "$ref": "#/components/schemas/CertificationHolder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "certificationHolders.update", "tags": ["Credentials"], "x-xos-table": "app.certification_holders", "x-xos-capability": "people.certification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Update a certification holder", "description": "A person's certification with evidence and expiry. It cannot be self-verified and verifies publicly only with consent. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the certification holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the certification holder.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expires_on": "2026-10-08", "issued_on": "2026-10-08", "public_verification_consented": false }, "schema": { "$ref": "#/components/schemas/CertificationHolderUpdate" } } } }, "responses": { "200": { "description": "The updated certification holder.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_on": "2026-10-08", "verified_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_on": "2026-10-08", "public_verification_consented": false }, "schema": { "$ref": "#/components/schemas/CertificationHolder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "certificationHolders.delete", "tags": ["Credentials"], "x-xos-table": "app.certification_holders", "x-xos-capability": "people.certification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Delete a certification holder", "description": "A person's certification with evidence and expiry. It cannot be self-verified and verifies publicly only with consent. Soft-deletes the certification holder: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the certification holder.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the certification holder.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The certification holder moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/budgets": { "get": { "operationId": "budgets.list", "tags": ["Finance"], "x-xos-table": "app.budgets", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List budget rows", "description": "A project budget, structured as a chart of accounts by department and discipline. Returns a cursor page of budget rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of budget rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Budget", "currency_code": "USD", "is_baseline": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BudgetPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "budgets.create", "tags": ["Finance"], "x-xos-table": "app.budgets", "x-xos-capability": "finance.budget.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a budget", "description": "A project budget, structured as a chart of accounts by department and discipline. Creates a budget. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Budget", "currency_code": "USD", "is_baseline": false }, "schema": { "$ref": "#/components/schemas/BudgetCreate" } } } }, "responses": { "201": { "description": "The created budget.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Budget", "currency_code": "USD", "is_baseline": false }, "schema": { "$ref": "#/components/schemas/Budget" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/budgets/{id}": { "get": { "operationId": "budgets.get", "tags": ["Finance"], "x-xos-table": "app.budgets", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a budget", "description": "A project budget, structured as a chart of accounts by department and discipline. Returns one budget with its `ETag`. A budget the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the budget.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The budget.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Budget", "currency_code": "USD", "is_baseline": false }, "schema": { "$ref": "#/components/schemas/Budget" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "budgets.update", "tags": ["Finance"], "x-xos-table": "app.budgets", "x-xos-capability": "finance.budget.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a budget", "description": "A project budget, structured as a chart of accounts by department and discipline. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the budget.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Gate 3 Budget", "currency_code": "USD", "is_baseline": false }, "schema": { "$ref": "#/components/schemas/BudgetUpdate" } } } }, "responses": { "200": { "description": "The updated budget.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Gate 3 Budget", "currency_code": "USD", "is_baseline": false }, "schema": { "$ref": "#/components/schemas/Budget" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "budgets.delete", "tags": ["Finance"], "x-xos-table": "app.budgets", "x-xos-capability": "finance.budget.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Delete a budget", "description": "A project budget, structured as a chart of accounts by department and discipline. Soft-deletes the budget: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the budget.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The budget moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/budgets/{id}/summary": { "get": { "operationId": "budgets.summary", "tags": ["Finance"], "x-xos-table": "app.budgets", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get budget totals", "description": "Returns estimate, committed, actual and variance as NULL-aware totals. Unpriced lines are excluded from each sum and counted in `unpriced_count`. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the budget.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the budget.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "estimate": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "committed": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "actual": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "variance": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 } }, "schema": { "$ref": "#/components/schemas/BudgetSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/budget-lines": { "get": { "operationId": "budgetLines.list", "tags": ["Finance"], "x-xos-table": "app.budget_lines", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["line_number"], "numeric": false }, "summary": "List budget line rows", "description": "A budget line. A blank unit price is unpriced; zero is a claim. Fee and Contingency are line types. Returns a cursor page of budget line rows the caller may see. The default order is `line_number` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of budget line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "xyz": "X", "xyz_basis": "Rented inventory", "line_type": "Contingency", "grade_code": "base", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_total_minor": 108000, "line_number": 1, "phase_code": "SCP", "tier_code": "04", "actual_minor": 480000, "account_code": "5400" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BudgetLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "budgetLines.create", "tags": ["Finance"], "x-xos-table": "app.budget_lines", "x-xos-capability": "finance.budget.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a budget line", "description": "A budget line. A blank unit price is unpriced; zero is a claim. Fee and Contingency are line types. Creates a budget line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "xyz": "X", "xyz_basis": "Rented inventory", "line_type": "Contingency", "grade_code": "base", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1, "phase_code": "SCP", "tier_code": "04" }, "schema": { "$ref": "#/components/schemas/BudgetLineCreate" } } } }, "responses": { "201": { "description": "The created budget line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "xyz": "X", "xyz_basis": "Rented inventory", "line_type": "Contingency", "grade_code": "base", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_total_minor": 108000, "line_number": 1, "phase_code": "SCP", "tier_code": "04", "actual_minor": 480000, "account_code": "5400" }, "schema": { "$ref": "#/components/schemas/BudgetLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/budget-lines/{id}": { "get": { "operationId": "budgetLines.get", "tags": ["Finance"], "x-xos-table": "app.budget_lines", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a budget line", "description": "A budget line. A blank unit price is unpriced; zero is a claim. Fee and Contingency are line types. Returns one budget line with its `ETag`. A budget line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the budget line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The budget line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "xyz": "X", "xyz_basis": "Rented inventory", "line_type": "Contingency", "grade_code": "base", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_total_minor": 108000, "line_number": 1, "phase_code": "SCP", "tier_code": "04", "actual_minor": 480000, "account_code": "5400" }, "schema": { "$ref": "#/components/schemas/BudgetLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "budgetLines.update", "tags": ["Finance"], "x-xos-table": "app.budget_lines", "x-xos-capability": "finance.budget.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a budget line", "description": "A budget line. A blank unit price is unpriced; zero is a claim. Fee and Contingency are line types. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the budget line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "xyz": "X", "xyz_basis": "Rented inventory", "line_type": "Contingency", "grade_code": "base", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1, "phase_code": "SCP", "tier_code": "04" }, "schema": { "$ref": "#/components/schemas/BudgetLineUpdate" } } } }, "responses": { "200": { "description": "The updated budget line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "xyz": "X", "xyz_basis": "Rented inventory", "line_type": "Contingency", "grade_code": "base", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_total_minor": 108000, "line_number": 1, "phase_code": "SCP", "tier_code": "04", "actual_minor": 480000, "account_code": "5400" }, "schema": { "$ref": "#/components/schemas/BudgetLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "budgetLines.delete", "tags": ["Finance"], "x-xos-table": "app.budget_lines", "x-xos-capability": "finance.budget.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Delete a budget line", "description": "A budget line. A blank unit price is unpriced; zero is a claim. Fee and Contingency are line types. Soft-deletes the budget line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the budget line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the budget line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The budget line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/expenses": { "get": { "operationId": "expenses.list", "tags": ["Finance"], "x-xos-table": "app.expenses", "x-xos-capability": "finance.expense.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List expense rows", "description": "An expense. One expense posts to exactly one budget line; the submitter cannot approve it. Returns a cursor page of expense rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of expense rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "expense_state": "Proposed", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ExpensePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "expenses.create", "tags": ["Finance"], "x-xos-table": "app.expenses", "x-xos-capability": "finance.expense.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create an expense", "description": "An expense. One expense posts to exactly one budget line; the submitter cannot approve it. Creates an expense. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ExpenseCreate" } } } }, "responses": { "201": { "description": "The created expense.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "expense_state": "Proposed", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Expense" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/expenses/{id}": { "get": { "operationId": "expenses.get", "tags": ["Finance"], "x-xos-table": "app.expenses", "x-xos-capability": "finance.expense.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get an expense", "description": "An expense. One expense posts to exactly one budget line; the submitter cannot approve it. Returns one expense with its `ETag`. A expense the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the expense.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the expense.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The expense.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "expense_state": "Proposed", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Expense" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "expenses.update", "tags": ["Finance"], "x-xos-table": "app.expenses", "x-xos-capability": "finance.expense.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update an expense", "description": "An expense. One expense posts to exactly one budget line; the submitter cannot approve it. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the expense.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the expense.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ExpenseUpdate" } } } }, "responses": { "200": { "description": "The updated expense.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "expense_state": "Proposed", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Expense" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/expenses/{id}/submit": { "post": { "operationId": "expenses.submit", "tags": ["Finance"], "x-xos-table": "app.expenses", "x-xos-capability": "finance.expense.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Submit an expense", "description": "Submits the expense for approval. A closed production refuses new expenses. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the expense.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the expense.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "expense_state": "Proposed", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Expense" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/expenses/{id}/approve": { "post": { "operationId": "expenses.approve", "tags": ["Finance"], "x-xos-table": "app.expenses", "x-xos-capability": "finance.expense.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Approve a expense", "description": "Records an approval decision on the expense. The submitter cannot approve it. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the expense.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the expense.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Gaffer tape, 12 rolls", "amount_minor": 14388, "currency_code": "USD", "incurred_on": "2026-10-08", "expense_state": "Proposed", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Expense" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contingency-draws": { "get": { "operationId": "contingencyDraws.list", "tags": ["Finance"], "x-xos-table": "app.contingency_draws", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List contingency draw rows", "description": "A draw from a contingency line onto another budget line. Returns a cursor page of contingency draw rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of contingency draw rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 250000, "reason": "Added wind bracing after the engineering review." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ContingencyDrawPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "contingencyDraws.create", "tags": ["Finance"], "x-xos-table": "app.contingency_draws", "x-xos-capability": "finance.budget.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a contingency draw", "description": "A draw from a contingency line onto another budget line. Creates a contingency draw. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "from_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 250000, "reason": "Added wind bracing after the engineering review." }, "schema": { "$ref": "#/components/schemas/ContingencyDrawCreate" } } } }, "responses": { "201": { "description": "The created contingency draw.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 250000, "reason": "Added wind bracing after the engineering review." }, "schema": { "$ref": "#/components/schemas/ContingencyDraw" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contingency-draws/{id}": { "get": { "operationId": "contingencyDraws.get", "tags": ["Finance"], "x-xos-table": "app.contingency_draws", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a contingency draw", "description": "A draw from a contingency line onto another budget line. Returns one contingency draw with its `ETag`. A contingency draw the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the contingency draw.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the contingency draw.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The contingency draw.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 250000, "reason": "Added wind bracing after the engineering review." }, "schema": { "$ref": "#/components/schemas/ContingencyDraw" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/change-orders": { "get": { "operationId": "changeOrders.list", "tags": ["Finance"], "x-xos-table": "app.change_orders", "x-xos-capability": "finance.change_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List change order rows", "description": "A change order. An unpriced change order cannot be stored at zero; its requester cannot price and approve it alone. Returns a cursor page of change order rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of change order rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_number": 3, "order_type_enum_id": "ENM-092", "priced_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show.", "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ChangeOrderPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "changeOrders.create", "tags": ["Finance"], "x-xos-table": "app.change_orders", "x-xos-capability": "finance.change_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a change order", "description": "A change order. An unpriced change order cannot be stored at zero; its requester cannot price and approve it alone. Creates a change order. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "order_type_enum_id": "ENM-092", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show." }, "schema": { "$ref": "#/components/schemas/ChangeOrderCreate" } } } }, "responses": { "201": { "description": "The created change order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_number": 3, "order_type_enum_id": "ENM-092", "priced_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show.", "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/change-orders/{id}": { "get": { "operationId": "changeOrders.get", "tags": ["Finance"], "x-xos-table": "app.change_orders", "x-xos-capability": "finance.change_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a change order", "description": "A change order. An unpriced change order cannot be stored at zero; its requester cannot price and approve it alone. Returns one change order with its `ETag`. A change order the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The change order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_number": 3, "order_type_enum_id": "ENM-092", "priced_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show.", "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "changeOrders.update", "tags": ["Finance"], "x-xos-table": "app.change_orders", "x-xos-capability": "finance.change_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a change order", "description": "A change order. An unpriced change order cannot be stored at zero; its requester cannot price and approve it alone. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "order_type_enum_id": "ENM-092", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show." }, "schema": { "$ref": "#/components/schemas/ChangeOrderUpdate" } } } }, "responses": { "200": { "description": "The updated change order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_number": 3, "order_type_enum_id": "ENM-092", "priced_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show.", "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/change-orders/{id}/transitions": { "post": { "operationId": "changeOrders.transition", "tags": ["Finance"], "x-xos-table": "app.change_orders", "x-xos-capability": "finance.change_order.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Transition the change order state", "description": "Moves the change order lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Proposed", "to_state": "Canceled", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/ChangeOrderTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_number": 3, "order_type_enum_id": "ENM-092", "priced_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show.", "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/change-orders/{id}/approve": { "post": { "operationId": "changeOrders.approve", "tags": ["Finance"], "x-xos-table": "app.change_orders", "x-xos-capability": "finance.change_order.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Approve a change order", "description": "Records an approval decision on the change order. Its requester cannot price and approve it alone, and an unpriced change order cannot be approved at zero. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Add Second Bar", "reason": "Client added a second bar at the north lawn.", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_number": 3, "order_type_enum_id": "ENM-092", "priced_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "schedule_impact_days": 2, "client_impact": "Adds a second stage to the run of show.", "approved_at": "2026-10-08T14:30:00Z", "approved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/change-order-lines": { "get": { "operationId": "changeOrderLines.list", "tags": ["Finance"], "x-xos-table": "app.change_order_lines", "x-xos-capability": "finance.change_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List change order line rows", "description": "A line of a change order. Returns a cursor page of change order line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of change order line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Bar build and dressing", "quantity": 24, "unit_price_minor": 1200000, "is_no_cost": false, "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ChangeOrderLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "changeOrderLines.create", "tags": ["Finance"], "x-xos-table": "app.change_order_lines", "x-xos-capability": "finance.change_order.price", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a change order line", "description": "A line of a change order. Creates a change order line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "change_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Bar build and dressing", "quantity": 24, "unit_price_minor": 1200000, "is_no_cost": false }, "schema": { "$ref": "#/components/schemas/ChangeOrderLineCreate" } } } }, "responses": { "201": { "description": "The created change order line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Bar build and dressing", "quantity": 24, "unit_price_minor": 1200000, "is_no_cost": false, "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrderLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/change-order-lines/{id}": { "get": { "operationId": "changeOrderLines.get", "tags": ["Finance"], "x-xos-table": "app.change_order_lines", "x-xos-capability": "finance.change_order.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a change order line", "description": "A line of a change order. Returns one change order line with its `ETag`. A change order line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the change order line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the change order line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The change order line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Bar build and dressing", "quantity": 24, "unit_price_minor": 1200000, "is_no_cost": false, "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrderLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "changeOrderLines.update", "tags": ["Finance"], "x-xos-table": "app.change_order_lines", "x-xos-capability": "finance.change_order.price", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a change order line", "description": "A line of a change order. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the change order line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the change order line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Bar build and dressing", "quantity": 24, "unit_price_minor": 1200000, "is_no_cost": false }, "schema": { "$ref": "#/components/schemas/ChangeOrderLineUpdate" } } } }, "responses": { "200": { "description": "The updated change order line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "change_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "description": "Bar build and dressing", "quantity": 24, "unit_price_minor": 1200000, "is_no_cost": false, "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ChangeOrderLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "changeOrderLines.delete", "tags": ["Finance"], "x-xos-table": "app.change_order_lines", "x-xos-capability": "finance.change_order.price", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Delete a change order line", "description": "A line of a change order. Soft-deletes the change order line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the change order line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the change order line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The change order line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accounting-periods": { "get": { "operationId": "accountingPeriods.list", "tags": ["Finance"], "x-xos-table": "app.accounting_periods", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["starts_on"], "numeric": false }, "summary": "List accounting period rows", "description": "An accounting period. A closed period refuses postings; an open period cannot become Audited without passing through Closed. Returns a cursor page of accounting period rows the caller may see. The default order is `starts_on` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of accounting period rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "period_state": "Open" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AccountingPeriodPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "accountingPeriods.create", "tags": ["Finance"], "x-xos-table": "app.accounting_periods", "x-xos-capability": "finance.period.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create an accounting period", "description": "An accounting period. A closed period refuses postings; an open period cannot become Audited without passing through Closed. Creates an accounting period. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "starts_on": "2026-10-08", "ends_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/AccountingPeriodCreate" } } } }, "responses": { "201": { "description": "The created accounting period.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "period_state": "Open" }, "schema": { "$ref": "#/components/schemas/AccountingPeriod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accounting-periods/{id}": { "get": { "operationId": "accountingPeriods.get", "tags": ["Finance"], "x-xos-table": "app.accounting_periods", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get an accounting period", "description": "An accounting period. A closed period refuses postings; an open period cannot become Audited without passing through Closed. Returns one accounting period with its `ETag`. A accounting period the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the accounting period.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The accounting period.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "period_state": "Open" }, "schema": { "$ref": "#/components/schemas/AccountingPeriod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accounting-periods/{id}/transitions": { "post": { "operationId": "accountingPeriods.transition", "tags": ["Finance"], "x-xos-table": "app.accounting_periods", "x-xos-capability": "finance.period.close", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Transition an accounting period", "description": "Moves the period through Open, In Period, Closing, Closed, Audited and Archived. A closed period refuses postings; Audited is reachable only through Closed. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the accounting period.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the accounting period.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Closing", "to_state": "Closed", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/AccountingPeriodTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "period_state": "Open" }, "schema": { "$ref": "#/components/schemas/AccountingPeriod" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/journal-entries": { "get": { "operationId": "journalEntries.list", "tags": ["Finance"], "x-xos-table": "app.journal_entries", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List journal entry rows", "description": "A journal entry. The preparer cannot post it. Returns a cursor page of journal entry rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of journal entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry_date": "2026-10-08", "memo": "Reclass staging rental", "journal_state": "Proposed", "posted_at": "2026-10-08T14:30:00Z", "posted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "prepared_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_table": "invoices", "source_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/JournalEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "journalEntries.create", "tags": ["Finance"], "x-xos-table": "app.journal_entries", "x-xos-capability": "finance.journal.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a journal entry", "description": "A journal entry. The preparer cannot post it. Creates a journal entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry_date": "2026-10-08", "memo": "Reclass staging rental", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JournalEntryCreate" } } } }, "responses": { "201": { "description": "The created journal entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry_date": "2026-10-08", "memo": "Reclass staging rental", "journal_state": "Proposed", "posted_at": "2026-10-08T14:30:00Z", "posted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "prepared_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_table": "invoices", "source_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JournalEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/journal-entries/{id}": { "get": { "operationId": "journalEntries.get", "tags": ["Finance"], "x-xos-table": "app.journal_entries", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a journal entry", "description": "A journal entry. The preparer cannot post it. Returns one journal entry with its `ETag`. A journal entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the journal entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the journal entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The journal entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry_date": "2026-10-08", "memo": "Reclass staging rental", "journal_state": "Proposed", "posted_at": "2026-10-08T14:30:00Z", "posted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "prepared_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_table": "invoices", "source_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JournalEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "journalEntries.update", "tags": ["Finance"], "x-xos-table": "app.journal_entries", "x-xos-capability": "finance.journal.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a journal entry", "description": "A journal entry. The preparer cannot post it. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the journal entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the journal entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry_date": "2026-10-08", "memo": "Reclass staging rental", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JournalEntryUpdate" } } } }, "responses": { "200": { "description": "The updated journal entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry_date": "2026-10-08", "memo": "Reclass staging rental", "journal_state": "Proposed", "posted_at": "2026-10-08T14:30:00Z", "posted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "prepared_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_table": "invoices", "source_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JournalEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/journal-entries/{id}/post": { "post": { "operationId": "journalEntries.post", "tags": ["Finance"], "x-xos-table": "app.journal_entries", "x-xos-capability": "finance.journal.post", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Post a journal entry", "description": "Posts the entry to the ledger. The preparer cannot post it; a closed period refuses it. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the journal entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the journal entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "entry_date": "2026-10-08", "memo": "Reclass staging rental", "journal_state": "Proposed", "posted_at": "2026-10-08T14:30:00Z", "posted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "prepared_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_table": "invoices", "source_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JournalEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/journal-lines": { "get": { "operationId": "journalLines.list", "tags": ["Finance"], "x-xos-table": "app.journal_lines", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["account_code"], "numeric": true }, "summary": "List journal line rows", "description": "A line of a journal entry. Returns a cursor page of journal line rows the caller may see. Coded list: the default order is numeric code order by `account_code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of journal line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "journal_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "1000", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "line_number": 1, "description": "Reclass staging rental", "debit_minor": 45000, "credit_minor": 0, "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "quantity": 24, "unit_basis": "each" }, { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "journal_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "line_number": 1, "description": "Reclass staging rental", "debit_minor": 45000, "credit_minor": 0, "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "quantity": 24, "unit_basis": "each" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/JournalLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "journalLines.create", "tags": ["Finance"], "x-xos-table": "app.journal_lines", "x-xos-capability": "finance.journal.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a journal line", "description": "A line of a journal entry. Creates a journal line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "journal_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "line_number": 1, "description": "Reclass staging rental", "debit_minor": 45000, "credit_minor": 0, "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "quantity": 24, "unit_basis": "each" }, "schema": { "$ref": "#/components/schemas/JournalLineCreate" } } } }, "responses": { "201": { "description": "The created journal line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "journal_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "line_number": 1, "description": "Reclass staging rental", "debit_minor": 45000, "credit_minor": 0, "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "quantity": 24, "unit_basis": "each" }, "schema": { "$ref": "#/components/schemas/JournalLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/journal-lines/{id}": { "get": { "operationId": "journalLines.get", "tags": ["Finance"], "x-xos-table": "app.journal_lines", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a journal line", "description": "A line of a journal entry. Returns one journal line with its `ETag`. A journal line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the journal line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the journal line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The journal line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "journal_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "line_number": 1, "description": "Reclass staging rental", "debit_minor": 45000, "credit_minor": 0, "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "quantity": 24, "unit_basis": "each" }, "schema": { "$ref": "#/components/schemas/JournalLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "journalLines.update", "tags": ["Finance"], "x-xos-table": "app.journal_lines", "x-xos-capability": "finance.journal.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a journal line", "description": "A line of a journal entry. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the journal line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the journal line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "line_number": 1, "description": "Reclass staging rental", "debit_minor": 45000, "credit_minor": 0, "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "quantity": 24, "unit_basis": "each" }, "schema": { "$ref": "#/components/schemas/JournalLineUpdate" } } } }, "responses": { "200": { "description": "The updated journal line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "journal_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5400", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "line_number": 1, "description": "Reclass staging rental", "debit_minor": 45000, "credit_minor": 0, "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "quantity": 24, "unit_basis": "each" }, "schema": { "$ref": "#/components/schemas/JournalLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "journalLines.delete", "tags": ["Finance"], "x-xos-table": "app.journal_lines", "x-xos-capability": "finance.journal.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Delete a journal line", "description": "A line of a journal entry. Soft-deletes the journal line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the journal line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the journal line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The journal line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/posting-lines": { "get": { "operationId": "postingLines.list", "tags": ["Finance"], "x-xos-table": "app.posting_lines", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["account_code", "urid"], "numeric": true }, "summary": "List posting line rows", "description": "A Universal Posting Line (Bible tab 36): the one export shape, projected to every accounting platform. Returns a cursor page of posting line rows the caller may see. Coded list: the default order is numeric code order by `account_code`, then `urid`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of posting line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "date": "2026-10-08", "account_code": "5000", "cost_center_id": "CC-VENUE", "urid": "0000.01", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_id": "4000.01.01-XPMS-001", "description": "Stage deck rental for opening weekend.", "quantity": 24, "unit_basis": "each", "amount_minor": 108000, "tax_type": "Tax on Purchases", "currency": "USD", "external_ref": "INV-2026-0042", "line_state": "Committed", "posting_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, { "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "date": "2026-10-08", "account_code": "5400", "cost_center_id": "CC-VENUE", "urid": "4000.01", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_id": "4000.01.01-XPMS-001", "description": "Stage deck rental for opening weekend.", "quantity": 24, "unit_basis": "each", "amount_minor": 108000, "tax_type": "Tax on Purchases", "currency": "USD", "external_ref": "INV-2026-0042", "line_state": "Committed", "posting_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PostingLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/posting-lines/{posting_line_id}": { "get": { "operationId": "postingLines.get", "tags": ["Finance"], "x-xos-table": "app.posting_lines", "x-xos-capability": "finance.journal.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a posting line", "description": "A Universal Posting Line (Bible tab 36): the one export shape, projected to every accounting platform. Returns one posting line with its `ETag`. A posting line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the posting line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the posting line.", "name": "posting_line_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The posting line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "date": "2026-10-08", "account_code": "5400", "cost_center_id": "CC-VENUE", "urid": "4000.01", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_id": "4000.01.01-XPMS-001", "description": "Stage deck rental for opening weekend.", "quantity": 24, "unit_basis": "each", "amount_minor": 108000, "tax_type": "Tax on Purchases", "currency": "USD", "external_ref": "INV-2026-0042", "line_state": "Committed", "posting_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PostingLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/posting-lines/exports": { "post": { "operationId": "postingLines.export", "tags": ["Finance"], "x-xos-table": "app.posting_lines", "x-xos-capability": "finance.upl.export", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Export posting lines", "description": "Projects the period's Universal Posting Lines to the target accounting platform through its canon field mapping and returns the CSV. There is no other export format. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "target": "xero", "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PostingExportRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "target": "xero", "accounting_period_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filename": "upl-xero-2026-09-01-2026-09-30.csv", "content_type": "text/csv", "header": ["Date", "Amount"], "row_count": 42, "csv": "Date,AccountCode\r\n2026-09-14,5400\r\n" }, "schema": { "$ref": "#/components/schemas/PostingExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoices": { "get": { "operationId": "invoices.list", "tags": ["Finance"], "x-xos-table": "app.invoices", "x-xos-capability": "finance.invoice.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List invoice rows", "description": "An invoice issued or received. A closed production refuses new invoices. Returns a cursor page of invoice rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of invoice rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "invoice_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InvoicePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "invoices.create", "tags": ["Finance"], "x-xos-table": "app.invoices", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create an invoice", "description": "An invoice issued or received. A closed production refuses new invoices. Creates an invoice. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/InvoiceCreate" } } } }, "responses": { "201": { "description": "The created invoice.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "invoice_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoices/{id}": { "get": { "operationId": "invoices.get", "tags": ["Finance"], "x-xos-table": "app.invoices", "x-xos-capability": "finance.invoice.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get an invoice", "description": "An invoice issued or received. A closed production refuses new invoices. Returns one invoice with its `ETag`. A invoice the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The invoice.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "invoice_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "invoices.update", "tags": ["Finance"], "x-xos-table": "app.invoices", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update an invoice", "description": "An invoice issued or received. A closed production refuses new invoices. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/InvoiceUpdate" } } } }, "responses": { "200": { "description": "The updated invoice.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "invoice_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoices/{id}/transitions": { "post": { "operationId": "invoices.transition", "tags": ["Finance"], "x-xos-table": "app.invoices", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Transition the invoice state", "description": "Moves the invoice lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Proposed", "to_state": "Canceled", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/InvoiceTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "invoice_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoices/{id}/approve": { "post": { "operationId": "invoices.approve", "tags": ["Finance"], "x-xos-table": "app.invoices", "x-xos-capability": "finance.invoice.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Approve a invoice", "description": "Records an approval decision on the invoice. Three-way match must pass, and a person who created the vendor or edited its bank details cannot approve payment to it. Spend authority and separation of duties are enforced in the approval RPC; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "invoice_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoices/{id}/record-payment": { "post": { "operationId": "invoices.recordPayment", "tags": ["Finance"], "x-xos-table": "app.invoices", "x-xos-capability": "finance.payment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Record a payment", "description": "Records that an approved payable (or issued receivable) was paid: a Proposed payment of the invoice's payee, its counterparty or the person engaged as an individual, applied to the invoice for the whole balance unless `amount_minor` says otherwise. Money moves on the org's own rails; XOS never holds funds. Another eligible person approves the payment. Refuses a Proposed, Disputed or Canceled invoice and an invoice with nothing left to pay (422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "paid_on": "2026-10-08", "amount_minor": 349000, "reference": "ACH-2027-0042" }, "schema": { "$ref": "#/components/schemas/InvoicePaymentRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "Payable", "invoice_number": "INV-2026-0042", "issued_on": "2026-10-08", "due_on": "2026-10-08", "currency_code": "USD", "invoice_state": "Proposed", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoice-lines": { "get": { "operationId": "invoiceLines.list", "tags": ["Finance"], "x-xos-table": "app.invoice_lines", "x-xos-capability": "finance.invoice.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List invoice line rows", "description": "A line of an invoice. Returns a cursor page of invoice line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of invoice line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Stage deck rental", "quantity": 24, "unit_price_minor": 4500, "line_number": 1, "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_rate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InvoiceLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "invoiceLines.create", "tags": ["Finance"], "x-xos-table": "app.invoice_lines", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create an invoice line", "description": "A line of an invoice. Creates an invoice line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Stage deck rental", "quantity": 24, "unit_price_minor": 4500, "line_number": 1, "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_rate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01" }, "schema": { "$ref": "#/components/schemas/InvoiceLineCreate" } } } }, "responses": { "201": { "description": "The created invoice line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Stage deck rental", "quantity": 24, "unit_price_minor": 4500, "line_number": 1, "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_rate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01" }, "schema": { "$ref": "#/components/schemas/InvoiceLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoice-lines/{id}": { "get": { "operationId": "invoiceLines.get", "tags": ["Finance"], "x-xos-table": "app.invoice_lines", "x-xos-capability": "finance.invoice.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get an invoice line", "description": "A line of an invoice. Returns one invoice line with its `ETag`. A invoice line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The invoice line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Stage deck rental", "quantity": 24, "unit_price_minor": 4500, "line_number": 1, "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_rate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01" }, "schema": { "$ref": "#/components/schemas/InvoiceLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "invoiceLines.update", "tags": ["Finance"], "x-xos-table": "app.invoice_lines", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update an invoice line", "description": "A line of an invoice. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Stage deck rental", "quantity": 24, "unit_price_minor": 4500, "line_number": 1, "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_rate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01" }, "schema": { "$ref": "#/components/schemas/InvoiceLineUpdate" } } } }, "responses": { "200": { "description": "The updated invoice line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Stage deck rental", "quantity": 24, "unit_price_minor": 4500, "line_number": 1, "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_rate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01" }, "schema": { "$ref": "#/components/schemas/InvoiceLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "invoiceLines.delete", "tags": ["Finance"], "x-xos-table": "app.invoice_lines", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Delete an invoice line", "description": "A line of an invoice. Soft-deletes the invoice line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The invoice line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payment-applications": { "get": { "operationId": "paymentApplications.list", "tags": ["Finance"], "x-xos-table": "app.payment_applications", "x-xos-capability": "finance.payment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List payment application rows", "description": "A payment applied to an invoice. Billed-to-date counts each payment once. Returns a cursor page of payment application rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of payment application rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "paid_on": "2026-10-08", "amount_minor": 108000, "currency_code": "USD", "external_ref": "ACH-77812", "payment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PaymentApplicationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "paymentApplications.create", "tags": ["Finance"], "x-xos-table": "app.payment_applications", "x-xos-capability": "finance.payment.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a payment application", "description": "A payment applied to an invoice. Billed-to-date counts each payment once. Creates a payment application. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 108000, "payment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PaymentApplicationCreate" } } } }, "responses": { "201": { "description": "The created payment application.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "paid_on": "2026-10-08", "amount_minor": 108000, "currency_code": "USD", "external_ref": "ACH-77812", "payment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PaymentApplication" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payment-applications/{id}": { "get": { "operationId": "paymentApplications.get", "tags": ["Finance"], "x-xos-table": "app.payment_applications", "x-xos-capability": "finance.payment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a payment application", "description": "A payment applied to an invoice. Billed-to-date counts each payment once. Returns one payment application with its `ETag`. A payment application the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payment application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payment application.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The payment application.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "paid_on": "2026-10-08", "amount_minor": 108000, "currency_code": "USD", "external_ref": "ACH-77812", "payment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PaymentApplication" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/billing-draws": { "get": { "operationId": "billingDraws.list", "tags": ["Finance"], "x-xos-table": "app.billing_draws", "x-xos-capability": "finance.invoice.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List billing draw rows", "description": "A client billing draw against the project. Returns a cursor page of billing draw rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of billing draw rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "draw_number": 1, "period_end": "2026-10-08", "amount_requested_minor": 5000000, "currency_code": "USD", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BillingDrawPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "billingDraws.create", "tags": ["Finance"], "x-xos-table": "app.billing_draws", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a billing draw", "description": "A client billing draw against the project. Creates a billing draw. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "draw_number": 1, "period_end": "2026-10-08", "amount_requested_minor": 5000000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/BillingDrawCreate" } } } }, "responses": { "201": { "description": "The created billing draw.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "draw_number": 1, "period_end": "2026-10-08", "amount_requested_minor": 5000000, "currency_code": "USD", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/BillingDraw" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/billing-draws/{id}": { "get": { "operationId": "billingDraws.get", "tags": ["Finance"], "x-xos-table": "app.billing_draws", "x-xos-capability": "finance.invoice.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a billing draw", "description": "A client billing draw against the project. Returns one billing draw with its `ETag`. A billing draw the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the billing draw.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the billing draw.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The billing draw.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "draw_number": 1, "period_end": "2026-10-08", "amount_requested_minor": 5000000, "currency_code": "USD", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/BillingDraw" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "billingDraws.update", "tags": ["Finance"], "x-xos-table": "app.billing_draws", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a billing draw", "description": "A client billing draw against the project. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the billing draw.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the billing draw.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "draw_number": 1, "period_end": "2026-10-08", "amount_requested_minor": 5000000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/BillingDrawUpdate" } } } }, "responses": { "200": { "description": "The updated billing draw.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "draw_number": 1, "period_end": "2026-10-08", "amount_requested_minor": 5000000, "currency_code": "USD", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/BillingDraw" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "billingDraws.delete", "tags": ["Finance"], "x-xos-table": "app.billing_draws", "x-xos-capability": "finance.invoice.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Delete a billing draw", "description": "A client billing draw against the project. Soft-deletes the billing draw: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the billing draw.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the billing draw.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The billing draw moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/cost-centers": { "get": { "operationId": "costCenters.list", "tags": ["Finance"], "x-xos-table": "app.cost_centers", "x-xos-capability": "finance.gl.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["code"], "numeric": false }, "summary": "List cost center rows", "description": "A tenant cost center (GL dimension 1), created from canon templates or per event scope. Returns a cursor page of cost center rows the caller may see. The default order is `code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of cost center rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "CC-VENUE", "name": "Event 01 Opening Weekend", "kind": "Standing", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "CC-VENUE" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CostCenterPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "costCenters.create", "tags": ["Finance"], "x-xos-table": "app.cost_centers", "x-xos-capability": "finance.cost_center.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Create a cost center", "description": "A tenant cost center (GL dimension 1), created from canon templates or per event scope. Creates a cost center. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "CC-VENUE", "name": "Event 01 Opening Weekend", "kind": "Standing", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CostCenterCreate" } } } }, "responses": { "201": { "description": "The created cost center.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "CC-VENUE", "name": "Event 01 Opening Weekend", "kind": "Standing", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "CC-VENUE" }, "schema": { "$ref": "#/components/schemas/CostCenter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/cost-centers/{id}": { "get": { "operationId": "costCenters.get", "tags": ["Finance"], "x-xos-table": "app.cost_centers", "x-xos-capability": "finance.gl.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a cost center", "description": "A tenant cost center (GL dimension 1), created from canon templates or per event scope. Returns one cost center with its `ETag`. A cost center the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cost center.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The cost center.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "CC-VENUE", "name": "Event 01 Opening Weekend", "kind": "Standing", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "CC-VENUE" }, "schema": { "$ref": "#/components/schemas/CostCenter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "costCenters.update", "tags": ["Finance"], "x-xos-table": "app.cost_centers", "x-xos-capability": "finance.cost_center.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Update a cost center", "description": "A tenant cost center (GL dimension 1), created from canon templates or per event scope. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cost center.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "CC-VENUE", "name": "Event 01 Opening Weekend", "kind": "Standing", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CostCenterUpdate" } } } }, "responses": { "200": { "description": "The updated cost center.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "code": "CC-VENUE", "name": "Event 01 Opening Weekend", "kind": "Standing", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "CC-VENUE" }, "schema": { "$ref": "#/components/schemas/CostCenter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "costCenters.delete", "tags": ["Finance"], "x-xos-table": "app.cost_centers", "x-xos-capability": "finance.cost_center.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Delete a cost center", "description": "A tenant cost center (GL dimension 1), created from canon templates or per event scope. Soft-deletes the cost center: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cost center.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cost center.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The cost center moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tax-jurisdictions": { "get": { "operationId": "taxJurisdictions.list", "tags": ["Finance"], "x-xos-table": "app.tax_jurisdictions", "x-xos-capability": "finance.gl.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List tax jurisdiction rows", "description": "A tax jurisdiction the org collects or pays tax in. Returns a cursor page of tax jurisdiction rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of tax jurisdiction rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "name": "Florida Sales Tax" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TaxJurisdictionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "taxJurisdictions.create", "tags": ["Finance"], "x-xos-table": "app.tax_jurisdictions", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a tax jurisdiction", "description": "A tax jurisdiction the org collects or pays tax in. Creates a tax jurisdiction. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "jurisdiction_id": "US-FL", "name": "Florida Sales Tax" }, "schema": { "$ref": "#/components/schemas/TaxJurisdictionCreate" } } } }, "responses": { "201": { "description": "The created tax jurisdiction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "name": "Florida Sales Tax" }, "schema": { "$ref": "#/components/schemas/TaxJurisdiction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tax-jurisdictions/{id}": { "get": { "operationId": "taxJurisdictions.get", "tags": ["Finance"], "x-xos-table": "app.tax_jurisdictions", "x-xos-capability": "finance.gl.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a tax jurisdiction", "description": "A tax jurisdiction the org collects or pays tax in. Returns one tax jurisdiction with its `ETag`. A tax jurisdiction the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tax jurisdiction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tax jurisdiction.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The tax jurisdiction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "name": "Florida Sales Tax" }, "schema": { "$ref": "#/components/schemas/TaxJurisdiction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "taxJurisdictions.update", "tags": ["Finance"], "x-xos-table": "app.tax_jurisdictions", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a tax jurisdiction", "description": "A tax jurisdiction the org collects or pays tax in. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tax jurisdiction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tax jurisdiction.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "jurisdiction_id": "US-FL", "name": "Florida Sales Tax" }, "schema": { "$ref": "#/components/schemas/TaxJurisdictionUpdate" } } } }, "responses": { "200": { "description": "The updated tax jurisdiction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "name": "Florida Sales Tax" }, "schema": { "$ref": "#/components/schemas/TaxJurisdiction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "taxJurisdictions.delete", "tags": ["Finance"], "x-xos-table": "app.tax_jurisdictions", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a tax jurisdiction", "description": "A tax jurisdiction the org collects or pays tax in. Soft-deletes the tax jurisdiction: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tax jurisdiction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tax jurisdiction.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The tax jurisdiction moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tax-rates": { "get": { "operationId": "taxRates.list", "tags": ["Finance"], "x-xos-table": "app.tax_rates", "x-xos-capability": "finance.gl.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List tax rate rows", "description": "A tax rate with its effective dates. Returns a cursor page of tax rate rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of tax rate rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_jurisdiction_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_percent": 7, "effective_from": "2026-10-08", "effective_to": "2026-10-08", "tax_type": "Tax on Purchases" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TaxRatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "taxRates.create", "tags": ["Finance"], "x-xos-table": "app.tax_rates", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a tax rate", "description": "A tax rate with its effective dates. Creates a tax rate. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "tax_jurisdiction_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_percent": 7, "effective_from": "2026-10-08", "effective_to": "2026-10-08", "tax_type": "Tax on Purchases" }, "schema": { "$ref": "#/components/schemas/TaxRateCreate" } } } }, "responses": { "201": { "description": "The created tax rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_jurisdiction_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_percent": 7, "effective_from": "2026-10-08", "effective_to": "2026-10-08", "tax_type": "Tax on Purchases" }, "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tax-rates/{id}": { "get": { "operationId": "taxRates.get", "tags": ["Finance"], "x-xos-table": "app.tax_rates", "x-xos-capability": "finance.gl.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Get a tax rate", "description": "A tax rate with its effective dates. Returns one tax rate with its `ETag`. A tax rate the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tax rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tax rate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The tax rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_jurisdiction_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_percent": 7, "effective_from": "2026-10-08", "effective_to": "2026-10-08", "tax_type": "Tax on Purchases" }, "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "taxRates.update", "tags": ["Finance"], "x-xos-table": "app.tax_rates", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a tax rate", "description": "A tax rate with its effective dates. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tax rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tax rate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "rate_percent": 7, "effective_from": "2026-10-08", "effective_to": "2026-10-08", "tax_type": "Tax on Purchases" }, "schema": { "$ref": "#/components/schemas/TaxRateUpdate" } } } }, "responses": { "200": { "description": "The updated tax rate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tax_jurisdiction_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_percent": 7, "effective_from": "2026-10-08", "effective_to": "2026-10-08", "tax_type": "Tax on Purchases" }, "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "taxRates.delete", "tags": ["Finance"], "x-xos-table": "app.tax_rates", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a tax rate", "description": "A tax rate with its effective dates. Soft-deletes the tax rate: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tax rate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tax rate.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The tax rate moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fx-rates": { "get": { "operationId": "fxRates.list", "tags": ["Finance"], "x-xos-table": "app.fx_rates", "x-xos-capability": "finance.gl.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "x-xos-order": { "by": ["effective_on"], "numeric": false }, "summary": "List fx rate rows", "description": "A daily reference exchange rate with its rate date and source. Returns a cursor page of fx rate rows the caller may see. The default order is `effective_on` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of fx rate rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "base_currency": "USD", "quote_currency": "USD", "rate": 0.9213, "effective_on": "2026-10-08", "source": "ECB" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/FxRatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/price-books": { "get": { "operationId": "priceBooks.list", "tags": ["Finance"], "x-xos-table": "app.price_books", "x-xos-capability": "procurement.catalog.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List price book rows", "description": "An org price book for selling items. Returns a cursor page of price book rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of price book rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Standard Client Rates", "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PriceBookPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "priceBooks.create", "tags": ["Finance"], "x-xos-table": "app.price_books", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a price book", "description": "An org price book for selling items. Creates a price book. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Standard Client Rates", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PriceBookCreate" } } } }, "responses": { "201": { "description": "The created price book.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Standard Client Rates", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PriceBook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/price-books/{id}": { "get": { "operationId": "priceBooks.get", "tags": ["Finance"], "x-xos-table": "app.price_books", "x-xos-capability": "procurement.catalog.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a price book", "description": "An org price book for selling items. Returns one price book with its `ETag`. A price book the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the price book.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the price book.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The price book.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Standard Client Rates", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PriceBook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "priceBooks.update", "tags": ["Finance"], "x-xos-table": "app.price_books", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a price book", "description": "An org price book for selling items. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the price book.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the price book.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Standard Client Rates", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PriceBookUpdate" } } } }, "responses": { "200": { "description": "The updated price book.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Standard Client Rates", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/PriceBook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "priceBooks.delete", "tags": ["Finance"], "x-xos-table": "app.price_books", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Delete a price book", "description": "An org price book for selling items. Soft-deletes the price book: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the price book.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the price book.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The price book moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfqs": { "get": { "operationId": "rfqs.list", "tags": ["Procurement"], "x-xos-table": "app.rfqs", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List RFQ rows", "description": "A request for quotation. Responses stay sealed until the deadline. Returns a cursor page of RFQ rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of RFQ rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Main Stage Audio Package", "rfq_state": "Proposed", "rfq_number": 3, "responses_due_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RfqPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "rfqs.create", "tags": ["Procurement"], "x-xos-table": "app.rfqs", "x-xos-capability": "procurement.rfq.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a RFQ", "description": "A request for quotation. Responses stay sealed until the deadline. Creates a RFQ. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Main Stage Audio Package", "responses_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RfqCreate" } } } }, "responses": { "201": { "description": "The created RFQ.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Main Stage Audio Package", "rfq_state": "Proposed", "rfq_number": 3, "responses_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Rfq" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfqs/{id}": { "get": { "operationId": "rfqs.get", "tags": ["Procurement"], "x-xos-table": "app.rfqs", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a RFQ", "description": "A request for quotation. Responses stay sealed until the deadline. Returns one RFQ with its `ETag`. A RFQ the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The RFQ.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Main Stage Audio Package", "rfq_state": "Proposed", "rfq_number": 3, "responses_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Rfq" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "rfqs.update", "tags": ["Procurement"], "x-xos-table": "app.rfqs", "x-xos-capability": "procurement.rfq.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a RFQ", "description": "A request for quotation. Responses stay sealed until the deadline. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Main Stage Audio Package", "responses_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/RfqUpdate" } } } }, "responses": { "200": { "description": "The updated RFQ.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Main Stage Audio Package", "rfq_state": "Proposed", "rfq_number": 3, "responses_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Rfq" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "rfqs.delete", "tags": ["Procurement"], "x-xos-table": "app.rfqs", "x-xos-capability": "procurement.rfq.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Delete a RFQ", "description": "A request for quotation. Responses stay sealed until the deadline. Soft-deletes the RFQ: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The RFQ moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfqs/{id}/issue": { "post": { "operationId": "rfqs.issue", "tags": ["Procurement"], "x-xos-table": "app.rfqs", "x-xos-capability": "procurement.rfq.issue", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Issue an RFQ", "description": "Sends invitations to bid. Responses stay sealed until the deadline. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Main Stage Audio Package", "rfq_state": "Proposed", "rfq_number": 3, "responses_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Rfq" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfqs/{id}/transitions": { "post": { "operationId": "rfqs.transition", "tags": ["Procurement"], "x-xos-table": "app.rfqs", "x-xos-capability": "procurement.rfq.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Transition the rfq state", "description": "Moves the rfq lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Issued", "to_state": "Closed", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/RFQTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Main Stage Audio Package", "rfq_state": "Proposed", "rfq_number": 3, "responses_due_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Rfq" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfq-invitations": { "get": { "operationId": "rfqInvitations.list", "tags": ["Procurement"], "x-xos-table": "app.rfq_invitations", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List RFQ invitation rows", "description": "An invitation to bid on an RFQ. Returns a cursor page of RFQ invitation rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of RFQ invitation rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RfqInvitationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "rfqInvitations.create", "tags": ["Procurement"], "x-xos-table": "app.rfq_invitations", "x-xos-capability": "procurement.rfq.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a RFQ invitation", "description": "An invitation to bid on an RFQ. Creates a RFQ invitation. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RfqInvitationCreate" } } } }, "responses": { "201": { "description": "The created RFQ invitation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RfqInvitation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfq-invitations/{id}": { "get": { "operationId": "rfqInvitations.get", "tags": ["Procurement"], "x-xos-table": "app.rfq_invitations", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a RFQ invitation", "description": "An invitation to bid on an RFQ. Returns one RFQ invitation with its `ETag`. A RFQ invitation the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq invitation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq invitation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The RFQ invitation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RfqInvitation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "rfqInvitations.delete", "tags": ["Procurement"], "x-xos-table": "app.rfq_invitations", "x-xos-capability": "procurement.rfq.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Delete a RFQ invitation", "description": "An invitation to bid on an RFQ. Soft-deletes the RFQ invitation: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq invitation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq invitation.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The RFQ invitation moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfq-responses": { "get": { "operationId": "rfqResponses.list", "tags": ["Procurement"], "x-xos-table": "app.rfq_responses", "x-xos-capability": "procurement.bid.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List RFQ response rows", "description": "A sealed RFQ response. A bidder sees only their own response. Returns a cursor page of RFQ response rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of RFQ response rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_at": "2026-10-08T14:30:00Z", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_until": "2026-10-08" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RfqResponsePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "rfqResponses.create", "tags": ["Procurement"], "x-xos-table": "app.rfq_responses", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-rpc": "app.record_rfq_response", "summary": "Record an RFQ response", "description": "Records a sealed response and its quoted lines in one call (app.record_rfq_response) for a holder of procurement.rfq.write on the project. Only an invited vendor responds while the RFQ is Issued (rfq_not_invited, 422) and a response quotes at least one line (rfq_response_lines_required, 422). Answers 201 with a receipt: the response stays unreadable until the RFQ closes. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_until": "2026-10-08", "currency_code": "USD", "lines": [ { "description": "Line array, 12 boxes per side", "element_id": "0000.01.01-XOS-001", "quantity": 2, "unit_price_minor": 1800000 } ] }, "schema": { "$ref": "#/components/schemas/RfqResponseCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "line_count": 3, "sealed": true }, "schema": { "$ref": "#/components/schemas/RfqResponseReceipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfq-responses/{id}": { "get": { "operationId": "rfqResponses.get", "tags": ["Procurement"], "x-xos-table": "app.rfq_responses", "x-xos-capability": "procurement.bid.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a RFQ response", "description": "A sealed RFQ response. A bidder sees only their own response. Returns one RFQ response with its `ETag`. A RFQ response the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq response.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq response.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The RFQ response.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_at": "2026-10-08T14:30:00Z", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RfqResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfq-response-lines": { "get": { "operationId": "rfqResponseLines.list", "tags": ["Procurement"], "x-xos-table": "app.rfq_response_lines", "x-xos-capability": "procurement.bid.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List RFQ response line rows", "description": "A line of an RFQ response. Returns a cursor page of RFQ response line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of RFQ response line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array, 12 boxes per side", "quantity": 1, "unit_price_minor": 1800000, "currency_code": "USD", "element_id": "0000.01.01-XOS-001" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RfqResponseLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "rfqResponseLines.create", "tags": ["Procurement"], "x-xos-table": "app.rfq_response_lines", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a RFQ response line", "description": "A line of an RFQ response. Creates a RFQ response line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array, 12 boxes per side", "quantity": 1, "unit_price_minor": 1800000, "currency_code": "USD", "element_id": "0000.01.01-XOS-001" }, "schema": { "$ref": "#/components/schemas/RfqResponseLineCreate" } } } }, "responses": { "201": { "description": "The created RFQ response line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array, 12 boxes per side", "quantity": 1, "unit_price_minor": 1800000, "currency_code": "USD", "element_id": "0000.01.01-XOS-001" }, "schema": { "$ref": "#/components/schemas/RfqResponseLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rfq-response-lines/{id}": { "get": { "operationId": "rfqResponseLines.get", "tags": ["Procurement"], "x-xos-table": "app.rfq_response_lines", "x-xos-capability": "procurement.bid.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a RFQ response line", "description": "A line of an RFQ response. Returns one RFQ response line with its `ETag`. A RFQ response line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq response line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq response line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The RFQ response line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array, 12 boxes per side", "quantity": 1, "unit_price_minor": 1800000, "currency_code": "USD", "element_id": "0000.01.01-XOS-001" }, "schema": { "$ref": "#/components/schemas/RfqResponseLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "rfqResponseLines.update", "tags": ["Procurement"], "x-xos-table": "app.rfq_response_lines", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a RFQ response line", "description": "A line of an RFQ response. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq response line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq response line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Line array, 12 boxes per side", "quantity": 1, "unit_price_minor": 1800000, "currency_code": "USD", "element_id": "0000.01.01-XOS-001" }, "schema": { "$ref": "#/components/schemas/RfqResponseLineUpdate" } } } }, "responses": { "200": { "description": "The updated RFQ response line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array, 12 boxes per side", "quantity": 1, "unit_price_minor": 1800000, "currency_code": "USD", "element_id": "0000.01.01-XOS-001" }, "schema": { "$ref": "#/components/schemas/RfqResponseLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "rfqResponseLines.delete", "tags": ["Procurement"], "x-xos-table": "app.rfq_response_lines", "x-xos-capability": "procurement.rfq.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Delete a RFQ response line", "description": "A line of an RFQ response. Soft-deletes the RFQ response line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rfq response line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rfq response line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The RFQ response line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/purchase-orders": { "get": { "operationId": "purchaseOrders.list", "tags": ["Procurement"], "x-xos-table": "app.purchase_orders", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List purchase order rows", "description": "A purchase order. Its creator cannot approve it; spend authority applies inside the approval RPC. Returns a cursor page of purchase order rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of purchase order rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_number": 7, "currency_code": "USD", "po_state": "Proposed", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000, "sent_at": "2026-10-08T14:30:00Z", "invoiced_minor": 1250000, "paid_minor": 600000 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PurchaseOrderPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "purchaseOrders.create", "tags": ["Procurement"], "x-xos-table": "app.purchase_orders", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a purchase order", "description": "A purchase order. Its creator cannot approve it; spend authority applies inside the approval RPC. Creates a purchase order. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "currency_code": "USD", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrderCreate" } } } }, "responses": { "201": { "description": "The created purchase order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_number": 7, "currency_code": "USD", "po_state": "Proposed", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000, "sent_at": "2026-10-08T14:30:00Z", "invoiced_minor": 1250000, "paid_minor": 600000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/purchase-orders/{id}": { "get": { "operationId": "purchaseOrders.get", "tags": ["Procurement"], "x-xos-table": "app.purchase_orders", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a purchase order", "description": "A purchase order. Its creator cannot approve it; spend authority applies inside the approval RPC. Returns one purchase order with its `ETag`. A purchase order the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the purchase order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The purchase order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_number": 7, "currency_code": "USD", "po_state": "Proposed", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000, "sent_at": "2026-10-08T14:30:00Z", "invoiced_minor": 1250000, "paid_minor": 600000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "purchaseOrders.update", "tags": ["Procurement"], "x-xos-table": "app.purchase_orders", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a purchase order", "description": "A purchase order. Its creator cannot approve it; spend authority applies inside the approval RPC. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the purchase order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrderUpdate" } } } }, "responses": { "200": { "description": "The updated purchase order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_number": 7, "currency_code": "USD", "po_state": "Proposed", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000, "sent_at": "2026-10-08T14:30:00Z", "invoiced_minor": 1250000, "paid_minor": 600000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/purchase-orders/{id}/approve": { "post": { "operationId": "purchaseOrders.approve", "tags": ["Procurement"], "x-xos-table": "app.purchase_orders", "x-xos-capability": "finance.po.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Approve a purchase order", "description": "Records an approval through app.approve_purchase_order: finance.po.approve on the project, never by the order's creator (sod_po_creator), fully priced, within spend authority. Above the dual threshold the order stays Proposed until a second approver approves; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the purchase order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Within budget." }, "schema": { "$ref": "#/components/schemas/PurchaseOrderApproveRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_number": 7, "currency_code": "USD", "po_state": "Proposed", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000, "sent_at": "2026-10-08T14:30:00Z", "invoiced_minor": 1250000, "paid_minor": 600000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/purchase-orders/{id}/transitions": { "post": { "operationId": "purchaseOrders.transition", "tags": ["Procurement"], "x-xos-table": "app.purchase_orders", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Transition the purchase order state", "description": "Moves the purchase order lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the purchase order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Approved", "to_state": "Sent", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/PurchaseOrderTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_number": 7, "currency_code": "USD", "po_state": "Proposed", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000, "sent_at": "2026-10-08T14:30:00Z", "invoiced_minor": 1250000, "paid_minor": 600000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/purchase-orders/{id}/acknowledge": { "post": { "operationId": "purchaseOrders.acknowledge", "tags": ["Procurement"], "x-xos-table": "app.purchase_orders", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Acknowledge a purchase order", "description": "Records the vendor's acknowledgment of the purchase order. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the purchase order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the purchase order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_number": 7, "currency_code": "USD", "po_state": "Proposed", "rfq_response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_due_on": "2026-10-08", "payment_terms_days": 30, "tax_minor": 4200, "shipping_minor": 15000, "sent_at": "2026-10-08T14:30:00Z", "invoiced_minor": 1250000, "paid_minor": 600000 }, "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/po-lines": { "get": { "operationId": "poLines.list", "tags": ["Procurement"], "x-xos-table": "app.po_lines", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List PO line rows", "description": "A purchase order line. Returns a cursor page of PO line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of PO line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PoLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "poLines.create", "tags": ["Procurement"], "x-xos-table": "app.po_lines", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a PO line", "description": "A purchase order line. Creates a PO line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1 }, "schema": { "$ref": "#/components/schemas/PoLineCreate" } } } }, "responses": { "201": { "description": "The created PO line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1 }, "schema": { "$ref": "#/components/schemas/PoLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/po-lines/{id}": { "get": { "operationId": "poLines.get", "tags": ["Procurement"], "x-xos-table": "app.po_lines", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a PO line", "description": "A purchase order line. Returns one PO line with its `ETag`. A PO line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the po line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the po line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The PO line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1 }, "schema": { "$ref": "#/components/schemas/PoLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "poLines.update", "tags": ["Procurement"], "x-xos-table": "app.po_lines", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a PO line", "description": "A purchase order line. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the po line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the po line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1 }, "schema": { "$ref": "#/components/schemas/PoLineUpdate" } } } }, "responses": { "200": { "description": "The updated PO line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "budget_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "description": "Stage deck rental", "quantity": 24, "unit_basis": "each", "unit_price_minor": 4500, "line_number": 1 }, "schema": { "$ref": "#/components/schemas/PoLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "poLines.delete", "tags": ["Procurement"], "x-xos-table": "app.po_lines", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Delete a PO line", "description": "A purchase order line. Soft-deletes the PO line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the po line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the po line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The PO line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/po-change-orders": { "get": { "operationId": "poChangeOrders.list", "tags": ["Procurement"], "x-xos-table": "app.po_change_orders", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List PO change order rows", "description": "A change to an issued purchase order. Returns a cursor page of PO change order rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of PO change order rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Add six deck sections.", "amount_delta_minor": 27000, "po_change_order_state": "Proposed" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PoChangeOrderPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "poChangeOrders.create", "tags": ["Procurement"], "x-xos-table": "app.po_change_orders", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a PO change order", "description": "A change to an issued purchase order. Creates a PO change order. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Add six deck sections.", "amount_delta_minor": 27000 }, "schema": { "$ref": "#/components/schemas/PoChangeOrderCreate" } } } }, "responses": { "201": { "description": "The created PO change order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Add six deck sections.", "amount_delta_minor": 27000, "po_change_order_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/PoChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/po-change-orders/{id}": { "get": { "operationId": "poChangeOrders.get", "tags": ["Procurement"], "x-xos-table": "app.po_change_orders", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a PO change order", "description": "A change to an issued purchase order. Returns one PO change order with its `ETag`. A PO change order the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the po change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the po change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The PO change order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Add six deck sections.", "amount_delta_minor": 27000, "po_change_order_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/PoChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "poChangeOrders.update", "tags": ["Procurement"], "x-xos-table": "app.po_change_orders", "x-xos-capability": "procurement.po.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a PO change order", "description": "A change to an issued purchase order. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the po change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the po change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Add six deck sections.", "amount_delta_minor": 27000 }, "schema": { "$ref": "#/components/schemas/PoChangeOrderUpdate" } } } }, "responses": { "200": { "description": "The updated PO change order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Add six deck sections.", "amount_delta_minor": 27000, "po_change_order_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/PoChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/po-change-orders/{id}/approve": { "post": { "operationId": "poChangeOrders.approve", "tags": ["Procurement"], "x-xos-table": "app.po_change_orders", "x-xos-capability": "finance.po.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Approve a PO change order", "description": "Approves a priced, Proposed PO change order through app.decide_po_change_order under spend authority. Its requester cannot approve it; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the po change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the po change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Within budget." }, "schema": { "$ref": "#/components/schemas/PoChangeOrderApproveRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Add six deck sections.", "amount_delta_minor": 27000, "po_change_order_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/PoChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/po-change-orders/{id}/reject": { "post": { "operationId": "poChangeOrders.reject", "tags": ["Procurement"], "x-xos-table": "app.po_change_orders", "x-xos-capability": "finance.po.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Reject a PO change order", "description": "Rejects a Proposed PO change order through app.decide_po_change_order. Its requester cannot decide it; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the po change order.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the po change order.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Within budget." }, "schema": { "$ref": "#/components/schemas/PoChangeOrderRejectRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Add six deck sections.", "amount_delta_minor": 27000, "po_change_order_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/PoChangeOrder" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/goods-receipts": { "get": { "operationId": "goodsReceipts.list", "tags": ["Procurement"], "x-xos-table": "app.goods_receipts", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List goods receipt rows", "description": "A goods receipt against a purchase order. Duplicate receipts are refused. Returns a cursor page of goods receipt rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of goods receipt rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "received_at": "2026-10-08T14:30:00Z", "received_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Two cases dented." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/GoodsReceiptPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "goodsReceipts.create", "tags": ["Procurement"], "x-xos-table": "app.goods_receipts", "x-xos-capability": "procurement.receipt.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a goods receipt", "description": "A goods receipt against a purchase order. Duplicate receipts are refused. Creates a goods receipt. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "received_at": "2026-10-08T14:30:00Z", "note": "Two cases dented." }, "schema": { "$ref": "#/components/schemas/GoodsReceiptCreate" } } } }, "responses": { "201": { "description": "The created goods receipt.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "received_at": "2026-10-08T14:30:00Z", "received_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Two cases dented." }, "schema": { "$ref": "#/components/schemas/GoodsReceipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/goods-receipts/{id}": { "get": { "operationId": "goodsReceipts.get", "tags": ["Procurement"], "x-xos-table": "app.goods_receipts", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a goods receipt", "description": "A goods receipt against a purchase order. Duplicate receipts are refused. Returns one goods receipt with its `ETag`. A goods receipt the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the goods receipt.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the goods receipt.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The goods receipt.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "received_at": "2026-10-08T14:30:00Z", "received_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Two cases dented." }, "schema": { "$ref": "#/components/schemas/GoodsReceipt" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/receipt-lines": { "get": { "operationId": "receiptLines.list", "tags": ["Procurement"], "x-xos-table": "app.receipt_lines", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List receipt line rows", "description": "A received quantity against a PO line. Returns a cursor page of receipt line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of receipt line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity_received": 24 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReceiptLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "receiptLines.create", "tags": ["Procurement"], "x-xos-table": "app.receipt_lines", "x-xos-capability": "procurement.receipt.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a receipt line", "description": "A received quantity against a PO line. Creates a receipt line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity_received": 24 }, "schema": { "$ref": "#/components/schemas/ReceiptLineCreate" } } } }, "responses": { "201": { "description": "The created receipt line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity_received": 24 }, "schema": { "$ref": "#/components/schemas/ReceiptLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/receipt-lines/{id}": { "get": { "operationId": "receiptLines.get", "tags": ["Procurement"], "x-xos-table": "app.receipt_lines", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a receipt line", "description": "A received quantity against a PO line. Returns one receipt line with its `ETag`. A receipt line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the receipt line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the receipt line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The receipt line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "po_line_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "quantity_received": 24 }, "schema": { "$ref": "#/components/schemas/ReceiptLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoice-matches": { "get": { "operationId": "invoiceMatches.list", "tags": ["Procurement"], "x-xos-table": "app.invoice_matches", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List three-way match rows", "description": "A three-way match of PO, receipt and invoice. A mismatch is never auto-approved. Returns a cursor page of three-way match rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of three-way match rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "matched": true, "variance_minor": 2000, "resolution_note": "Freight surcharge agreed.", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "resolved_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InvoiceMatchPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "invoiceMatches.create", "tags": ["Procurement"], "x-xos-table": "app.invoice_matches", "x-xos-capability": "procurement.invoice_match.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a three-way match", "description": "A three-way match of PO, receipt and invoice. A mismatch is never auto-approved. Creates a three-way match. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/InvoiceMatchCreate" } } } }, "responses": { "201": { "description": "The created three-way match.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "matched": true, "variance_minor": 2000, "resolution_note": "Freight surcharge agreed.", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "resolved_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/InvoiceMatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoice-matches/{id}": { "get": { "operationId": "invoiceMatches.get", "tags": ["Procurement"], "x-xos-table": "app.invoice_matches", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a three-way match", "description": "A three-way match of PO, receipt and invoice. A mismatch is never auto-approved. Returns one three-way match with its `ETag`. A three-way match the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice match.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice match.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The three-way match.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "matched": true, "variance_minor": 2000, "resolution_note": "Freight surcharge agreed.", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "resolved_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/InvoiceMatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoice-matches/{id}/resolve": { "post": { "operationId": "invoiceMatches.resolve", "tags": ["Procurement"], "x-xos-table": "app.invoice_matches", "x-xos-capability": "procurement.invoice_match.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Accept an invoice mismatch", "description": "Records why a mismatch is accepted. Only someone other than the person who recorded the match may accept it, once; a refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invoice match.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invoice match.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "resolution_note": "Freight surcharge agreed by phone." }, "schema": { "$ref": "#/components/schemas/InvoiceMatchResolveRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invoice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purchase_order_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "goods_receipt_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "matched": true, "variance_minor": 2000, "resolution_note": "Freight surcharge agreed.", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "resolved_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/InvoiceMatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/catalog-bindings": { "get": { "operationId": "catalogBindings.list", "tags": ["Procurement"], "x-xos-table": "app.catalog_bindings", "x-xos-capability": "procurement.catalog.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List catalog binding rows", "description": "A tenant item bound to a canon element. Returns a cursor page of catalog binding rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of catalog binding rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "item_id": "0000.01.01-NORTHW-001", "name": "4x8 Stage Deck", "unit_basis": "ea", "default_unit_price_minor": 4500, "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CatalogBindingPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "catalogBindings.create", "tags": ["Procurement"], "x-xos-table": "app.catalog_bindings", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a catalog binding", "description": "A tenant item bound to a canon element. Creates a catalog binding. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "element_id": "4000.01.01-XPMS-001", "name": "4x8 Stage Deck", "unit_basis": "ea", "default_unit_price_minor": 4500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/CatalogBindingCreate" } } } }, "responses": { "201": { "description": "The created catalog binding.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "item_id": "0000.01.01-NORTHW-001", "name": "4x8 Stage Deck", "unit_basis": "ea", "default_unit_price_minor": 4500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/CatalogBinding" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/catalog-bindings/{id}": { "get": { "operationId": "catalogBindings.get", "tags": ["Procurement"], "x-xos-table": "app.catalog_bindings", "x-xos-capability": "procurement.catalog.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a catalog binding", "description": "A tenant item bound to a canon element. Returns one catalog binding with its `ETag`. A catalog binding the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the catalog binding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the catalog binding.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The catalog binding.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "item_id": "0000.01.01-NORTHW-001", "name": "4x8 Stage Deck", "unit_basis": "ea", "default_unit_price_minor": 4500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/CatalogBinding" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "catalogBindings.update", "tags": ["Procurement"], "x-xos-table": "app.catalog_bindings", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a catalog binding", "description": "A tenant item bound to a canon element. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the catalog binding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the catalog binding.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "4x8 Stage Deck", "unit_basis": "ea", "default_unit_price_minor": 4500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/CatalogBindingUpdate" } } } }, "responses": { "200": { "description": "The updated catalog binding.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "item_id": "0000.01.01-NORTHW-001", "name": "4x8 Stage Deck", "unit_basis": "ea", "default_unit_price_minor": 4500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/CatalogBinding" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "catalogBindings.delete", "tags": ["Procurement"], "x-xos-table": "app.catalog_bindings", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Delete a catalog binding", "description": "A tenant item bound to a canon element. Soft-deletes the catalog binding: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the catalog binding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the catalog binding.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The catalog binding moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-products": { "get": { "operationId": "vendorProducts.list", "tags": ["Procurement"], "x-xos-table": "app.vendor_products", "x-xos-capability": "procurement.catalog.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List vendor product rows", "description": "A product a vendor offers, optionally bound to an element. Returns a cursor page of vendor product rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of vendor product rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "unit_price_minor": 4500, "currency_code": "USD", "vendor_sku": "DSS-DECK-0408", "catalog_binding_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lead_time_days": 14 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VendorProductPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "vendorProducts.create", "tags": ["Procurement"], "x-xos-table": "app.vendor_products", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Create a vendor product", "description": "A product a vendor offers, optionally bound to an element. Creates a vendor product. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "unit_price_minor": 4500, "currency_code": "USD", "vendor_sku": "DSS-DECK-0408", "catalog_binding_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lead_time_days": 14 }, "schema": { "$ref": "#/components/schemas/VendorProductCreate" } } } }, "responses": { "201": { "description": "The created vendor product.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "unit_price_minor": 4500, "currency_code": "USD", "vendor_sku": "DSS-DECK-0408", "catalog_binding_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lead_time_days": 14 }, "schema": { "$ref": "#/components/schemas/VendorProduct" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-products/{id}": { "get": { "operationId": "vendorProducts.get", "tags": ["Procurement"], "x-xos-table": "app.vendor_products", "x-xos-capability": "procurement.catalog.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Get a vendor product", "description": "A product a vendor offers, optionally bound to an element. Returns one vendor product with its `ETag`. A vendor product the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor product.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor product.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The vendor product.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "unit_price_minor": 4500, "currency_code": "USD", "vendor_sku": "DSS-DECK-0408", "catalog_binding_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lead_time_days": 14 }, "schema": { "$ref": "#/components/schemas/VendorProduct" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "vendorProducts.update", "tags": ["Procurement"], "x-xos-table": "app.vendor_products", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Update a vendor product", "description": "A product a vendor offers, optionally bound to an element. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor product.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor product.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "element_id": "4000.01.01-XPMS-001", "unit_price_minor": 4500, "currency_code": "USD", "vendor_sku": "DSS-DECK-0408", "catalog_binding_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lead_time_days": 14 }, "schema": { "$ref": "#/components/schemas/VendorProductUpdate" } } } }, "responses": { "200": { "description": "The updated vendor product.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "element_id": "4000.01.01-XPMS-001", "unit_price_minor": 4500, "currency_code": "USD", "vendor_sku": "DSS-DECK-0408", "catalog_binding_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lead_time_days": 14 }, "schema": { "$ref": "#/components/schemas/VendorProduct" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "vendorProducts.delete", "tags": ["Procurement"], "x-xos-table": "app.vendor_products", "x-xos-capability": "procurement.catalog.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "Delete a vendor product", "description": "A product a vendor offers, optionally bound to an element. Soft-deletes the vendor product: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor product.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor product.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The vendor product moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendors": { "get": { "operationId": "vendors.list", "tags": ["Vendors"], "x-xos-table": "app.vendors", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List vendor rows", "description": "An organization in the vendor relationship with this org, with its counterparty type. Returns a cursor page of vendor rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of vendor rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator", "vendor_state": "Prospect", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payment_terms_days": 30, "default_currency_code": "USD", "default_account_code": "5400", "default_cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bank_account_last4": "4321" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VendorPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "vendors.create", "tags": ["Vendors"], "x-xos-table": "app.vendors", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create a vendor", "description": "An organization in the vendor relationship with this org, with its counterparty type. Creates a vendor. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payment_terms_days": 30, "default_currency_code": "USD", "default_account_code": "5400", "default_cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/VendorCreate" } } } }, "responses": { "201": { "description": "The created vendor.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator", "vendor_state": "Prospect", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payment_terms_days": 30, "default_currency_code": "USD", "default_account_code": "5400", "default_cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bank_account_last4": "4321" }, "schema": { "$ref": "#/components/schemas/Vendor" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendors/{id}": { "get": { "operationId": "vendors.get", "tags": ["Vendors"], "x-xos-table": "app.vendors", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get a vendor", "description": "An organization in the vendor relationship with this org, with its counterparty type. Returns one vendor with its `ETag`. A vendor the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The vendor.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator", "vendor_state": "Prospect", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payment_terms_days": 30, "default_currency_code": "USD", "default_account_code": "5400", "default_cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bank_account_last4": "4321" }, "schema": { "$ref": "#/components/schemas/Vendor" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "vendors.update", "tags": ["Vendors"], "x-xos-table": "app.vendors", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update a vendor", "description": "An organization in the vendor relationship with this org, with its counterparty type. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "payment_terms_days": 30, "default_currency_code": "USD", "default_account_code": "5400", "default_cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/VendorUpdate" } } } }, "responses": { "200": { "description": "The updated vendor.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator", "vendor_state": "Prospect", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payment_terms_days": 30, "default_currency_code": "USD", "default_account_code": "5400", "default_cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bank_account_last4": "4321" }, "schema": { "$ref": "#/components/schemas/Vendor" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "vendors.delete", "tags": ["Vendors"], "x-xos-table": "app.vendors", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete a vendor", "description": "An organization in the vendor relationship with this org, with its counterparty type. Soft-deletes the vendor: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The vendor moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendors/{id}/transitions": { "post": { "operationId": "vendors.transition", "tags": ["Vendors"], "x-xos-table": "app.vendors", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Transition the vendor state", "description": "Moves the vendor lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Prospect", "to_state": "Onboarded", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/VendorTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator", "vendor_state": "Prospect", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payment_terms_days": 30, "default_currency_code": "USD", "default_account_code": "5400", "default_cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bank_account_last4": "4321" }, "schema": { "$ref": "#/components/schemas/Vendor" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-classes": { "get": { "operationId": "vendorClasses.list", "tags": ["Vendors"], "x-xos-table": "app.vendor_classes", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List vendor class rows", "description": "An org vendor class, seeded from the Standard Library. Returns a cursor page of vendor class rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of vendor class rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Staging", "std_vendor_class_id": "VC-001", "description": "Staging rental houses." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VendorClassPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "vendorClasses.create", "tags": ["Vendors"], "x-xos-table": "app.vendor_classes", "x-xos-capability": "vendors.class.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create a vendor class", "description": "An org vendor class, seeded from the Standard Library. Creates a vendor class. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Staging", "std_vendor_class_id": "VC-001", "description": "Staging rental houses." }, "schema": { "$ref": "#/components/schemas/VendorClassCreate" } } } }, "responses": { "201": { "description": "The created vendor class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Staging", "std_vendor_class_id": "VC-001", "description": "Staging rental houses." }, "schema": { "$ref": "#/components/schemas/VendorClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-classes/{id}": { "get": { "operationId": "vendorClasses.get", "tags": ["Vendors"], "x-xos-table": "app.vendor_classes", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get a vendor class", "description": "An org vendor class, seeded from the Standard Library. Returns one vendor class with its `ETag`. A vendor class the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor class.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The vendor class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Staging", "std_vendor_class_id": "VC-001", "description": "Staging rental houses." }, "schema": { "$ref": "#/components/schemas/VendorClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "vendorClasses.update", "tags": ["Vendors"], "x-xos-table": "app.vendor_classes", "x-xos-capability": "vendors.class.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update a vendor class", "description": "An org vendor class, seeded from the Standard Library. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor class.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Staging", "std_vendor_class_id": "VC-001", "description": "Staging rental houses." }, "schema": { "$ref": "#/components/schemas/VendorClassUpdate" } } } }, "responses": { "200": { "description": "The updated vendor class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Staging", "std_vendor_class_id": "VC-001", "description": "Staging rental houses." }, "schema": { "$ref": "#/components/schemas/VendorClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "vendorClasses.delete", "tags": ["Vendors"], "x-xos-table": "app.vendor_classes", "x-xos-capability": "vendors.class.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete a vendor class", "description": "An org vendor class, seeded from the Standard Library. Soft-deletes the vendor class: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor class.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The vendor class moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-class-assignments": { "get": { "operationId": "vendorClassAssignments.list", "tags": ["Vendors"], "x-xos-table": "app.vendor_class_assignments", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List vendor class assignment rows", "description": "A vendor placed in a vendor class. Returns a cursor page of vendor class assignment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of vendor class assignment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VendorClassAssignmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "vendorClassAssignments.create", "tags": ["Vendors"], "x-xos-table": "app.vendor_class_assignments", "x-xos-capability": "vendors.class.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create a vendor class assignment", "description": "A vendor placed in a vendor class. Creates a vendor class assignment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/VendorClassAssignmentCreate" } } } }, "responses": { "201": { "description": "The created vendor class assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/VendorClassAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-class-assignments/{id}": { "get": { "operationId": "vendorClassAssignments.get", "tags": ["Vendors"], "x-xos-table": "app.vendor_class_assignments", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get a vendor class assignment", "description": "A vendor placed in a vendor class. Returns one vendor class assignment with its `ETag`. A vendor class assignment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor class assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The vendor class assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_class_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/VendorClassAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "vendorClassAssignments.delete", "tags": ["Vendors"], "x-xos-table": "app.vendor_class_assignments", "x-xos-capability": "vendors.class.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete a vendor class assignment", "description": "A vendor placed in a vendor class. Soft-deletes the vendor class assignment: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor class assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor class assignment.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The vendor class assignment moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/prequalifications": { "get": { "operationId": "prequalifications.list", "tags": ["Vendors"], "x-xos-table": "app.prequalifications", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List prequalification rows", "description": "A vendor prequalification. Returns a cursor page of prequalification rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of prequalification rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08", "scope_note": "Rigging over 2,000 kg.", "decision": "Approved", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PrequalificationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "prequalifications.create", "tags": ["Vendors"], "x-xos-table": "app.prequalifications", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create a prequalification", "description": "A vendor prequalification. Creates a prequalification. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08", "scope_note": "Rigging over 2,000 kg." }, "schema": { "$ref": "#/components/schemas/PrequalificationCreate" } } } }, "responses": { "201": { "description": "The created prequalification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08", "scope_note": "Rigging over 2,000 kg.", "decision": "Approved", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Prequalification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/prequalifications/{id}": { "get": { "operationId": "prequalifications.get", "tags": ["Vendors"], "x-xos-table": "app.prequalifications", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get a prequalification", "description": "A vendor prequalification. Returns one prequalification with its `ETag`. A prequalification the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the prequalification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the prequalification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The prequalification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08", "scope_note": "Rigging over 2,000 kg.", "decision": "Approved", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Prequalification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "prequalifications.update", "tags": ["Vendors"], "x-xos-table": "app.prequalifications", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update a prequalification", "description": "A vendor prequalification. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the prequalification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the prequalification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_to": "2026-10-08", "scope_note": "Rigging over 2,000 kg." }, "schema": { "$ref": "#/components/schemas/PrequalificationUpdate" } } } }, "responses": { "200": { "description": "The updated prequalification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08", "scope_note": "Rigging over 2,000 kg.", "decision": "Approved", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Prequalification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "prequalifications.delete", "tags": ["Vendors"], "x-xos-table": "app.prequalifications", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete a prequalification", "description": "A vendor prequalification. Soft-deletes the prequalification: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the prequalification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the prequalification.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The prequalification moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/prequalifications/{id}/decide": { "post": { "operationId": "prequalifications.decide", "tags": ["Vendors"], "x-xos-table": "app.prequalifications", "x-xos-capability": "vendors.prequalification.approve", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Decide a prequalification", "description": "Approves or rejects a pending prequalification through app.decide_prequalification: vendors.prequalification.approve, never by the requester, final once decided. A refusal returns 422 and names the rule. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the prequalification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the prequalification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "decision": "Approved", "valid_to": "2027-12-31" }, "schema": { "$ref": "#/components/schemas/PrequalificationDecideRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08", "scope_note": "Rigging over 2,000 kg.", "decision": "Approved", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Prequalification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/insurance-certificates": { "get": { "operationId": "insuranceCertificates.list", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificates", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List insurance certificate rows", "description": "A certificate of insurance naming the required additional insureds. Returns a cursor page of insurance certificate rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of insurance certificate rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "coverage_type": "General Liability", "coverage_limit_minor": 100000000, "currency_code": "USD", "valid_to": "2026-10-08", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurer": "Example Mutual", "policy_identifier": "GL-2027-0042", "valid_from": "2026-10-08", "document_uri": "https://northwindlive.example/files/site-plan.pdf" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InsuranceCertificatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "insuranceCertificates.create", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificates", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create an insurance certificate", "description": "A certificate of insurance naming the required additional insureds. Creates an insurance certificate. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "coverage_type": "General Liability", "coverage_limit_minor": 100000000, "currency_code": "USD", "valid_to": "2026-10-08", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurer": "Example Mutual", "policy_identifier": "GL-2027-0042", "valid_from": "2026-10-08", "document_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateCreate" } } } }, "responses": { "201": { "description": "The created insurance certificate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "coverage_type": "General Liability", "coverage_limit_minor": 100000000, "currency_code": "USD", "valid_to": "2026-10-08", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurer": "Example Mutual", "policy_identifier": "GL-2027-0042", "valid_from": "2026-10-08", "document_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/insurance-certificates/{id}": { "get": { "operationId": "insuranceCertificates.get", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificates", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get an insurance certificate", "description": "A certificate of insurance naming the required additional insureds. Returns one insurance certificate with its `ETag`. A insurance certificate the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the insurance certificate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The insurance certificate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "coverage_type": "General Liability", "coverage_limit_minor": 100000000, "currency_code": "USD", "valid_to": "2026-10-08", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurer": "Example Mutual", "policy_identifier": "GL-2027-0042", "valid_from": "2026-10-08", "document_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "insuranceCertificates.update", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificates", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update an insurance certificate", "description": "A certificate of insurance naming the required additional insureds. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the insurance certificate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "coverage_type": "General Liability", "coverage_limit_minor": 100000000, "currency_code": "USD", "valid_to": "2026-10-08", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurer": "Example Mutual", "policy_identifier": "GL-2027-0042", "valid_from": "2026-10-08", "document_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateUpdate" } } } }, "responses": { "200": { "description": "The updated insurance certificate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "coverage_type": "General Liability", "coverage_limit_minor": 100000000, "currency_code": "USD", "valid_to": "2026-10-08", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurer": "Example Mutual", "policy_identifier": "GL-2027-0042", "valid_from": "2026-10-08", "document_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "insuranceCertificates.delete", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificates", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete an insurance certificate", "description": "A certificate of insurance naming the required additional insureds. Soft-deletes the insurance certificate: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the insurance certificate.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The insurance certificate moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-scorecards": { "get": { "operationId": "vendorScorecards.list", "tags": ["Vendors"], "x-xos-table": "app.vendor_scorecards", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List vendor scorecard rows", "description": "A vendor scorecard for an engagement or project. Returns a cursor page of vendor scorecard rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of vendor scorecard rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "On time; one damaged deck.", "period_end": "2026-10-08", "quality_score": 4, "delivery_score": 4, "safety_score": 4 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VendorScorecardPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "vendorScorecards.create", "tags": ["Vendors"], "x-xos-table": "app.vendor_scorecards", "x-xos-capability": "vendors.scorecard.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create a vendor scorecard", "description": "A vendor scorecard for an engagement or project. Creates a vendor scorecard. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "On time; one damaged deck.", "period_end": "2026-10-08", "quality_score": 4, "delivery_score": 4, "safety_score": 4 }, "schema": { "$ref": "#/components/schemas/VendorScorecardCreate" } } } }, "responses": { "201": { "description": "The created vendor scorecard.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "On time; one damaged deck.", "period_end": "2026-10-08", "quality_score": 4, "delivery_score": 4, "safety_score": 4 }, "schema": { "$ref": "#/components/schemas/VendorScorecard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vendor-scorecards/{id}": { "get": { "operationId": "vendorScorecards.get", "tags": ["Vendors"], "x-xos-table": "app.vendor_scorecards", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get a vendor scorecard", "description": "A vendor scorecard for an engagement or project. Returns one vendor scorecard with its `ETag`. A vendor scorecard the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor scorecard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor scorecard.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The vendor scorecard.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "On time; one damaged deck.", "period_end": "2026-10-08", "quality_score": 4, "delivery_score": 4, "safety_score": 4 }, "schema": { "$ref": "#/components/schemas/VendorScorecard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "vendorScorecards.update", "tags": ["Vendors"], "x-xos-table": "app.vendor_scorecards", "x-xos-capability": "vendors.scorecard.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update a vendor scorecard", "description": "A vendor scorecard for an engagement or project. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor scorecard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor scorecard.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "On time; one damaged deck.", "period_end": "2026-10-08", "quality_score": 4, "delivery_score": 4, "safety_score": 4 }, "schema": { "$ref": "#/components/schemas/VendorScorecardUpdate" } } } }, "responses": { "200": { "description": "The updated vendor scorecard.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "vendor_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "On time; one damaged deck.", "period_end": "2026-10-08", "quality_score": 4, "delivery_score": 4, "safety_score": 4 }, "schema": { "$ref": "#/components/schemas/VendorScorecard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "vendorScorecards.delete", "tags": ["Vendors"], "x-xos-table": "app.vendor_scorecards", "x-xos-capability": "vendors.scorecard.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete a vendor scorecard", "description": "A vendor scorecard for an engagement or project. Soft-deletes the vendor scorecard: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the vendor scorecard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the vendor scorecard.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The vendor scorecard moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sponsor-entitlements": { "get": { "operationId": "sponsorEntitlements.list", "tags": ["Vendors"], "x-xos-table": "app.sponsor_entitlements", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List sponsor entitlement rows", "description": "A sponsor entitlement with fulfillment tracking. Returns a cursor page of sponsor entitlement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of sponsor entitlement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Logo on the main stage scrims.", "quantity": 12, "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "fulfilled_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SponsorEntitlementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sponsorEntitlements.create", "tags": ["Vendors"], "x-xos-table": "app.sponsor_entitlements", "x-xos-capability": "vendors.entitlement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create a sponsor entitlement", "description": "A sponsor entitlement with fulfillment tracking. Creates a sponsor entitlement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Logo on the main stage scrims.", "quantity": 12, "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/SponsorEntitlementCreate" } } } }, "responses": { "201": { "description": "The created sponsor entitlement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Logo on the main stage scrims.", "quantity": 12, "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SponsorEntitlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sponsor-entitlements/{id}": { "get": { "operationId": "sponsorEntitlements.get", "tags": ["Vendors"], "x-xos-table": "app.sponsor_entitlements", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get a sponsor entitlement", "description": "A sponsor entitlement with fulfillment tracking. Returns one sponsor entitlement with its `ETag`. A sponsor entitlement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor entitlement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sponsor entitlement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The sponsor entitlement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Logo on the main stage scrims.", "quantity": 12, "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SponsorEntitlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "sponsorEntitlements.update", "tags": ["Vendors"], "x-xos-table": "app.sponsor_entitlements", "x-xos-capability": "vendors.entitlement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update a sponsor entitlement", "description": "A sponsor entitlement with fulfillment tracking. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor entitlement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sponsor entitlement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Logo on the main stage scrims.", "quantity": 12, "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/SponsorEntitlementUpdate" } } } }, "responses": { "200": { "description": "The updated sponsor entitlement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Logo on the main stage scrims.", "quantity": 12, "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SponsorEntitlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "sponsorEntitlements.delete", "tags": ["Vendors"], "x-xos-table": "app.sponsor_entitlements", "x-xos-capability": "vendors.entitlement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete a sponsor entitlement", "description": "A sponsor entitlement with fulfillment tracking. Soft-deletes the sponsor entitlement: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor entitlement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sponsor entitlement.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The sponsor entitlement moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sponsor-entitlements/{id}/fulfill": { "post": { "operationId": "sponsorEntitlements.fulfill", "tags": ["Vendors"], "x-xos-table": "app.sponsor_entitlements", "x-xos-capability": "vendors.entitlement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Mark an entitlement fulfilled", "description": "Stamps `fulfilled_at` now. Needs vendors.entitlement.write on the project. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor entitlement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sponsor entitlement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Logo on the main stage scrims.", "quantity": 12, "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SponsorEntitlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sponsor-entitlements/{id}/reopen": { "post": { "operationId": "sponsorEntitlements.reopen", "tags": ["Vendors"], "x-xos-table": "app.sponsor_entitlements", "x-xos-capability": "vendors.entitlement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Mark an entitlement owed again", "description": "Clears `fulfilled_at`. Needs vendors.entitlement.write on the project. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the sponsor entitlement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the sponsor entitlement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Logo on the main stage scrims.", "quantity": 12, "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "fulfilled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SponsorEntitlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspection-templates": { "get": { "operationId": "inspectionTemplates.list", "tags": ["Safety"], "x-xos-table": "app.inspection_templates", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List inspection template rows", "description": "A template for an inspection walk. Returns a cursor page of inspection template rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of inspection template rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Daily Stage Walk" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InspectionTemplatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "inspectionTemplates.create", "tags": ["Safety"], "x-xos-table": "app.inspection_templates", "x-xos-capability": "safety.inspection_template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create an inspection template", "description": "A template for an inspection walk. Creates an inspection template. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Daily Stage Walk" }, "schema": { "$ref": "#/components/schemas/InspectionTemplateCreate" } } } }, "responses": { "201": { "description": "The created inspection template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Daily Stage Walk" }, "schema": { "$ref": "#/components/schemas/InspectionTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspection-templates/{id}": { "get": { "operationId": "inspectionTemplates.get", "tags": ["Safety"], "x-xos-table": "app.inspection_templates", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an inspection template", "description": "A template for an inspection walk. Returns one inspection template with its `ETag`. A inspection template the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The inspection template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Daily Stage Walk" }, "schema": { "$ref": "#/components/schemas/InspectionTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "inspectionTemplates.update", "tags": ["Safety"], "x-xos-table": "app.inspection_templates", "x-xos-capability": "safety.inspection_template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update an inspection template", "description": "A template for an inspection walk. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Daily Stage Walk" }, "schema": { "$ref": "#/components/schemas/InspectionTemplateUpdate" } } } }, "responses": { "200": { "description": "The updated inspection template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Daily Stage Walk" }, "schema": { "$ref": "#/components/schemas/InspectionTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "inspectionTemplates.delete", "tags": ["Safety"], "x-xos-table": "app.inspection_templates", "x-xos-capability": "safety.inspection_template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Delete an inspection template", "description": "A template for an inspection walk. Soft-deletes the inspection template: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection template.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The inspection template moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspection-items": { "get": { "operationId": "inspectionItems.list", "tags": ["Safety"], "x-xos-table": "app.inspection_items", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["position"], "numeric": false }, "summary": "List inspection item rows", "description": "An item of an inspection template. Returns a cursor page of inspection item rows the caller may see. The default order is `position` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of inspection item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Guardrails secured on all stage edges", "is_critical": true } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InspectionItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "inspectionItems.create", "tags": ["Safety"], "x-xos-table": "app.inspection_items", "x-xos-capability": "safety.inspection_template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create an inspection item", "description": "An item of an inspection template. Creates an inspection item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Guardrails secured on all stage edges", "is_critical": true }, "schema": { "$ref": "#/components/schemas/InspectionItemCreate" } } } }, "responses": { "201": { "description": "The created inspection item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Guardrails secured on all stage edges", "is_critical": true }, "schema": { "$ref": "#/components/schemas/InspectionItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspection-items/{id}": { "get": { "operationId": "inspectionItems.get", "tags": ["Safety"], "x-xos-table": "app.inspection_items", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an inspection item", "description": "An item of an inspection template. Returns one inspection item with its `ETag`. A inspection item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The inspection item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Guardrails secured on all stage edges", "is_critical": true }, "schema": { "$ref": "#/components/schemas/InspectionItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "inspectionItems.update", "tags": ["Safety"], "x-xos-table": "app.inspection_items", "x-xos-capability": "safety.inspection_template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update an inspection item", "description": "An item of an inspection template. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "position": 1, "prompt": "Guardrails secured on all stage edges", "is_critical": true }, "schema": { "$ref": "#/components/schemas/InspectionItemUpdate" } } } }, "responses": { "200": { "description": "The updated inspection item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Guardrails secured on all stage edges", "is_critical": true }, "schema": { "$ref": "#/components/schemas/InspectionItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "inspectionItems.delete", "tags": ["Safety"], "x-xos-table": "app.inspection_items", "x-xos-capability": "safety.inspection_template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Delete an inspection item", "description": "An item of an inspection template. Soft-deletes the inspection item: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection item.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The inspection item moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspections": { "get": { "operationId": "inspections.list", "tags": ["Safety"], "x-xos-table": "app.inspections", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List inspection rows", "description": "An inspection performed from a template, with sign-off. Returns a cursor page of inspection rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of inspection rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspector_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_at": "2026-10-08T14:30:00Z", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspected_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InspectionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "inspections.create", "tags": ["Safety"], "x-xos-table": "app.inspections", "x-xos-capability": "safety.inspection.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create an inspection", "description": "An inspection performed from a template, with sign-off. Creates an inspection. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspected_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/InspectionCreate" } } } }, "responses": { "201": { "description": "The created inspection.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspector_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_at": "2026-10-08T14:30:00Z", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspected_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/Inspection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspections/{id}": { "get": { "operationId": "inspections.get", "tags": ["Safety"], "x-xos-table": "app.inspections", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an inspection", "description": "An inspection performed from a template, with sign-off. Returns one inspection with its `ETag`. A inspection the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The inspection.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspector_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_at": "2026-10-08T14:30:00Z", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspected_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/Inspection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "inspections.update", "tags": ["Safety"], "x-xos-table": "app.inspections", "x-xos-capability": "safety.inspection.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update an inspection", "description": "An inspection performed from a template, with sign-off. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/InspectionUpdate" } } } }, "responses": { "200": { "description": "The updated inspection.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspector_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_at": "2026-10-08T14:30:00Z", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspected_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/Inspection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspections/{id}/sign-off": { "post": { "operationId": "inspections.signOff", "tags": ["Safety"], "x-xos-table": "app.inspections", "x-xos-capability": "safety.inspection.sign_off", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Sign off an inspection", "description": "Signs off the inspection. Every item needs a result first. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspector_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signed_off_at": "2026-10-08T14:30:00Z", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspected_at": "2026-10-08T14:30:00Z", "urid": "4000.01.01" }, "schema": { "$ref": "#/components/schemas/Inspection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspection-results": { "get": { "operationId": "inspectionResults.list", "tags": ["Safety"], "x-xos-table": "app.inspection_results", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List inspection result rows", "description": "Pass or fail for one inspection item. Returns a cursor page of inspection result rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of inspection result rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Left rail tightened on site.", "result_enum_id": "ENM-084", "photo_uri": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InspectionResultPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "inspectionResults.create", "tags": ["Safety"], "x-xos-table": "app.inspection_results", "x-xos-capability": "safety.inspection.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create an inspection result", "description": "Pass or fail for one inspection item. Creates an inspection result. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "inspection_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Left rail tightened on site.", "result_enum_id": "ENM-084", "photo_uri": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg" }, "schema": { "$ref": "#/components/schemas/InspectionResultCreate" } } } }, "responses": { "201": { "description": "The created inspection result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Left rail tightened on site.", "result_enum_id": "ENM-084", "photo_uri": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/InspectionResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inspection-results/{id}": { "get": { "operationId": "inspectionResults.get", "tags": ["Safety"], "x-xos-table": "app.inspection_results", "x-xos-capability": "safety.inspection.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an inspection result", "description": "Pass or fail for one inspection item. Returns one inspection result with its `ETag`. A inspection result the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection result.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection result.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The inspection result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Left rail tightened on site.", "result_enum_id": "ENM-084", "photo_uri": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/InspectionResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "inspectionResults.update", "tags": ["Safety"], "x-xos-table": "app.inspection_results", "x-xos-capability": "safety.inspection.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update an inspection result", "description": "Pass or fail for one inspection item. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inspection result.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inspection result.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "note": "Left rail tightened on site.", "result_enum_id": "ENM-084", "photo_uri": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg" }, "schema": { "$ref": "#/components/schemas/InspectionResultUpdate" } } } }, "responses": { "200": { "description": "The updated inspection result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "inspection_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "note": "Left rail tightened on site.", "result_enum_id": "ENM-084", "photo_uri": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/inspections/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/rail.jpg", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/InspectionResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/permit-requirements": { "get": { "operationId": "permitRequirements.list", "tags": ["Safety"], "x-xos-table": "app.permit_requirements", "x-xos-capability": "safety.permit.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List permit requirement rows", "description": "A permit requirement generated by the jurisdiction permit engine. An unpopulated jurisdiction returns no answer. Returns a cursor page of permit requirement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of permit requirement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rule": "Assembly occupancy", "jurisdiction_id": "US-FL", "permit": "Certificate of occupancy", "ahj": "City Building and Fire", "permit_state": "Proposed", "lead_time": "4-6 wks", "trigger_type": "project", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PermitRequirementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/permit-requirements/{id}": { "get": { "operationId": "permitRequirements.get", "tags": ["Safety"], "x-xos-table": "app.permit_requirements", "x-xos-capability": "safety.permit.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a permit requirement", "description": "A permit requirement generated by the jurisdiction permit engine. An unpopulated jurisdiction returns no answer. Returns one permit requirement with its `ETag`. A permit requirement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the permit requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the permit requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The permit requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rule": "Assembly occupancy", "jurisdiction_id": "US-FL", "permit": "Certificate of occupancy", "ahj": "City Building and Fire", "permit_state": "Proposed", "lead_time": "4-6 wks", "trigger_type": "project", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PermitRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/permit-requirements/generate": { "post": { "operationId": "permitRequirements.generate", "tags": ["Safety"], "x-xos-table": "app.permit_requirements", "x-xos-capability": "safety.permit.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Run the permit engine", "description": "Runs the jurisdiction permit engine for a project and writes its permit requirements. An unpopulated jurisdiction returns a 422 `NO_ANSWER` refusal; it never passes. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PermitEngineRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rule": "Assembly occupancy", "jurisdiction_id": "US-FL", "permit": "Certificate of occupancy", "ahj": "City Building and Fire", "permit_state": "Proposed", "lead_time": "4-6 wks", "trigger_type": "project", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PermitRequirementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/permit-requirements/{id}/transitions": { "post": { "operationId": "permitRequirements.transition", "tags": ["Safety"], "x-xos-table": "app.permit_requirements", "x-xos-capability": "safety.permit.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Transition the permit state", "description": "Moves the permit lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the permit requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the permit requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Proposed", "to_state": "Active", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/PermitTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rule": "Assembly occupancy", "jurisdiction_id": "US-FL", "permit": "Certificate of occupancy", "ahj": "City Building and Fire", "permit_state": "Proposed", "lead_time": "4-6 wks", "trigger_type": "project", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PermitRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/permit-requirements/{id}/track": { "post": { "operationId": "permitRequirements.track", "tags": ["Safety"], "x-xos-table": "app.permit_requirements", "x-xos-capability": "safety.permit.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Track a permit requirement", "description": "Opens the Permit record that tracks the requirement (app.track_permit_requirement), titled with the canon permit, in one transaction. A requirement already tracked returns a 422 `permit_requirement_tracked` refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the permit requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the permit requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Special Events Permit" }, "schema": { "$ref": "#/components/schemas/PermitTrackRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rule": "Assembly occupancy", "jurisdiction_id": "US-FL", "permit": "Certificate of occupancy", "ahj": "City Building and Fire", "permit_state": "Proposed", "lead_time": "4-6 wks", "trigger_type": "project", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PermitRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incidents": { "get": { "operationId": "incidents.list", "tags": ["Safety"], "x-xos-table": "app.incidents", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List incident rows", "description": "An incident with dispatch. A critical incident cannot be relabeled and closed in one statement; closing requires sign-off. Returns a cursor page of incident rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of incident rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "incident_number": 142, "incident_state": "Reported", "reported_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "closed_signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/IncidentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "incidents.create", "tags": ["Safety"], "x-xos-table": "app.incidents", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create an incident", "description": "An incident with dispatch. A critical incident cannot be relabeled and closed in one statement; closing requires sign-off. Creates an incident. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/IncidentCreate" } } } }, "responses": { "201": { "description": "The created incident.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "incident_number": 142, "incident_state": "Reported", "reported_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "closed_signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incidents/{id}": { "get": { "operationId": "incidents.get", "tags": ["Safety"], "x-xos-table": "app.incidents", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an incident", "description": "An incident with dispatch. A critical incident cannot be relabeled and closed in one statement; closing requires sign-off. Returns one incident with its `ETag`. A incident the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The incident.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "incident_number": 142, "incident_state": "Reported", "reported_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "closed_signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "incidents.update", "tags": ["Safety"], "x-xos-table": "app.incidents", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update an incident", "description": "An incident with dispatch. A critical incident cannot be relabeled and closed in one statement; closing requires sign-off. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/IncidentUpdate" } } } }, "responses": { "200": { "description": "The updated incident.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "incident_number": 142, "incident_state": "Reported", "reported_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "closed_signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incidents/{id}/transitions": { "post": { "operationId": "incidents.transition", "tags": ["Safety"], "x-xos-table": "app.incidents", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Transition the incident state", "description": "Moves the incident lifecycle to another state through its transition RPC, which writes the transition ledger. Uses compare-and-set on `expected_state`; a disallowed transition returns a 422 refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Reported", "to_state": "Dispatched", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/IncidentTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "incident_number": 142, "incident_state": "Reported", "reported_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "closed_signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incidents/{id}/close": { "post": { "operationId": "incidents.close", "tags": ["Safety"], "x-xos-table": "app.incidents", "x-xos-capability": "safety.incident.close", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Close an incident", "description": "Closes a contained incident with sign-off through app.close_incident; the caller is recorded as the person signing off. The reporter of a critical incident cannot sign off its closure (422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "note": "Area inspected and safe." }, "schema": { "$ref": "#/components/schemas/IncidentCloseRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Guest Fall Near North Bar", "occurred_at": "2026-10-08T14:30:00Z", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "latitude": 25.7617, "longitude": -80.1918, "severity_enum_id": "ENM-097", "incident_number": 142, "incident_state": "Reported", "reported_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "closed_signed_off_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accuracy_m": 8, "device_reported_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incident-parties": { "get": { "operationId": "incidentParties.list", "tags": ["Safety"], "x-xos-table": "app.incident_parties", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List incident party rows", "description": "A person involved in an incident. Returns a cursor page of incident party rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of incident party rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Witness" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/IncidentPartyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "incidentParties.create", "tags": ["Safety"], "x-xos-table": "app.incident_parties", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create an incident party", "description": "A person involved in an incident. Creates an incident party. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Witness" }, "schema": { "$ref": "#/components/schemas/IncidentPartyCreate" } } } }, "responses": { "201": { "description": "The created incident party.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Witness" }, "schema": { "$ref": "#/components/schemas/IncidentParty" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incident-parties/{id}": { "get": { "operationId": "incidentParties.get", "tags": ["Safety"], "x-xos-table": "app.incident_parties", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an incident party", "description": "A person involved in an incident. Returns one incident party with its `ETag`. A incident party the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident party.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident party.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The incident party.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Witness" }, "schema": { "$ref": "#/components/schemas/IncidentParty" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "incidentParties.update", "tags": ["Safety"], "x-xos-table": "app.incident_parties", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update an incident party", "description": "A person involved in an incident. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident party.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident party.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Witness" }, "schema": { "$ref": "#/components/schemas/IncidentPartyUpdate" } } } }, "responses": { "200": { "description": "The updated incident party.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Witness" }, "schema": { "$ref": "#/components/schemas/IncidentParty" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "incidentParties.delete", "tags": ["Safety"], "x-xos-table": "app.incident_parties", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Delete an incident party", "description": "A person involved in an incident. Soft-deletes the incident party: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident party.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident party.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The incident party moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incident-media": { "get": { "operationId": "incidentMediaItems.list", "tags": ["Safety"], "x-xos-table": "app.incident_media", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List incident media item rows", "description": "A photo or file attached to an incident. Returns a cursor page of incident media item rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of incident media item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "media_uri": "org/incidents/gate.jpg", "captured_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/IncidentMediaPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "incidentMediaItems.create", "tags": ["Safety"], "x-xos-table": "app.incident_media", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create an incident media item", "description": "A photo or file attached to an incident. Creates an incident media item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "media_uri": "org/incidents/gate.jpg", "captured_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/IncidentMediaCreate" } } } }, "responses": { "201": { "description": "The created incident media item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "media_uri": "org/incidents/gate.jpg", "captured_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/IncidentMedia" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/incident-media/{id}": { "get": { "operationId": "incidentMediaItems.get", "tags": ["Safety"], "x-xos-table": "app.incident_media", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an incident media item", "description": "A photo or file attached to an incident. Returns one incident media item with its `ETag`. A incident media item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident media.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident media.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The incident media item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "media_uri": "org/incidents/gate.jpg", "captured_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/IncidentMedia" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "incidentMediaItems.delete", "tags": ["Safety"], "x-xos-table": "app.incident_media", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Delete an incident media item", "description": "A photo or file attached to an incident. Soft-deletes the incident media item: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the incident media.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the incident media.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The incident media item moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dispatch-assignments": { "get": { "operationId": "dispatchAssignments.list", "tags": ["Safety"], "x-xos-table": "app.dispatch_assignments", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List dispatch assignment rows", "description": "A responder dispatched to an incident. Returns a cursor page of dispatch assignment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of dispatch assignment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dispatched_at": "2026-10-08T14:30:00Z", "arrived_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DispatchAssignmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "dispatchAssignments.create", "tags": ["Safety"], "x-xos-table": "app.dispatch_assignments", "x-xos-capability": "safety.incident.dispatch", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a dispatch assignment", "description": "A responder dispatched to an incident. Creates a dispatch assignment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "arrived_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DispatchAssignmentCreate" } } } }, "responses": { "201": { "description": "The created dispatch assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dispatched_at": "2026-10-08T14:30:00Z", "arrived_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DispatchAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dispatch-assignments/{id}": { "get": { "operationId": "dispatchAssignments.get", "tags": ["Safety"], "x-xos-table": "app.dispatch_assignments", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a dispatch assignment", "description": "A responder dispatched to an incident. Returns one dispatch assignment with its `ETag`. A dispatch assignment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dispatch assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dispatch assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The dispatch assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dispatched_at": "2026-10-08T14:30:00Z", "arrived_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DispatchAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "dispatchAssignments.update", "tags": ["Safety"], "x-xos-table": "app.dispatch_assignments", "x-xos-capability": "safety.incident.dispatch", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update a dispatch assignment", "description": "A responder dispatched to an incident. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dispatch assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dispatch assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "arrived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DispatchAssignmentUpdate" } } } }, "responses": { "200": { "description": "The updated dispatch assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dispatched_at": "2026-10-08T14:30:00Z", "arrived_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DispatchAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/medical-encounters": { "get": { "operationId": "medicalEncounters.list", "tags": ["Safety"], "x-xos-table": "app.medical_encounters", "x-xos-capability": "data.restricted.read.medical", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List medical encounter rows", "description": "A medical encounter. Notes are Restricted, encrypted and never sent to a model. Returns a cursor page of medical encounter rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of medical encounter rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "patient_description": "Guest, adult", "treatment_notes": "Abrasion to the left knee, cleaned and dressed.", "disposition": "Released" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MedicalEncounterPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "medicalEncounters.create", "tags": ["Safety"], "x-xos-table": "app.medical_encounters", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a medical encounter", "description": "A medical encounter. Notes are Restricted, encrypted and never sent to a model. Creates a medical encounter. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "patient_description": "Guest, adult", "treatment_notes": "Abrasion to the left knee, cleaned and dressed.", "disposition": "Released" }, "schema": { "$ref": "#/components/schemas/MedicalEncounterCreate" } } } }, "responses": { "201": { "description": "The created medical encounter.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "patient_description": "Guest, adult", "treatment_notes": "Abrasion to the left knee, cleaned and dressed.", "disposition": "Released" }, "schema": { "$ref": "#/components/schemas/MedicalEncounter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/medical-encounters/{id}": { "get": { "operationId": "medicalEncounters.get", "tags": ["Safety"], "x-xos-table": "app.medical_encounters", "x-xos-capability": "data.restricted.read.medical", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get a medical encounter", "description": "A medical encounter. Notes are Restricted, encrypted and never sent to a model. Returns one medical encounter with its `ETag`. A medical encounter the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the medical encounter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the medical encounter.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The medical encounter.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "patient_description": "Guest, adult", "treatment_notes": "Abrasion to the left knee, cleaned and dressed.", "disposition": "Released" }, "schema": { "$ref": "#/components/schemas/MedicalEncounter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "medicalEncounters.update", "tags": ["Safety"], "x-xos-table": "app.medical_encounters", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update a medical encounter", "description": "A medical encounter. Notes are Restricted, encrypted and never sent to a model. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the medical encounter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the medical encounter.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "patient_description": "Guest, adult", "treatment_notes": "Abrasion to the left knee, cleaned and dressed.", "disposition": "Released" }, "schema": { "$ref": "#/components/schemas/MedicalEncounterUpdate" } } } }, "responses": { "200": { "description": "The updated medical encounter.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "incident_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "patient_description": "Guest, adult", "treatment_notes": "Abrasion to the left knee, cleaned and dressed.", "disposition": "Released" }, "schema": { "$ref": "#/components/schemas/MedicalEncounter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/crisis-alerts": { "get": { "operationId": "crisisAlerts.list", "tags": ["Safety"], "x-xos-table": "app.crisis_alerts", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List crisis alert rows", "description": "A crisis alert broadcast to a project. Returns a cursor page of crisis alert rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of crisis alert rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Weather hold: clear the north lawn.", "issued_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "emergency_code": "CODE_RED" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CrisisAlertPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "crisisAlerts.create", "tags": ["Safety"], "x-xos-table": "app.crisis_alerts", "x-xos-capability": "safety.incident.dispatch", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a crisis alert", "description": "A crisis alert broadcast to a project. Creates a crisis alert. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Weather hold: clear the north lawn.", "ended_at": "2026-10-08T14:30:00Z", "emergency_code": "CODE_RED" }, "schema": { "$ref": "#/components/schemas/CrisisAlertCreate" } } } }, "responses": { "201": { "description": "The created crisis alert.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Weather hold: clear the north lawn.", "issued_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "emergency_code": "CODE_RED" }, "schema": { "$ref": "#/components/schemas/CrisisAlert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/crisis-alerts/{id}": { "get": { "operationId": "crisisAlerts.get", "tags": ["Safety"], "x-xos-table": "app.crisis_alerts", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a crisis alert", "description": "A crisis alert broadcast to a project. Returns one crisis alert with its `ETag`. A crisis alert the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the crisis alert.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the crisis alert.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The crisis alert.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Weather hold: clear the north lawn.", "issued_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "emergency_code": "CODE_RED" }, "schema": { "$ref": "#/components/schemas/CrisisAlert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/crisis-alerts/{id}/clear": { "post": { "operationId": "crisisAlerts.clear", "tags": ["Safety"], "x-xos-table": "app.crisis_alerts", "x-xos-capability": "safety.incident.dispatch", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Clear a crisis alert", "description": "Clears the alert and notifies the project. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the crisis alert.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the crisis alert.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Weather hold: clear the north lawn.", "issued_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "emergency_code": "CODE_RED" }, "schema": { "$ref": "#/components/schemas/CrisisAlert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/emergency-codes": { "get": { "operationId": "emergencyCodes.list", "tags": ["Safety"], "x-xos-table": "xpms.emergency_code", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["sort_order"], "numeric": true }, "summary": "List emergency code rows", "description": "An org emergency code, seeded from the Standard Library and listed in numeric order. Returns a cursor page of emergency code rows the caller may see. Coded list: the default order is numeric code order by `sort_order`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of emergency code rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "code": "CODE_RED", "label": "Code Red", "emergency": "Fire Emergency", "swatch": "ecode-red", "sort_order": 1 }, { "code": "CODE_RED", "label": "Code Red", "emergency": "Fire Emergency", "swatch": "ecode-red", "sort_order": 2 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EmergencyCodePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/emergency-codes/{code}": { "get": { "operationId": "emergencyCodes.get", "tags": ["Safety"], "x-xos-table": "xpms.emergency_code", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an emergency code", "description": "An org emergency code, seeded from the Standard Library and listed in numeric order. Returns one emergency code with its `ETag`. A emergency code the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Code token.", "example": "CODE_RED" }, "required": true, "description": "Code token.", "name": "code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The emergency code.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "code": "CODE_RED", "label": "Code Red", "emergency": "Fire Emergency", "swatch": "ecode-red", "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/EmergencyCode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/radio-channels": { "get": { "operationId": "radioChannels.list", "tags": ["Safety"], "x-xos-table": "app.radio_channels", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["channel_number"], "numeric": true }, "summary": "List radio channel rows", "description": "A radio channel in the org radio plan, listed in numeric order. Returns a cursor page of radio channel rows the caller may see. Coded list: the default order is numeric code order by `channel_number`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of radio channel rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "channel_number": 1, "name": "Production", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "channel_number": 2, "name": "Production", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RadioChannelPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "radioChannels.create", "tags": ["Safety"], "x-xos-table": "app.radio_channels", "x-xos-capability": "safety.radio_channel.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a radio channel", "description": "A radio channel in the org radio plan, listed in numeric order. Creates a radio channel. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "channel_number": 1, "name": "Production", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RadioChannelCreate" } } } }, "responses": { "201": { "description": "The created radio channel.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "channel_number": 1, "name": "Production", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RadioChannel" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/radio-channels/{id}": { "get": { "operationId": "radioChannels.get", "tags": ["Safety"], "x-xos-table": "app.radio_channels", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a radio channel", "description": "A radio channel in the org radio plan, listed in numeric order. Returns one radio channel with its `ETag`. A radio channel the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the radio channel.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the radio channel.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The radio channel.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "channel_number": 1, "name": "Production", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RadioChannel" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "radioChannels.update", "tags": ["Safety"], "x-xos-table": "app.radio_channels", "x-xos-capability": "safety.radio_channel.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update a radio channel", "description": "A radio channel in the org radio plan, listed in numeric order. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the radio channel.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the radio channel.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "channel_number": 1, "name": "Production", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RadioChannelUpdate" } } } }, "responses": { "200": { "description": "The updated radio channel.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "channel_number": 1, "name": "Production", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "zone_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RadioChannel" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "radioChannels.delete", "tags": ["Safety"], "x-xos-table": "app.radio_channels", "x-xos-capability": "safety.radio_channel.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Delete a radio channel", "description": "A radio channel in the org radio plan, listed in numeric order. Soft-deletes the radio channel: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the radio channel.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the radio channel.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The radio channel moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunities": { "get": { "operationId": "opportunities.list", "tags": ["Opportunities"], "x-xos-table": "app.opportunities", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List opportunity rows", "description": "An opportunity published from an approved requisition. Without posted compensation it shows Rate on Request, never zero. Returns a cursor page of opportunity rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of opportunity rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "description": "Six stagehands for a two-day load-in.", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "visibility": "Pool", "opportunity_state": "Published", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_min_minor": 3500, "pay_max_minor": 4500, "currency_code": "USD", "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "is_remote": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OpportunityPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "opportunities.create", "tags": ["Opportunities"], "x-xos-table": "app.opportunities", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an opportunity", "description": "An opportunity published from an approved requisition. Without posted compensation it shows Rate on Request, never zero. Creates an opportunity. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "description": "Six stagehands for a two-day load-in.", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "visibility": "Pool", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_min_minor": 3500, "pay_max_minor": 4500, "currency_code": "USD", "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "is_remote": false }, "schema": { "$ref": "#/components/schemas/OpportunityCreate" } } } }, "responses": { "201": { "description": "The created opportunity.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "description": "Six stagehands for a two-day load-in.", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "visibility": "Pool", "opportunity_state": "Published", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_min_minor": 3500, "pay_max_minor": 4500, "currency_code": "USD", "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "is_remote": false }, "schema": { "$ref": "#/components/schemas/Opportunity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunities/{id}": { "get": { "operationId": "opportunities.get", "tags": ["Opportunities"], "x-xos-table": "app.opportunities", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an opportunity", "description": "An opportunity published from an approved requisition. Without posted compensation it shows Rate on Request, never zero. Returns one opportunity with its `ETag`. A opportunity the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The opportunity.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "description": "Six stagehands for a two-day load-in.", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "visibility": "Pool", "opportunity_state": "Published", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_min_minor": 3500, "pay_max_minor": 4500, "currency_code": "USD", "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "is_remote": false }, "schema": { "$ref": "#/components/schemas/Opportunity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "opportunities.update", "tags": ["Opportunities"], "x-xos-table": "app.opportunities", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update an opportunity", "description": "An opportunity published from an approved requisition. Without posted compensation it shows Rate on Request, never zero. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "description": "Six stagehands for a two-day load-in.", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "visibility": "Pool", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_min_minor": 3500, "pay_max_minor": 4500, "currency_code": "USD", "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "is_remote": false }, "schema": { "$ref": "#/components/schemas/OpportunityUpdate" } } } }, "responses": { "200": { "description": "The updated opportunity.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "description": "Six stagehands for a two-day load-in.", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "visibility": "Pool", "opportunity_state": "Published", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_min_minor": 3500, "pay_max_minor": 4500, "currency_code": "USD", "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "is_remote": false }, "schema": { "$ref": "#/components/schemas/Opportunity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "opportunities.delete", "tags": ["Opportunities"], "x-xos-table": "app.opportunities", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete an opportunity", "description": "An opportunity published from an approved requisition. Without posted compensation it shows Rate on Request, never zero. Soft-deletes the opportunity: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The opportunity moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunities/{id}/transitions": { "post": { "operationId": "opportunities.transition", "tags": ["Opportunities"], "x-xos-table": "app.opportunities", "x-xos-capability": "opportunities.posting.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Transition the opportunity state", "description": "Moves the opportunity state machine through its transition RPC, which writes its ledger. Publishing applies spend authority and refuses a posting without a pay range where the jurisdiction requires one. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Draft", "to_state": "Pending Approval", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/OpportunityTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requisition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "description": "Six stagehands for a two-day load-in.", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rate_type": "Day", "visibility": "Pool", "opportunity_state": "Published", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "pay_min_minor": 3500, "pay_max_minor": 4500, "currency_code": "USD", "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "is_remote": false }, "schema": { "$ref": "#/components/schemas/Opportunity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-positions": { "get": { "operationId": "opportunityPositions.list", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_positions", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List opportunity position rows", "description": "A position within an opportunity. Returns a cursor page of opportunity position rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of opportunity position rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "Rigger 2", "call_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OpportunityPositionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "opportunityPositions.create", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_positions", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an opportunity position", "description": "A position within an opportunity. Creates an opportunity position. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "Rigger 2", "call_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OpportunityPositionCreate" } } } }, "responses": { "201": { "description": "The created opportunity position.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "Rigger 2", "call_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OpportunityPosition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-positions/{id}": { "get": { "operationId": "opportunityPositions.get", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_positions", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an opportunity position", "description": "A position within an opportunity. Returns one opportunity position with its `ETag`. A opportunity position the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity position.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity position.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The opportunity position.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "Rigger 2", "call_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OpportunityPosition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "opportunityPositions.update", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_positions", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update an opportunity position", "description": "A position within an opportunity. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity position.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity position.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "label": "Rigger 2", "call_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OpportunityPositionUpdate" } } } }, "responses": { "200": { "description": "The updated opportunity position.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "label": "Rigger 2", "call_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OpportunityPosition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "opportunityPositions.delete", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_positions", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete an opportunity position", "description": "A position within an opportunity. Soft-deletes the opportunity position: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity position.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity position.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The opportunity position moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-requirements": { "get": { "operationId": "opportunityRequirements.list", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_requirements", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List opportunity requirement rows", "description": "A requirement of an opportunity: a certification through a canon compliance tag, insurance or equipment. Returns a cursor page of opportunity requirement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of opportunity requirement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurance_minimum_minor": 100000000, "requirement_kind": "Certification", "description": "Rigging certification, current.", "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OpportunityRequirementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "opportunityRequirements.create", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_requirements", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an opportunity requirement", "description": "A requirement of an opportunity: a certification through a canon compliance tag, insurance or equipment. Creates an opportunity requirement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurance_minimum_minor": 100000000, "requirement_kind": "Certification", "description": "Rigging certification, current.", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/OpportunityRequirementCreate" } } } }, "responses": { "201": { "description": "The created opportunity requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurance_minimum_minor": 100000000, "requirement_kind": "Certification", "description": "Rigging certification, current.", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/OpportunityRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-requirements/{id}": { "get": { "operationId": "opportunityRequirements.get", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_requirements", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an opportunity requirement", "description": "A requirement of an opportunity: a certification through a canon compliance tag, insurance or equipment. Returns one opportunity requirement with its `ETag`. A opportunity requirement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The opportunity requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurance_minimum_minor": 100000000, "requirement_kind": "Certification", "description": "Rigging certification, current.", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/OpportunityRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "opportunityRequirements.update", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_requirements", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update an opportunity requirement", "description": "A requirement of an opportunity: a certification through a canon compliance tag, insurance or equipment. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurance_minimum_minor": 100000000, "requirement_kind": "Certification", "description": "Rigging certification, current.", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/OpportunityRequirementUpdate" } } } }, "responses": { "200": { "description": "The updated opportunity requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insurance_minimum_minor": 100000000, "requirement_kind": "Certification", "description": "Rigging certification, current.", "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/OpportunityRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "opportunityRequirements.delete", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_requirements", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete an opportunity requirement", "description": "A requirement of an opportunity: a certification through a canon compliance tag, insurance or equipment. Soft-deletes the opportunity requirement: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity requirement.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The opportunity requirement moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-questions": { "get": { "operationId": "opportunityQuestions.list", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_questions", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["position"], "numeric": false }, "summary": "List opportunity question rows", "description": "An application question. Returns a cursor page of opportunity question rows the caller may see. The default order is `position` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of opportunity question rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Have you worked a festival load-in before?", "required": true } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OpportunityQuestionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "opportunityQuestions.create", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_questions", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an opportunity question", "description": "An application question. Creates an opportunity question. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Have you worked a festival load-in before?", "required": true }, "schema": { "$ref": "#/components/schemas/OpportunityQuestionCreate" } } } }, "responses": { "201": { "description": "The created opportunity question.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Have you worked a festival load-in before?", "required": true }, "schema": { "$ref": "#/components/schemas/OpportunityQuestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-questions/{id}": { "get": { "operationId": "opportunityQuestions.get", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_questions", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an opportunity question", "description": "An application question. Returns one opportunity question with its `ETag`. A opportunity question the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity question.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The opportunity question.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Have you worked a festival load-in before?", "required": true }, "schema": { "$ref": "#/components/schemas/OpportunityQuestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "opportunityQuestions.update", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_questions", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update an opportunity question", "description": "An application question. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity question.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "position": 1, "prompt": "Have you worked a festival load-in before?", "required": true }, "schema": { "$ref": "#/components/schemas/OpportunityQuestionUpdate" } } } }, "responses": { "200": { "description": "The updated opportunity question.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "Have you worked a festival load-in before?", "required": true }, "schema": { "$ref": "#/components/schemas/OpportunityQuestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "opportunityQuestions.delete", "tags": ["Opportunities"], "x-xos-table": "app.opportunity_questions", "x-xos-capability": "opportunities.posting.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete an opportunity question", "description": "An application question. Soft-deletes the opportunity question: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity question.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The opportunity question moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pay-transparency-rules": { "get": { "operationId": "payTransparencyRules.list", "tags": ["Opportunities"], "x-xos-table": "app.pay_transparency_rules", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["jurisdiction_id"], "numeric": false }, "summary": "List pay transparency rule rows", "description": "Where a pay range is legally required in a posting. Returns a cursor page of pay transparency rule rows the caller may see. The default order is `jurisdiction_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of pay transparency rule rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "jurisdiction_id": "US-FL", "range_required": true, "effective_from": "2026-10-08" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PayTransparencyRulePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/applications": { "get": { "operationId": "applications.list", "tags": ["Opportunities"], "x-xos-table": "app.applications", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List application rows", "description": "An application to an opportunity, with a consented profile snapshot. Returns a cursor page of application rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of application rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "profile_share_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "availability_confirmed": true, "application_state": "Submitted", "applicant_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "applicant_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cover_note": "Available for both show days.", "proposed_fee_minor": 250000, "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ApplicationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "applications.create", "tags": ["Opportunities"], "x-xos-table": "app.applications", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an application", "description": "An application to an opportunity, with a consented profile snapshot. Creates an application. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "profile_share_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "availability_confirmed": true, "applicant_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "applicant_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cover_note": "Available for both show days.", "proposed_fee_minor": 250000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/ApplicationCreate" } } } }, "responses": { "201": { "description": "The created application.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "profile_share_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "availability_confirmed": true, "application_state": "Submitted", "applicant_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "applicant_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cover_note": "Available for both show days.", "proposed_fee_minor": 250000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/applications/{id}": { "get": { "operationId": "applications.get", "tags": ["Opportunities"], "x-xos-table": "app.applications", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an application", "description": "An application to an opportunity, with a consented profile snapshot. Returns one application with its `ETag`. A application the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the application.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The application.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "profile_share_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "availability_confirmed": true, "application_state": "Submitted", "applicant_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "applicant_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cover_note": "Available for both show days.", "proposed_fee_minor": 250000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/applications/{id}/transitions": { "post": { "operationId": "applications.transition", "tags": ["Opportunities"], "x-xos-table": "app.applications", "x-xos-capability": "opportunities.selection.decide", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Transition the application state", "description": "Moves the application state machine through its transition RPC, which writes its ledger. Applicants may only withdraw; every other transition belongs to the org. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the application.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Submitted", "to_state": "In Review", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/ApplicationTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "profile_share_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "availability_confirmed": true, "application_state": "Submitted", "applicant_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "applicant_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cover_note": "Available for both show days.", "proposed_fee_minor": 250000, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/application-answers": { "get": { "operationId": "applicationAnswers.list", "tags": ["Opportunities"], "x-xos-table": "app.application_answers", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List application answer rows", "description": "An answer to an application question. Returns a cursor page of application answer rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of application answer rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answer": "Yes, three seasons of festival load-ins." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ApplicationAnswerPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "applicationAnswers.create", "tags": ["Opportunities"], "x-xos-table": "app.application_answers", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an application answer", "description": "An answer to an application question. Creates an application answer. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answer": "Yes, three seasons of festival load-ins." }, "schema": { "$ref": "#/components/schemas/ApplicationAnswerCreate" } } } }, "responses": { "201": { "description": "The created application answer.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answer": "Yes, three seasons of festival load-ins." }, "schema": { "$ref": "#/components/schemas/ApplicationAnswer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/application-answers/{id}": { "get": { "operationId": "applicationAnswers.get", "tags": ["Opportunities"], "x-xos-table": "app.application_answers", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an application answer", "description": "An answer to an application question. Returns one application answer with its `ETag`. A application answer the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the application answer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the application answer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The application answer.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answer": "Yes, three seasons of festival load-ins." }, "schema": { "$ref": "#/components/schemas/ApplicationAnswer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bids": { "get": { "operationId": "bids.list", "tags": ["Opportunities"], "x-xos-table": "app.bids", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List bid rows", "description": "A sealed line-item bid. A bidder never sees another bidder, and the org sees bids only after the deadline unless it holds `procurement.bid.unseal`. Returns a cursor page of bid rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of bid rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "sealed": true, "currency_code": "USD", "valid_until": "2026-10-08", "submitted_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BidPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "bids.create", "tags": ["Opportunities"], "x-xos-table": "app.bids", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a bid", "description": "A sealed line-item bid. A bidder never sees another bidder, and the org sees bids only after the deadline unless it holds `procurement.bid.unseal`. Creates a bid. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "currency_code": "USD", "valid_until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/BidCreate" } } } }, "responses": { "201": { "description": "The created bid.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "sealed": true, "currency_code": "USD", "valid_until": "2026-10-08", "submitted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Bid" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bids/{id}": { "get": { "operationId": "bids.get", "tags": ["Opportunities"], "x-xos-table": "app.bids", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a bid", "description": "A sealed line-item bid. A bidder never sees another bidder, and the org sees bids only after the deadline unless it holds `procurement.bid.unseal`. Returns one bid with its `ETag`. A bid the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the bid.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The bid.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "sealed": true, "currency_code": "USD", "valid_until": "2026-10-08", "submitted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Bid" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "bids.update", "tags": ["Opportunities"], "x-xos-table": "app.bids", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a bid", "description": "A sealed line-item bid. A bidder never sees another bidder, and the org sees bids only after the deadline unless it holds `procurement.bid.unseal`. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the bid.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the bid.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_until": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/BidUpdate" } } } }, "responses": { "200": { "description": "The updated bid.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "total": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "sealed": true, "currency_code": "USD", "valid_until": "2026-10-08", "submitted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Bid" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bid-lines": { "get": { "operationId": "bidLines.list", "tags": ["Opportunities"], "x-xos-table": "app.bid_lines", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List bid line rows", "description": "A line of a sealed bid. Returns a cursor page of bid line rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of bid line rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bid_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array rental", "quantity": 2, "unit_price_minor": 1800000, "currency": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BidLinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "bidLines.create", "tags": ["Opportunities"], "x-xos-table": "app.bid_lines", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a bid line", "description": "A line of a sealed bid. Creates a bid line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "bid_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array rental", "quantity": 2, "unit_price_minor": 1800000 }, "schema": { "$ref": "#/components/schemas/BidLineCreate" } } } }, "responses": { "201": { "description": "The created bid line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bid_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array rental", "quantity": 2, "unit_price_minor": 1800000, "currency": "USD" }, "schema": { "$ref": "#/components/schemas/BidLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bid-lines/{id}": { "get": { "operationId": "bidLines.get", "tags": ["Opportunities"], "x-xos-table": "app.bid_lines", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a bid line", "description": "A line of a sealed bid. Returns one bid line with its `ETag`. A bid line the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the bid line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the bid line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The bid line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bid_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array rental", "quantity": 2, "unit_price_minor": 1800000, "currency": "USD" }, "schema": { "$ref": "#/components/schemas/BidLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "bidLines.update", "tags": ["Opportunities"], "x-xos-table": "app.bid_lines", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a bid line", "description": "A line of a sealed bid. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the bid line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the bid line.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "description": "Line array rental", "quantity": 2, "unit_price_minor": 1800000 }, "schema": { "$ref": "#/components/schemas/BidLineUpdate" } } } }, "responses": { "200": { "description": "The updated bid line.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "bid_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Line array rental", "quantity": 2, "unit_price_minor": 1800000, "currency": "USD" }, "schema": { "$ref": "#/components/schemas/BidLine" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "bidLines.delete", "tags": ["Opportunities"], "x-xos-table": "app.bid_lines", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a bid line", "description": "A line of a sealed bid. Soft-deletes the bid line: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the bid line.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the bid line.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The bid line moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/agency-slates": { "get": { "operationId": "agencySlates.list", "tags": ["Opportunities"], "x-xos-table": "app.agency_slates", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List agency slate entry rows", "description": "A named staff member on a staffing agency's slate. Returns a cursor page of agency slate entry rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of agency slate entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AgencySlatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "agencySlates.create", "tags": ["Opportunities"], "x-xos-table": "app.agency_slates", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an agency slate entry", "description": "A named staff member on a staffing agency's slate. Creates an agency slate entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AgencySlateCreate" } } } }, "responses": { "201": { "description": "The created agency slate entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AgencySlate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/agency-slates/{id}": { "get": { "operationId": "agencySlates.get", "tags": ["Opportunities"], "x-xos-table": "app.agency_slates", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an agency slate entry", "description": "A named staff member on a staffing agency's slate. Returns one agency slate entry with its `ETag`. A agency slate entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the agency slate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the agency slate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The agency slate entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AgencySlate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "agencySlates.delete", "tags": ["Opportunities"], "x-xos-table": "app.agency_slates", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete an agency slate entry", "description": "A named staff member on a staffing agency's slate. Soft-deletes the agency slate entry: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the agency slate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the agency slate.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The agency slate entry moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shortlists": { "get": { "operationId": "shortlistEntries.list", "tags": ["Opportunities"], "x-xos-table": "app.shortlists", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List shortlist entry rows", "description": "An application placed on the opportunity shortlist. Returns a cursor page of shortlist entry rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of shortlist entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rank": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ShortlistPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "shortlistEntries.create", "tags": ["Opportunities"], "x-xos-table": "app.shortlists", "x-xos-capability": "opportunities.application.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create a shortlist entry", "description": "An application placed on the opportunity shortlist. Creates a shortlist entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rank": 1 }, "schema": { "$ref": "#/components/schemas/ShortlistCreate" } } } }, "responses": { "201": { "description": "The created shortlist entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rank": 1 }, "schema": { "$ref": "#/components/schemas/Shortlist" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/shortlists/{id}": { "get": { "operationId": "shortlistEntries.get", "tags": ["Opportunities"], "x-xos-table": "app.shortlists", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a shortlist entry", "description": "An application placed on the opportunity shortlist. Returns one shortlist entry with its `ETag`. A shortlist entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shortlist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shortlist.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The shortlist entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rank": 1 }, "schema": { "$ref": "#/components/schemas/Shortlist" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "shortlistEntries.update", "tags": ["Opportunities"], "x-xos-table": "app.shortlists", "x-xos-capability": "opportunities.application.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update a shortlist entry", "description": "An application placed on the opportunity shortlist. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shortlist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shortlist.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "rank": 1 }, "schema": { "$ref": "#/components/schemas/ShortlistUpdate" } } } }, "responses": { "200": { "description": "The updated shortlist entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rank": 1 }, "schema": { "$ref": "#/components/schemas/Shortlist" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "shortlistEntries.delete", "tags": ["Opportunities"], "x-xos-table": "app.shortlists", "x-xos-capability": "opportunities.application.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete a shortlist entry", "description": "An application placed on the opportunity shortlist. Soft-deletes the shortlist entry: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the shortlist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the shortlist.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The shortlist entry moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/interviews": { "get": { "operationId": "interviews.list", "tags": ["Opportunities"], "x-xos-table": "app.interviews", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List interview rows", "description": "An interview or audition for an application. Returns a cursor page of interview rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of interview rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scheduled_at": "2026-10-08T14:30:00Z", "interview_kind": "Interview", "duration_minutes": 30, "location_text": "Production office, Hall B", "internal_note": "Strong rigging resume." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InterviewPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "interviews.create", "tags": ["Opportunities"], "x-xos-table": "app.interviews", "x-xos-capability": "opportunities.application.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an interview", "description": "An interview or audition for an application. Creates an interview. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scheduled_at": "2026-10-08T14:30:00Z", "interview_kind": "Interview", "duration_minutes": 30, "location_text": "Production office, Hall B", "internal_note": "Strong rigging resume." }, "schema": { "$ref": "#/components/schemas/InterviewCreate" } } } }, "responses": { "201": { "description": "The created interview.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scheduled_at": "2026-10-08T14:30:00Z", "interview_kind": "Interview", "duration_minutes": 30, "location_text": "Production office, Hall B", "internal_note": "Strong rigging resume." }, "schema": { "$ref": "#/components/schemas/Interview" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/interviews/{id}": { "get": { "operationId": "interviews.get", "tags": ["Opportunities"], "x-xos-table": "app.interviews", "x-xos-capability": "opportunities.application.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an interview", "description": "An interview or audition for an application. Returns one interview with its `ETag`. A interview the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the interview.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the interview.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The interview.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scheduled_at": "2026-10-08T14:30:00Z", "interview_kind": "Interview", "duration_minutes": 30, "location_text": "Production office, Hall B", "internal_note": "Strong rigging resume." }, "schema": { "$ref": "#/components/schemas/Interview" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "interviews.update", "tags": ["Opportunities"], "x-xos-table": "app.interviews", "x-xos-capability": "opportunities.application.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update an interview", "description": "An interview or audition for an application. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the interview.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the interview.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "scheduled_at": "2026-10-08T14:30:00Z", "interview_kind": "Interview", "duration_minutes": 30, "location_text": "Production office, Hall B", "internal_note": "Strong rigging resume." }, "schema": { "$ref": "#/components/schemas/InterviewUpdate" } } } }, "responses": { "200": { "description": "The updated interview.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scheduled_at": "2026-10-08T14:30:00Z", "interview_kind": "Interview", "duration_minutes": 30, "location_text": "Production office, Hall B", "internal_note": "Strong rigging resume." }, "schema": { "$ref": "#/components/schemas/Interview" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "interviews.delete", "tags": ["Opportunities"], "x-xos-table": "app.interviews", "x-xos-capability": "opportunities.application.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete an interview", "description": "An interview or audition for an application. Soft-deletes the interview: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the interview.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the interview.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The interview moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagements": { "get": { "operationId": "engagements.list", "tags": ["Opportunities"], "x-xos-table": "app.engagements", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List engagement rows", "description": "An external relationship: a person or external account working for an org. It cannot become Active until every blocking onboarding item passes. Returns a cursor page of engagement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of engagement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "engagement_state": "Onboarding", "activated_at": "2026-10-08T14:30:00Z", "completed_at": "2026-10-08T14:30:00Z", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "worker_classification": "INDEPENDENT_CONTRACTOR", "pay_basis": "Day Rate", "arrangement": "Per Engagement", "start_date": "2026-10-08", "end_date": "2026-10-08", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EngagementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "engagements.create", "tags": ["Opportunities"], "x-xos-table": "app.engagements", "x-xos-capability": "opportunities.engagement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an engagement", "description": "An external relationship: a person or external account working for an org. It cannot become Active until every blocking onboarding item passes. Creates an engagement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "worker_classification": "INDEPENDENT_CONTRACTOR", "pay_basis": "Day Rate", "arrangement": "Per Engagement", "start_date": "2026-10-08", "end_date": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/EngagementCreate" } } } }, "responses": { "201": { "description": "The created engagement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "engagement_state": "Onboarding", "activated_at": "2026-10-08T14:30:00Z", "completed_at": "2026-10-08T14:30:00Z", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "worker_classification": "INDEPENDENT_CONTRACTOR", "pay_basis": "Day Rate", "arrangement": "Per Engagement", "start_date": "2026-10-08", "end_date": "2026-10-08", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Engagement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagements/{id}": { "get": { "operationId": "engagements.get", "tags": ["Opportunities"], "x-xos-table": "app.engagements", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an engagement", "description": "An external relationship: a person or external account working for an org. It cannot become Active until every blocking onboarding item passes. Returns one engagement with its `ETag`. A engagement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the engagement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The engagement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "engagement_state": "Onboarding", "activated_at": "2026-10-08T14:30:00Z", "completed_at": "2026-10-08T14:30:00Z", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "worker_classification": "INDEPENDENT_CONTRACTOR", "pay_basis": "Day Rate", "arrangement": "Per Engagement", "start_date": "2026-10-08", "end_date": "2026-10-08", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Engagement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagements/{id}/transitions": { "post": { "operationId": "engagements.transition", "tags": ["Opportunities"], "x-xos-table": "app.engagements", "x-xos-capability": "opportunities.engagement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Transition the engagement state", "description": "Moves the engagement state machine through its transition RPC, which writes its ledger. Active is refused until every blocking onboarding item passes. Complete narrows external access to money and documents. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the engagement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the engagement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Onboarding", "to_state": "Active", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/EngagementTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "engagement_state": "Onboarding", "activated_at": "2026-10-08T14:30:00Z", "completed_at": "2026-10-08T14:30:00Z", "application_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "worker_classification": "INDEPENDENT_CONTRACTOR", "pay_basis": "Day Rate", "arrangement": "Per Engagement", "start_date": "2026-10-08", "end_date": "2026-10-08", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Engagement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagement-documents": { "get": { "operationId": "engagementDocuments.list", "tags": ["Opportunities"], "x-xos-table": "app.engagement_documents", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List engagement document rows", "description": "A document in an engagement, under the canon Engagement-Document lifecycle. Returns a cursor page of engagement document rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of engagement document rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Statement of Work", "engagement_document_state": "Proposed", "document_kind": "Offer", "expires_on": "2026-10-08" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EngagementDocumentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "engagementDocuments.create", "tags": ["Opportunities"], "x-xos-table": "app.engagement_documents", "x-xos-capability": "opportunities.engagement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an engagement document", "description": "A document in an engagement, under the canon Engagement-Document lifecycle. Creates an engagement document. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Statement of Work", "document_kind": "Offer", "expires_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/EngagementDocumentCreate" } } } }, "responses": { "201": { "description": "The created engagement document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Statement of Work", "engagement_document_state": "Proposed", "document_kind": "Offer", "expires_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/EngagementDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagement-documents/{id}": { "get": { "operationId": "engagementDocuments.get", "tags": ["Opportunities"], "x-xos-table": "app.engagement_documents", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an engagement document", "description": "A document in an engagement, under the canon Engagement-Document lifecycle. Returns one engagement document with its `ETag`. A engagement document the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the engagement document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the engagement document.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The engagement document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Statement of Work", "engagement_document_state": "Proposed", "document_kind": "Offer", "expires_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/EngagementDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagement-documents/{id}/transitions": { "post": { "operationId": "engagementDocuments.transition", "tags": ["Opportunities"], "x-xos-table": "app.engagement_documents", "x-xos-capability": "opportunities.engagement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Transition an engagement document", "description": "Moves the document through the canon Engagement-Document lifecycle. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the engagement document.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the engagement document.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Proposed", "to_state": "Active", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/EngagementDocumentTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Statement of Work", "engagement_document_state": "Proposed", "document_kind": "Offer", "expires_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/EngagementDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/onboarding-requirements": { "get": { "operationId": "onboardingRequirements.list", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_requirements", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List onboarding requirement rows", "description": "A requirement of the onboarding packet, by role type and jurisdiction. Returns a cursor page of onboarding requirement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of onboarding requirement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "jurisdiction_id": "US-FL", "verification_method": "Reviewer", "name": "Certificate of Insurance", "item_kind": "Document Upload", "is_blocking": true, "valid_for_days": 365, "remind_days_before": 30 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OnboardingRequirementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "onboardingRequirements.create", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_requirements", "x-xos-capability": "org.gateway.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an onboarding requirement", "description": "A requirement of the onboarding packet, by role type and jurisdiction. Creates an onboarding requirement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_type": "Crew", "jurisdiction_id": "US-FL", "verification_method": "Reviewer", "name": "Certificate of Insurance", "item_kind": "Document Upload", "is_blocking": true, "valid_for_days": 365, "remind_days_before": 30 }, "schema": { "$ref": "#/components/schemas/OnboardingRequirementCreate" } } } }, "responses": { "201": { "description": "The created onboarding requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "jurisdiction_id": "US-FL", "verification_method": "Reviewer", "name": "Certificate of Insurance", "item_kind": "Document Upload", "is_blocking": true, "valid_for_days": 365, "remind_days_before": 30 }, "schema": { "$ref": "#/components/schemas/OnboardingRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/onboarding-requirements/{id}": { "get": { "operationId": "onboardingRequirements.get", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_requirements", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an onboarding requirement", "description": "A requirement of the onboarding packet, by role type and jurisdiction. Returns one onboarding requirement with its `ETag`. A onboarding requirement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the onboarding requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The onboarding requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "jurisdiction_id": "US-FL", "verification_method": "Reviewer", "name": "Certificate of Insurance", "item_kind": "Document Upload", "is_blocking": true, "valid_for_days": 365, "remind_days_before": 30 }, "schema": { "$ref": "#/components/schemas/OnboardingRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "onboardingRequirements.update", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_requirements", "x-xos-capability": "org.gateway.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an onboarding requirement", "description": "A requirement of the onboarding packet, by role type and jurisdiction. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the onboarding requirement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_type": "Crew", "jurisdiction_id": "US-FL", "verification_method": "Reviewer", "name": "Certificate of Insurance", "item_kind": "Document Upload", "is_blocking": true, "valid_for_days": 365, "remind_days_before": 30 }, "schema": { "$ref": "#/components/schemas/OnboardingRequirementUpdate" } } } }, "responses": { "200": { "description": "The updated onboarding requirement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_type": "Crew", "jurisdiction_id": "US-FL", "verification_method": "Reviewer", "name": "Certificate of Insurance", "item_kind": "Document Upload", "is_blocking": true, "valid_for_days": 365, "remind_days_before": 30 }, "schema": { "$ref": "#/components/schemas/OnboardingRequirement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "onboardingRequirements.delete", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_requirements", "x-xos-capability": "org.gateway.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an onboarding requirement", "description": "A requirement of the onboarding packet, by role type and jurisdiction. Soft-deletes the onboarding requirement: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding requirement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the onboarding requirement.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The onboarding requirement moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/onboarding-items": { "get": { "operationId": "onboardingItems.list", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_items", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List onboarding item rows", "description": "One onboarding requirement instantiated for an engagement. Returns a cursor page of onboarding item rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of onboarding item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_requirement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_item_state": "In Review", "expires_on": "2026-10-08", "carried_over": false, "submitted_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OnboardingItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "onboardingItems.create", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_items", "x-xos-capability": "opportunities.onboarding.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an onboarding item", "description": "One onboarding requirement instantiated for an engagement. Creates an onboarding item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_requirement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/OnboardingItemCreate" } } } }, "responses": { "201": { "description": "The created onboarding item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_requirement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_item_state": "In Review", "expires_on": "2026-10-08", "carried_over": false, "submitted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OnboardingItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/onboarding-items/{id}": { "get": { "operationId": "onboardingItems.get", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_items", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an onboarding item", "description": "One onboarding requirement instantiated for an engagement. Returns one onboarding item with its `ETag`. A onboarding item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the onboarding item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The onboarding item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_requirement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_item_state": "In Review", "expires_on": "2026-10-08", "carried_over": false, "submitted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OnboardingItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/onboarding-items/{id}/submit": { "post": { "operationId": "onboardingItems.submit", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_items", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "submit_onboarding_item", "summary": "Submit an onboarding item", "description": "The engaged party submits the item while onboarding is open, optionally attaching a document of the org. Anyone else is refused (403). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the onboarding item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/OnboardingItemSubmitRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_requirement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_item_state": "In Review", "expires_on": "2026-10-08", "carried_over": false, "submitted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OnboardingItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/onboarding-verifications": { "get": { "operationId": "onboardingVerifications.list", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_verifications", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List onboarding verification rows", "description": "A verification decision on an onboarding item. Returns a cursor page of onboarding verification rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of onboarding verification rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "passed": true, "verified_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "verified_at": "2026-10-08T14:30:00Z", "notes": "Name matches the tax form." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OnboardingVerificationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "onboardingVerifications.create", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_verifications", "x-xos-capability": "opportunities.onboarding.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an onboarding verification", "description": "A verification decision on an onboarding item. Creates an onboarding verification. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "onboarding_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "passed": true, "notes": "Name matches the tax form." }, "schema": { "$ref": "#/components/schemas/OnboardingVerificationCreate" } } } }, "responses": { "201": { "description": "The created onboarding verification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "passed": true, "verified_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "verified_at": "2026-10-08T14:30:00Z", "notes": "Name matches the tax form." }, "schema": { "$ref": "#/components/schemas/OnboardingVerification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/onboarding-verifications/{id}": { "get": { "operationId": "onboardingVerifications.get", "tags": ["Opportunities"], "x-xos-table": "app.onboarding_verifications", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an onboarding verification", "description": "A verification decision on an onboarding item. Returns one onboarding verification with its `ETag`. A onboarding verification the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the onboarding verification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the onboarding verification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The onboarding verification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "onboarding_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "passed": true, "verified_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "verified_at": "2026-10-08T14:30:00Z", "notes": "Name matches the tax form." }, "schema": { "$ref": "#/components/schemas/OnboardingVerification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/talent-pools": { "get": { "operationId": "talentPools.list", "tags": ["Opportunities"], "x-xos-table": "app.talent_pools", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List talent pool rows", "description": "A talent or vendor pool. Returns a cursor page of talent pool rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of talent pool rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Preferred Riggers", "pool_kind": "Talent" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TalentPoolPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "talentPools.create", "tags": ["Opportunities"], "x-xos-table": "app.talent_pools", "x-xos-capability": "opportunities.pool.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create a talent pool", "description": "A talent or vendor pool. Creates a talent pool. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Preferred Riggers", "pool_kind": "Talent" }, "schema": { "$ref": "#/components/schemas/TalentPoolCreate" } } } }, "responses": { "201": { "description": "The created talent pool.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Preferred Riggers", "pool_kind": "Talent" }, "schema": { "$ref": "#/components/schemas/TalentPool" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/talent-pools/{id}": { "get": { "operationId": "talentPools.get", "tags": ["Opportunities"], "x-xos-table": "app.talent_pools", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a talent pool", "description": "A talent or vendor pool. Returns one talent pool with its `ETag`. A talent pool the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the talent pool.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the talent pool.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The talent pool.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Preferred Riggers", "pool_kind": "Talent" }, "schema": { "$ref": "#/components/schemas/TalentPool" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "talentPools.update", "tags": ["Opportunities"], "x-xos-table": "app.talent_pools", "x-xos-capability": "opportunities.pool.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update a talent pool", "description": "A talent or vendor pool. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the talent pool.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the talent pool.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Preferred Riggers" }, "schema": { "$ref": "#/components/schemas/TalentPoolUpdate" } } } }, "responses": { "200": { "description": "The updated talent pool.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Preferred Riggers", "pool_kind": "Talent" }, "schema": { "$ref": "#/components/schemas/TalentPool" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "talentPools.delete", "tags": ["Opportunities"], "x-xos-table": "app.talent_pools", "x-xos-capability": "opportunities.pool.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete a talent pool", "description": "A talent or vendor pool. Soft-deletes the talent pool: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the talent pool.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the talent pool.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The talent pool moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pool-members": { "get": { "operationId": "poolMembers.list", "tags": ["Opportunities"], "x-xos-table": "app.pool_members", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List pool member rows", "description": "A pool member. Do Not Engage needs a reason and a review date and is never visible externally. Returns a cursor page of pool member rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of pool member rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "talent_pool_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "level": "Preferred", "reason": "Repeated no-shows.", "review_on": "2026-10-08", "rehire_eligible": true } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PoolMemberPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "poolMembers.create", "tags": ["Opportunities"], "x-xos-table": "app.pool_members", "x-xos-capability": "opportunities.pool.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create a pool member", "description": "A pool member. Do Not Engage needs a reason and a review date and is never visible externally. Creates a pool member. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "talent_pool_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "level": "Preferred", "reason": "Repeated no-shows.", "review_on": "2026-10-08", "rehire_eligible": true }, "schema": { "$ref": "#/components/schemas/PoolMemberCreate" } } } }, "responses": { "201": { "description": "The created pool member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "talent_pool_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "level": "Preferred", "reason": "Repeated no-shows.", "review_on": "2026-10-08", "rehire_eligible": true }, "schema": { "$ref": "#/components/schemas/PoolMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pool-members/{id}": { "get": { "operationId": "poolMembers.get", "tags": ["Opportunities"], "x-xos-table": "app.pool_members", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a pool member", "description": "A pool member. Do Not Engage needs a reason and a review date and is never visible externally. Returns one pool member with its `ETag`. A pool member the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the pool member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the pool member.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The pool member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "talent_pool_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "level": "Preferred", "reason": "Repeated no-shows.", "review_on": "2026-10-08", "rehire_eligible": true }, "schema": { "$ref": "#/components/schemas/PoolMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "poolMembers.update", "tags": ["Opportunities"], "x-xos-table": "app.pool_members", "x-xos-capability": "opportunities.pool.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update a pool member", "description": "A pool member. Do Not Engage needs a reason and a review date and is never visible externally. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the pool member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the pool member.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "level": "Preferred", "reason": "Repeated no-shows.", "review_on": "2026-10-08", "rehire_eligible": true }, "schema": { "$ref": "#/components/schemas/PoolMemberUpdate" } } } }, "responses": { "200": { "description": "The updated pool member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "talent_pool_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "level": "Preferred", "reason": "Repeated no-shows.", "review_on": "2026-10-08", "rehire_eligible": true }, "schema": { "$ref": "#/components/schemas/PoolMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "poolMembers.delete", "tags": ["Opportunities"], "x-xos-table": "app.pool_members", "x-xos-capability": "opportunities.pool.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Delete a pool member", "description": "A pool member. Do Not Engage needs a reason and a review date and is never visible externally. Soft-deletes the pool member: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the pool member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the pool member.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The pool member moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ratings": { "get": { "operationId": "ratings.list", "tags": ["Opportunities"], "x-xos-table": "app.ratings", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List rating rows", "description": "A two-sided rating from a completed engagement, released together or after 14 days. Returns a cursor page of rating rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of rating rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rater_side": "org", "score": 5, "comment": "Prepared, punctual and safe.", "released_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RatingPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "ratings.create", "tags": ["Opportunities"], "x-xos-table": "app.ratings", "x-xos-capability": "opportunities.rating.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create a rating", "description": "A two-sided rating from a completed engagement, released together or after 14 days. Creates a rating. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rater_side": "org", "score": 5, "comment": "Prepared, punctual and safe." }, "schema": { "$ref": "#/components/schemas/RatingCreate" } } } }, "responses": { "201": { "description": "The created rating.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rater_side": "org", "score": 5, "comment": "Prepared, punctual and safe.", "released_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Rating" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ratings/{id}": { "get": { "operationId": "ratings.get", "tags": ["Opportunities"], "x-xos-table": "app.ratings", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a rating", "description": "A two-sided rating from a completed engagement, released together or after 14 days. Returns one rating with its `ETag`. A rating the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rating.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rating.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The rating.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rater_side": "org", "score": 5, "comment": "Prepared, punctual and safe.", "released_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Rating" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rating-replies": { "get": { "operationId": "ratingReplies.list", "tags": ["Opportunities"], "x-xos-table": "app.rating_replies", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List rating reply rows", "description": "A public reply from the rated party. Returns a cursor page of rating reply rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of rating reply rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rating_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Thank you, glad to work the series again." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RatingReplyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "ratingReplies.create", "tags": ["Opportunities"], "x-xos-table": "app.rating_replies", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a rating reply", "description": "A public reply from the rated party. Creates a rating reply. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "rating_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Thank you, glad to work the series again." }, "schema": { "$ref": "#/components/schemas/RatingReplyCreate" } } } }, "responses": { "201": { "description": "The created rating reply.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rating_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Thank you, glad to work the series again." }, "schema": { "$ref": "#/components/schemas/RatingReply" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/rating-replies/{id}": { "get": { "operationId": "ratingReplies.get", "tags": ["Opportunities"], "x-xos-table": "app.rating_replies", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a rating reply", "description": "A public reply from the rated party. Returns one rating reply with its `ETag`. A rating reply the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the rating reply.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the rating reply.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The rating reply.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rating_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Thank you, glad to work the series again." }, "schema": { "$ref": "#/components/schemas/RatingReply" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/marketplace/opportunities": { "get": { "operationId": "marketplace.search", "tags": ["Gateway"], "x-xos-table": "api_external.opportunities", "x-xos-capability": "opportunities.posting.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Search the marketplace", "description": "Searches opportunities the caller may see, by role type, discipline and category, distance, dates, rate and required certifications through the filter grammar. Ranking factors are published; no placement can be bought. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "example": "rigger" }, "required": false, "name": "q", "in": "query", "description": "Free-text search." }, { "schema": { "type": "string", "pattern": "^-?[0-9.]+,-?[0-9.]+$", "example": "25.7617,-80.1918" }, "required": false, "name": "near", "in": "query", "description": "Latitude and longitude to measure distance from." }, { "schema": { "type": "number", "exclusiveMinimum": 0, "example": 50 }, "required": false, "name": "radius_km", "in": "query", "description": "Search radius in kilometers." } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Stagehands for Harborfront Load-In", "role_type": "Crew", "role_code": "5000.50.01", "venue_locality": "Miami", "rate_type": "Day", "pay_min_minor": 32000, "pay_max_minor": 38000, "distance_km": 12.4, "org_name": "Northwind Live", "org_verified": true, "description": "Load-in and show calls for six weekends.", "cat_urid": "4000.01", "venue_name": "Harbor Lawn", "jurisdiction_id": "US-FL", "starts_on": "2026-10-08", "ends_on": "2026-10-08", "visibility": "Pool", "currency_code": "USD", "rate_on_request": false, "deadline_at": "2026-10-08T14:30:00Z", "minimum_age": 18, "opportunity_state": "Published", "position_count": 4 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MarketplaceListingPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-searches": { "get": { "operationId": "savedSearches.list", "tags": ["Gateway"], "x-xos-table": "app.saved_searches", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List saved search rows", "description": "A saved marketplace search that sends alerts. Returns a cursor page of saved search rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of saved search rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Miami Rigging Calls", "alerts_enabled": true, "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "jurisdiction_id": "US-FL", "starts_after": "2026-10-08", "ends_before": "2026-10-08", "min_rate_minor": 3500, "currency_code": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SavedSearchPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "savedSearches.create", "tags": ["Gateway"], "x-xos-table": "app.saved_searches", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a saved search", "description": "A saved marketplace search that sends alerts. Creates a saved search. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Miami Rigging Calls", "alerts_enabled": true, "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "jurisdiction_id": "US-FL", "starts_after": "2026-10-08", "ends_before": "2026-10-08", "min_rate_minor": 3500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/SavedSearchCreate" } } } }, "responses": { "201": { "description": "The created saved search.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Miami Rigging Calls", "alerts_enabled": true, "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "jurisdiction_id": "US-FL", "starts_after": "2026-10-08", "ends_before": "2026-10-08", "min_rate_minor": 3500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-searches/{id}": { "get": { "operationId": "savedSearches.get", "tags": ["Gateway"], "x-xos-table": "app.saved_searches", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a saved search", "description": "A saved marketplace search that sends alerts. Returns one saved search with its `ETag`. A saved search the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved search.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved search.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The saved search.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Miami Rigging Calls", "alerts_enabled": true, "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "jurisdiction_id": "US-FL", "starts_after": "2026-10-08", "ends_before": "2026-10-08", "min_rate_minor": 3500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "savedSearches.update", "tags": ["Gateway"], "x-xos-table": "app.saved_searches", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a saved search", "description": "A saved marketplace search that sends alerts. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved search.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved search.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Miami Rigging Calls", "alerts_enabled": true, "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "jurisdiction_id": "US-FL", "starts_after": "2026-10-08", "ends_before": "2026-10-08", "min_rate_minor": 3500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/SavedSearchUpdate" } } } }, "responses": { "200": { "description": "The updated saved search.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Miami Rigging Calls", "alerts_enabled": true, "role_type": "Crew", "role_code": "5000.50.01", "cat_urid": "4000.01", "jurisdiction_id": "US-FL", "starts_after": "2026-10-08", "ends_before": "2026-10-08", "min_rate_minor": 3500, "currency_code": "USD" }, "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "savedSearches.delete", "tags": ["Gateway"], "x-xos-table": "app.saved_searches", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a saved search", "description": "A saved marketplace search that sends alerts. Soft-deletes the saved search: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved search.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved search.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The saved search moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-alerts": { "get": { "operationId": "opportunityAlerts.list", "tags": ["Gateway"], "x-xos-table": "app.opportunity_alerts", "x-xos-capability": "me.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List opportunity alert rows", "description": "An alert raised for a saved search. Returns a cursor page of opportunity alert rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of opportunity alert rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "saved_search_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivered_at": "2026-10-08T14:30:00Z", "matched_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OpportunityAlertPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/opportunity-alerts/{id}": { "get": { "operationId": "opportunityAlerts.get", "tags": ["Gateway"], "x-xos-table": "app.opportunity_alerts", "x-xos-capability": "me.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get an opportunity alert", "description": "An alert raised for a saved search. Returns one opportunity alert with its `ETag`. A opportunity alert the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the opportunity alert.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the opportunity alert.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The opportunity alert.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "saved_search_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivered_at": "2026-10-08T14:30:00Z", "matched_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OpportunityAlert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/listing-reports": { "get": { "operationId": "listingReports.list", "tags": ["Gateway"], "x-xos-table": "app.listing_reports", "x-xos-capability": "opportunities.marketplace.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List listing report rows", "description": "A report against a listing or profile, handled through notice and action. Returns a cursor page of listing report rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of listing report rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "reason": "Illegal Content", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reporter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "details": "The listing asks for an upfront fee.", "reported_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ListingReportPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "listingReports.create", "tags": ["Gateway"], "x-xos-table": "app.listing_reports", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a listing report", "description": "A report against a listing or profile, handled through notice and action. Creates a listing report. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Illegal Content", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "details": "The listing asks for an upfront fee." }, "schema": { "$ref": "#/components/schemas/ListingReportCreate" } } } }, "responses": { "201": { "description": "The created listing report.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "reason": "Illegal Content", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reporter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "details": "The listing asks for an upfront fee.", "reported_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ListingReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/listing-reports/{id}": { "get": { "operationId": "listingReports.get", "tags": ["Gateway"], "x-xos-table": "app.listing_reports", "x-xos-capability": "opportunities.marketplace.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a listing report", "description": "A report against a listing or profile, handled through notice and action. Returns one listing report with its `ETag`. A listing report the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the listing report.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the listing report.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The listing report.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "reason": "Illegal Content", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reporter_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "details": "The listing asks for an upfront fee.", "reported_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ListingReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/moderation-actions": { "get": { "operationId": "moderationActions.list", "tags": ["Gateway"], "x-xos-table": "app.moderation_actions", "x-xos-capability": "opportunities.marketplace.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List moderation action rows", "description": "A moderation decision with a statement of reasons sent to the affected party. Returns a cursor page of moderation action rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of moderation action rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "listing_report_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "action": "Removed", "statement_of_reasons": "The listing requested a fee from applicants.", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ModerationActionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/moderation-actions/{id}": { "get": { "operationId": "moderationActions.get", "tags": ["Gateway"], "x-xos-table": "app.moderation_actions", "x-xos-capability": "opportunities.marketplace.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a moderation action", "description": "A moderation decision with a statement of reasons sent to the affected party. Returns one moderation action with its `ETag`. A moderation action the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the moderation action.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the moderation action.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The moderation action.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "listing_report_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "action": "Removed", "statement_of_reasons": "The listing requested a fee from applicants.", "opportunity_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ModerationAction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/profile-shares": { "get": { "operationId": "profileShares.list", "tags": ["Gateway"], "x-xos-table": "app.profile_shares", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List profile share rows", "description": "A consent snapshot of profile fields shared with one org. Live updates stop on revoke after close. Returns a cursor page of profile share rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of profile share rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shared_fields": [{ "field_key": "headline", "field_value": "Head Rigger" }], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProfileSharePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "profileShares.create", "tags": ["Gateway"], "x-xos-table": "app.profile_shares", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a profile share", "description": "A consent snapshot of profile fields shared with one org. Live updates stop on revoke after close. Creates a profile share. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shared_fields": [{ "field_key": "headline", "field_value": "Head Rigger" }], "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ProfileShareCreate" } } } }, "responses": { "201": { "description": "The created profile share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shared_fields": [{ "field_key": "headline", "field_value": "Head Rigger" }], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ProfileShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/profile-shares/{id}": { "get": { "operationId": "profileShares.get", "tags": ["Gateway"], "x-xos-table": "app.profile_shares", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a profile share", "description": "A consent snapshot of profile fields shared with one org. Live updates stop on revoke after close. Returns one profile share with its `ETag`. A profile share the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the profile share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the profile share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The profile share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shared_fields": [{ "field_key": "headline", "field_value": "Head Rigger" }], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ProfileShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/profile-shares/{id}/revoke": { "post": { "operationId": "profileShares.revoke", "tags": ["Gateway"], "x-xos-table": "app.profile_shares", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Revoke a profile share", "description": "Stops future updates to the org. The org keeps records it must retain by law. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the profile share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the profile share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shared_fields": [{ "field_key": "headline", "field_value": "Head Rigger" }], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ProfileShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/availability-calendars": { "get": { "operationId": "availabilityCalendars.list", "tags": ["Gateway"], "x-xos-table": "app.availability_calendars", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List availability calendar rows", "description": "A person's availability calendar. Returns a cursor page of availability calendar rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of availability calendar rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "visibility": "Private" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AvailabilityCalendarPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "availabilityCalendars.create", "tags": ["Gateway"], "x-xos-table": "app.availability_calendars", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an availability calendar", "description": "A person's availability calendar. Creates an availability calendar. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/AvailabilityCalendarCreate" } } } }, "responses": { "201": { "description": "The created availability calendar.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/AvailabilityCalendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/availability-calendars/{id}": { "get": { "operationId": "availabilityCalendars.get", "tags": ["Gateway"], "x-xos-table": "app.availability_calendars", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get an availability calendar", "description": "A person's availability calendar. Returns one availability calendar with its `ETag`. A availability calendar the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the availability calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the availability calendar.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The availability calendar.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/AvailabilityCalendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "availabilityCalendars.update", "tags": ["Gateway"], "x-xos-table": "app.availability_calendars", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update an availability calendar", "description": "A person's availability calendar. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the availability calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the availability calendar.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "time_zone": "America/New_York", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/AvailabilityCalendarUpdate" } } } }, "responses": { "200": { "description": "The updated availability calendar.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/AvailabilityCalendar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "availabilityCalendars.delete", "tags": ["Gateway"], "x-xos-table": "app.availability_calendars", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete an availability calendar", "description": "A person's availability calendar. Soft-deletes the availability calendar: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the availability calendar.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the availability calendar.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The availability calendar moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/availability-blocks": { "get": { "operationId": "availabilityBlocks.list", "tags": ["Gateway"], "x-xos-table": "app.availability_blocks", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List availability block rows", "description": "A block of availability or unavailability. Returns a cursor page of availability block rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of availability block rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "availability_calendar_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "availability_kind": "Available", "note": "Holding for a tour." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AvailabilityBlockPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "availabilityBlocks.create", "tags": ["Gateway"], "x-xos-table": "app.availability_blocks", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an availability block", "description": "A block of availability or unavailability. Creates an availability block. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "availability_calendar_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "availability_kind": "Available", "note": "Holding for a tour." }, "schema": { "$ref": "#/components/schemas/AvailabilityBlockCreate" } } } }, "responses": { "201": { "description": "The created availability block.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "availability_calendar_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "availability_kind": "Available", "note": "Holding for a tour." }, "schema": { "$ref": "#/components/schemas/AvailabilityBlock" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/availability-blocks/{id}": { "get": { "operationId": "availabilityBlocks.get", "tags": ["Gateway"], "x-xos-table": "app.availability_blocks", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get an availability block", "description": "A block of availability or unavailability. Returns one availability block with its `ETag`. A availability block the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the availability block.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the availability block.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The availability block.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "availability_calendar_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "availability_kind": "Available", "note": "Holding for a tour." }, "schema": { "$ref": "#/components/schemas/AvailabilityBlock" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "availabilityBlocks.update", "tags": ["Gateway"], "x-xos-table": "app.availability_blocks", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update an availability block", "description": "A block of availability or unavailability. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the availability block.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the availability block.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "availability_kind": "Available", "note": "Holding for a tour." }, "schema": { "$ref": "#/components/schemas/AvailabilityBlockUpdate" } } } }, "responses": { "200": { "description": "The updated availability block.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "availability_calendar_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "availability_kind": "Available", "note": "Holding for a tour." }, "schema": { "$ref": "#/components/schemas/AvailabilityBlock" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "availabilityBlocks.delete", "tags": ["Gateway"], "x-xos-table": "app.availability_blocks", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete an availability block", "description": "A block of availability or unavailability. Soft-deletes the availability block: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the availability block.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the availability block.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The availability block moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagement-threads": { "get": { "operationId": "engagementThreads.list", "tags": ["Gateway"], "x-xos-table": "app.engagement_threads", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List engagement thread rows", "description": "A message thread inside an engagement. Returns a cursor page of engagement thread rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of engagement thread rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": "Parking for Load-In" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EngagementThreadPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "engagementThreads.create", "tags": ["Gateway"], "x-xos-table": "app.engagement_threads", "x-xos-capability": "opportunities.engagement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an engagement thread", "description": "A message thread inside an engagement. Creates an engagement thread. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": "Parking for Load-In" }, "schema": { "$ref": "#/components/schemas/EngagementThreadCreate" } } } }, "responses": { "201": { "description": "The created engagement thread.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": "Parking for Load-In" }, "schema": { "$ref": "#/components/schemas/EngagementThread" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagement-threads/{id}": { "get": { "operationId": "engagementThreads.get", "tags": ["Gateway"], "x-xos-table": "app.engagement_threads", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an engagement thread", "description": "A message thread inside an engagement. Returns one engagement thread with its `ETag`. A engagement thread the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the engagement thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the engagement thread.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The engagement thread.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": "Parking for Load-In" }, "schema": { "$ref": "#/components/schemas/EngagementThread" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "engagementThreads.update", "tags": ["Gateway"], "x-xos-table": "app.engagement_threads", "x-xos-capability": "opportunities.engagement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Update an engagement thread", "description": "A message thread inside an engagement. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the engagement thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the engagement thread.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "subject": "Parking for Load-In" }, "schema": { "$ref": "#/components/schemas/EngagementThreadUpdate" } } } }, "responses": { "200": { "description": "The updated engagement thread.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": "Parking for Load-In" }, "schema": { "$ref": "#/components/schemas/EngagementThread" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagement-messages": { "get": { "operationId": "engagementMessages.list", "tags": ["Gateway"], "x-xos-table": "app.engagement_messages", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List engagement message rows", "description": "A message in an engagement thread. Returns a cursor page of engagement message rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of engagement message rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Use the north lot; passes are at the gate.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sent_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EngagementMessagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "engagementMessages.create", "tags": ["Gateway"], "x-xos-table": "app.engagement_messages", "x-xos-capability": "opportunities.engagement.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create an engagement message", "description": "A message in an engagement thread. Creates an engagement message. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Use the north lot; passes are at the gate." }, "schema": { "$ref": "#/components/schemas/EngagementMessageCreate" } } } }, "responses": { "201": { "description": "The created engagement message.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Use the north lot; passes are at the gate.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sent_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/EngagementMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/engagement-messages/{id}": { "get": { "operationId": "engagementMessages.get", "tags": ["Gateway"], "x-xos-table": "app.engagement_messages", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get an engagement message", "description": "A message in an engagement thread. Returns one engagement message with its `ETag`. A engagement message the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the engagement message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the engagement message.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The engagement message.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Use the north lot; passes are at the gate.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sent_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/EngagementMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tax-forms": { "get": { "operationId": "taxForms.list", "tags": ["Gateway"], "x-xos-table": "app.tax_forms", "x-xos-capability": "data.restricted.read.tax", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List tax form rows", "description": "A tax form. Restricted and encrypted; only the last four digits of the identifier are ever displayed. Returns a cursor page of tax form rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of tax form rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tin_last4": "6789", "foreign_performer_withholding": false, "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_kind": "W-9", "signed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TaxFormPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "taxForms.create", "tags": ["Gateway"], "x-xos-table": "app.tax_forms", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a tax form", "description": "A tax form. Restricted and encrypted; only the last four digits of the identifier are ever displayed. Creates a tax form. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "foreign_performer_withholding": false, "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_kind": "W-9", "tax_identifier": "123456789" }, "schema": { "$ref": "#/components/schemas/TaxFormCreate" } } } }, "responses": { "201": { "description": "The created tax form.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tin_last4": "6789", "foreign_performer_withholding": false, "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_kind": "W-9", "signed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TaxForm" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tax-forms/{id}": { "get": { "operationId": "taxForms.get", "tags": ["Gateway"], "x-xos-table": "app.tax_forms", "x-xos-capability": "data.restricted.read.tax", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get a tax form", "description": "A tax form. Restricted and encrypted; only the last four digits of the identifier are ever displayed. Returns one tax form with its `ETag`. A tax form the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tax form.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tax form.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The tax form.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tin_last4": "6789", "foreign_performer_withholding": false, "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_kind": "W-9", "signed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TaxForm" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payout-accounts": { "get": { "operationId": "payoutAccounts.list", "tags": ["Gateway"], "x-xos-table": "app.payout_accounts", "x-xos-capability": "data.restricted.read.banking", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List payout account rows", "description": "Payout details held by the payment provider. XOS stores provider references only. Returns a cursor page of payout account rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of payout account rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "Stripe Connect", "provider_account_reference": "acct_1PqRsT", "account_last4": "4421" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PayoutAccountPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "payoutAccounts.create", "tags": ["Gateway"], "x-xos-table": "app.payout_accounts", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a payout account", "description": "Payout details held by the payment provider. XOS stores provider references only. Creates a payout account. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "Stripe Connect", "provider_account_reference": "acct_1PqRsT" }, "schema": { "$ref": "#/components/schemas/PayoutAccountCreate" } } } }, "responses": { "201": { "description": "The created payout account.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "Stripe Connect", "provider_account_reference": "acct_1PqRsT", "account_last4": "4421" }, "schema": { "$ref": "#/components/schemas/PayoutAccount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payout-accounts/{id}": { "get": { "operationId": "payoutAccounts.get", "tags": ["Gateway"], "x-xos-table": "app.payout_accounts", "x-xos-capability": "data.restricted.read.banking", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get a payout account", "description": "Payout details held by the payment provider. XOS stores provider references only. Returns one payout account with its `ETag`. A payout account the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payout account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payout account.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The payout account.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "Stripe Connect", "provider_account_reference": "acct_1PqRsT", "account_last4": "4421" }, "schema": { "$ref": "#/components/schemas/PayoutAccount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "payoutAccounts.delete", "tags": ["Gateway"], "x-xos-table": "app.payout_accounts", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a payout account", "description": "Payout details held by the payment provider. XOS stores provider references only. Soft-deletes the payout account: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the payout account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the payout account.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The payout account moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/background-checks": { "get": { "operationId": "backgroundChecks.list", "tags": ["Gateway"], "x-xos-table": "app.background_checks", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List background check rows", "description": "A background check result from the provider. The report itself is never stored. Returns a cursor page of background check rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of background check rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "checkr", "provider_reference": "chk_7c1a2b", "completed_at": "2026-10-08T14:30:00Z", "result": "Pending" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BackgroundCheckPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "backgroundChecks.create", "tags": ["Gateway"], "x-xos-table": "app.background_checks", "x-xos-capability": "opportunities.onboarding.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Create a background check", "description": "A background check result from the provider. The report itself is never stored. Creates a background check. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "checkr", "provider_reference": "chk_7c1a2b" }, "schema": { "$ref": "#/components/schemas/BackgroundCheckCreate" } } } }, "responses": { "201": { "description": "The created background check.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "checkr", "provider_reference": "chk_7c1a2b", "completed_at": "2026-10-08T14:30:00Z", "result": "Pending" }, "schema": { "$ref": "#/components/schemas/BackgroundCheck" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/background-checks/{id}": { "get": { "operationId": "backgroundChecks.get", "tags": ["Gateway"], "x-xos-table": "app.background_checks", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a background check", "description": "A background check result from the provider. The report itself is never stored. Returns one background check with its `ETag`. A background check the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the background check.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the background check.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The background check.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider": "checkr", "provider_reference": "chk_7c1a2b", "completed_at": "2026-10-08T14:30:00Z", "result": "Pending" }, "schema": { "$ref": "#/components/schemas/BackgroundCheck" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/departments": { "get": { "operationId": "canonDepartments.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_department", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["dept_code"], "numeric": true }, "summary": "List canon department rows", "description": "A department class. Ten classes, always in numeric order. Returns a cursor page of canon department rows the caller may see. Coded list: the default order is numeric code order by `dept_code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon department rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dept_code": "0000", "department": "Executive", "source": "canon", "note": "Environment replaces the 3.0 label.", "executive_lead": "Executive Producer", "core_function": "Governance, master project control & compliance", "scope": "Master operations & overall accountability" }, { "dept_code": "4000", "department": "Environment", "source": "canon", "note": "Environment replaces the 3.0 label.", "executive_lead": "Executive Producer", "core_function": "Governance, master project control & compliance", "scope": "Master operations & overall accountability" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonDepartmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/departments/{dept_code}": { "get": { "operationId": "canonDepartments.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_department", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon department", "description": "A department class. Ten classes, always in numeric order. Returns one canon department with its `ETag`. A canon department the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/DeptCode" }, "required": true, "description": "Department class code from `xpms.dim_department` (Section 3.2).", "name": "dept_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon department.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "dept_code": "4000", "department": "Environment", "source": "canon", "note": "Environment replaces the 3.0 label.", "executive_lead": "Executive Producer", "core_function": "Governance, master project control & compliance", "scope": "Master operations & overall accountability" }, "schema": { "$ref": "#/components/schemas/CanonDepartment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/disciplines": { "get": { "operationId": "canonDisciplines.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_discipline", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["disc_code"], "numeric": true }, "summary": "List canon discipline rows", "description": "A discipline within a department class. Returns a cursor page of canon discipline rows the caller may see. Coded list: the default order is numeric code order by `disc_code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon discipline rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "disc_code": "0000.01", "dept_code": "0000", "discipline": "Executive Leadership & Strategy", "source": "canon" }, { "disc_code": "0000.02", "dept_code": "0000", "discipline": "Finance & Accounting", "source": "canon" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonDisciplinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/disciplines/{disc_code}": { "get": { "operationId": "canonDisciplines.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_discipline", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon discipline", "description": "A discipline within a department class. Returns one canon discipline with its `ETag`. A canon discipline the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/DiscCode" }, "required": true, "description": "Discipline code `DDDD.DD` from `xpms.dim_discipline`. Canon holds .01 to .49; tenant extensions hold .50 to .99.", "name": "disc_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon discipline.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "disc_code": "4000.01", "dept_code": "4000", "discipline": "Executive Leadership & Strategy", "source": "canon" }, "schema": { "$ref": "#/components/schemas/CanonDiscipline" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/categories": { "get": { "operationId": "canonCategories.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_category", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["cat_urid"], "numeric": true }, "summary": "List canon category rows", "description": "A category, the finest URID grain. Returns a cursor page of canon category rows the caller may see. Coded list: the default order is numeric code order by `cat_urid`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon category rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "cat_urid": "0000.01.01", "disc_code": "0000.01", "category": "Production Leadership", "source": "canon", "xyz": "X" }, { "cat_urid": "0000.02.01", "disc_code": "0000.02", "category": "Production Accounting", "source": "canon", "xyz": "X" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonCategoryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/categories/{cat_urid}": { "get": { "operationId": "canonCategories.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_category", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon category", "description": "A category, the finest URID grain. Returns one canon category with its `ETag`. A canon category the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/Urid" }, "required": true, "description": "Category URID `DDDD.DD.DD` from `xpms.dim_category` (Section 3.3). There is no fourth segment.", "name": "cat_urid", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon category.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "cat_urid": "4000.01.01", "disc_code": "4000.01", "category": "Production Leadership", "source": "canon", "xyz": "X" }, "schema": { "$ref": "#/components/schemas/CanonCategory" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/acts": { "get": { "operationId": "canonActs.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_act", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["ordinal"], "numeric": true }, "summary": "List canon act rows", "description": "An act: a presentation grouping of gates, never a control point. Returns a cursor page of canon act rows the caller may see. Coded list: the default order is numeric code order by `ordinal`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon act rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "ordinal": 1, "act_code": "PLAN", "definition": "Everything before money is committed." }, { "ordinal": 2, "act_code": "BUILD", "definition": "Everything before money is committed." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonActPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/acts/{act_code}": { "get": { "operationId": "canonActs.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_act", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon act", "description": "An act: a presentation grouping of gates, never a control point. Returns one canon act with its `ETag`. A canon act the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/ActCode" }, "required": true, "description": "Act from `xpms.dim_act`.", "name": "act_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon act.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "ordinal": 1, "act_code": "PLAN", "definition": "Everything before money is committed." }, "schema": { "$ref": "#/components/schemas/CanonAct" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/phases": { "get": { "operationId": "canonPhases.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_phase", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["gate"], "numeric": true }, "summary": "List canon phase rows", "description": "A gated phase. Nine phases with fixed, append-only ordinals. Returns a cursor page of canon phase rows the caller may see. Coded list: the default order is numeric code order by `gate`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon phase rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "gate": 1, "phase_code": "SCP", "phase": "Scope", "act_code": "PLAN", "definition": "What needs to happen.", "gate_exit": "Go or no-go ratified.", "is_redefined": false }, { "gate": 2, "phase_code": "ENG", "phase": "Engage", "act_code": "PLAN", "definition": "What needs to happen.", "gate_exit": "Go or no-go ratified.", "is_redefined": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonPhasePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/phases/{phase_code}": { "get": { "operationId": "canonPhases.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_phase", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon phase", "description": "A gated phase. Nine phases with fixed, append-only ordinals. Returns one canon phase with its `ETag`. A canon phase the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/PhaseCode" }, "required": true, "description": "Phase code from `xpms.dim_phase`, ordered by gate ordinal.", "name": "phase_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon phase.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "gate": 1, "phase_code": "SCP", "phase": "Scope", "act_code": "PLAN", "definition": "What needs to happen.", "gate_exit": "Go or no-go ratified.", "is_redefined": false }, "schema": { "$ref": "#/components/schemas/CanonPhase" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/gate-criteria": { "get": { "operationId": "canonGateCriteria.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_gate_criterion", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["gate", "criterion_id"], "numeric": true }, "summary": "List canon gate criterion rows", "description": "A gate criterion. Blocking criteria stop the gate transition in the database. Returns a cursor page of canon gate criterion rows the caller may see. Coded list: the default order is numeric code order by `gate`, then `criterion_id`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon gate criterion rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "gate": 1, "criterion_id": "G1.BUDGET_ENVELOPE", "statement": "A budget envelope exists and is approved.", "is_blocking": true }, { "gate": 2, "criterion_id": "G2.CONTRACTS", "statement": "A budget envelope exists and is approved.", "is_blocking": true } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonGateCriterionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/gate-criteria/{criterion_id}": { "get": { "operationId": "canonGateCriteria.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_gate_criterion", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon gate criterion", "description": "A gate criterion. Blocking criteria stop the gate transition in the database. Returns one canon gate criterion with its `ETag`. A canon gate criterion the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/CriterionId" }, "required": true, "description": "Gate criterion identifier from `xpms.dim_gate_criterion`.", "name": "criterion_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon gate criterion.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "gate": 1, "criterion_id": "G1.BUDGET_ENVELOPE", "statement": "A budget envelope exists and is approved.", "is_blocking": true }, "schema": { "$ref": "#/components/schemas/CanonGateCriterion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/tiers": { "get": { "operationId": "canonTiers.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_tier", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["tier_code"], "numeric": true }, "summary": "List canon tier rows", "description": "A tier of experience. International is never a tier. Returns a cursor page of canon tier rows the caller may see. Coded list: the default order is numeric code order by `tier_code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon tier rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "tier_code": "01", "tier": "Social" }, { "tier_code": "04", "tier": "Physical" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonTierPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/tiers/{tier_code}": { "get": { "operationId": "canonTiers.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_tier", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon tier", "description": "A tier of experience. International is never a tier. Returns one canon tier with its `ETag`. A canon tier the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/TierCode" }, "required": true, "description": "Tier of experience code from `xpms.dim_tier`.", "name": "tier_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon tier.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "tier_code": "04", "tier": "Physical" }, "schema": { "$ref": "#/components/schemas/CanonTier" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/teams": { "get": { "operationId": "canonTeams.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_team", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["team_id"], "numeric": true }, "summary": "List canon team rows", "description": "A canon team: a tag that rolls up to a department, never a tree level. Returns a cursor page of canon team rows the caller may see. Coded list: the default order is numeric code order by `team_id`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon team rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "team_id": "0000-T01", "team": "Executive Leadership", "dept_code": "0000", "workgroup_tag": "FOH", "lead_role": "Production Manager", "responsibilities": "Front of house operations." }, { "team_id": "0000-T02", "team": "Finance & Accounting", "dept_code": "0000", "workgroup_tag": "FOH", "lead_role": "Production Manager", "responsibilities": "Front of house operations." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonTeamPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/teams/{team_id}": { "get": { "operationId": "canonTeams.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_team", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon team", "description": "A canon team: a tag that rolls up to a department, never a tree level. Returns one canon team with its `ETag`. A canon team the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/TeamId" }, "required": true, "description": "Canon team identifier from `xpms.dim_team`.", "name": "team_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon team.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "team_id": "4000-T01", "team": "Executive Leadership", "dept_code": "4000", "workgroup_tag": "FOH", "lead_role": "Production Manager", "responsibilities": "Front of house operations." }, "schema": { "$ref": "#/components/schemas/CanonTeam" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/tags": { "get": { "operationId": "canonTags.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_tag", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["tag_id"], "numeric": true }, "summary": "List canon tag rows", "description": "A sustainability or compliance tag. Returns a cursor page of canon tag rows the caller may see. Coded list: the default order is numeric code order by `tag_id`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon tag rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "tag_id": "TAG-001", "tag_type": "Sustainability", "tag": "ELECTRIC" }, { "tag_id": "TAG-002", "tag_type": "Compliance", "tag": "OSHA" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonTagPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/tags/{tag_id}": { "get": { "operationId": "canonTags.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_tag", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon tag", "description": "A sustainability or compliance tag. Returns one canon tag with its `ETag`. A canon tag the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/TagId" }, "required": true, "description": "Sustainability or compliance tag from `xpms.dim_tag`.", "name": "tag_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon tag.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "tag_id": "TAG-002", "tag_type": "Compliance", "tag": "OSHA" }, "schema": { "$ref": "#/components/schemas/CanonTag" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/touchpoints": { "get": { "operationId": "canonTouchpoints.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_touchpoint", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["touchpoint_id"], "numeric": true }, "summary": "List canon touchpoint rows", "description": "A five-sense touchpoint with Base, Elevated and Premium grades. Returns a cursor page of canon touchpoint rows the caller may see. Coded list: the default order is numeric code order by `touchpoint_id`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon touchpoint rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "touchpoint_id": "SGT-01", "sense": "Architecture (Sight)", "brief_element": "Floor Plan", "category": "Stage Configuration", "item": "Ground-Level Stage", "base": "Low-rise deck stage.", "elevated": "Deck stage with skirted fascia.", "premium": "Custom-fabricated floor stage.", "optional_upgrades": "Stage-front lighting ribbon." }, { "touchpoint_id": "SGT-02", "sense": "Architecture (Sight)", "brief_element": "Floor Plan", "category": "Stage Configuration", "item": "Ground-Level Stage", "base": "Low-rise deck stage.", "elevated": "Deck stage with skirted fascia.", "premium": "Custom-fabricated floor stage.", "optional_upgrades": "Stage-front lighting ribbon." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonTouchpointPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/touchpoints/{touchpoint_id}": { "get": { "operationId": "canonTouchpoints.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_touchpoint", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon touchpoint", "description": "A five-sense touchpoint with Base, Elevated and Premium grades. Returns one canon touchpoint with its `ETag`. A canon touchpoint the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/TouchpointId" }, "required": true, "description": "Five-sense touchpoint identifier from `xpms.dim_touchpoint`.", "name": "touchpoint_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon touchpoint.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "touchpoint_id": "SGT-01", "sense": "Architecture (Sight)", "brief_element": "Floor Plan", "category": "Stage Configuration", "item": "Ground-Level Stage", "base": "Low-rise deck stage.", "elevated": "Deck stage with skirted fascia.", "premium": "Custom-fabricated floor stage.", "optional_upgrades": "Stage-front lighting ribbon." }, "schema": { "$ref": "#/components/schemas/CanonTouchpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/jurisdictions": { "get": { "operationId": "canonJurisdictions.list", "tags": ["Canon"], "x-xos-table": "xpms.jurisdiction", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["jurisdiction_id"], "numeric": false }, "summary": "List canon jurisdiction rows", "description": "A jurisdiction. An unpopulated jurisdiction returns no answer for permit and code questions. Returns a cursor page of canon jurisdiction rows the caller may see. The default order is `jurisdiction_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon jurisdiction rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "jurisdiction_id": "US-FL", "level": "region", "country": "US", "parent": "US-FL", "unit_system": "imperial", "currency": "USD", "status": "populated", "note": "Florida amendments to the model codes." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonJurisdictionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/jurisdictions/{jurisdiction_id}": { "get": { "operationId": "canonJurisdictions.get", "tags": ["Canon"], "x-xos-table": "xpms.jurisdiction", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon jurisdiction", "description": "A jurisdiction. An unpopulated jurisdiction returns no answer for permit and code questions. Returns one canon jurisdiction with its `ETag`. A canon jurisdiction the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/JurisdictionId" }, "required": true, "description": "Jurisdiction identifier from `xpms.dim_jurisdiction`. An unpopulated jurisdiction returns no answer.", "name": "jurisdiction_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon jurisdiction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "jurisdiction_id": "US-FL", "level": "region", "country": "US", "parent": "US-FL", "unit_system": "imperial", "currency": "USD", "status": "populated", "note": "Florida amendments to the model codes." }, "schema": { "$ref": "#/components/schemas/CanonJurisdiction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/regions": { "get": { "operationId": "canonRegions.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_region", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["region_code"], "numeric": false }, "summary": "List canon region rows", "description": "A cost region. Only ratified multipliers answer; others refuse. Returns a cursor page of canon region rows the caller may see. The default order is `region_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon region rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "region_code": "NA-SE-MIA", "name": "Miami and South Florida", "jurisdiction_id": "US-FL", "currency_code": "USD", "note": "Basis region." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonRegionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/regions/{region_code}": { "get": { "operationId": "canonRegions.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_region", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon region", "description": "A cost region. Only ratified multipliers answer; others refuse. Returns one canon region with its `ETag`. A canon region the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/RegionCode" }, "required": true, "description": "Cost region code from `xpms.dim_region`.", "name": "region_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon region.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "region_code": "NA-SE-MIA", "name": "Miami and South Florida", "jurisdiction_id": "US-FL", "currency_code": "USD", "note": "Basis region." }, "schema": { "$ref": "#/components/schemas/CanonRegion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/region-multipliers": { "get": { "operationId": "canonRegionMultipliers.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_region_multiplier", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["region_code"], "numeric": false }, "summary": "List canon region multiplier rows", "description": "A cost multiplier for a region, with its ratification. Returns a cursor page of canon region multiplier rows the caller may see. The default order is `region_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon region multiplier rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "region_code": "NA-SE-MIA", "cost_multiplier": 1, "is_basis": false }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonRegionMultiplierPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/region-multipliers/{region_code}": { "get": { "operationId": "canonRegionMultipliers.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_region_multiplier", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon region multiplier", "description": "A cost multiplier for a region, with its ratification. Returns one canon region multiplier with its `ETag`. A canon region multiplier the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/RegionCode" }, "required": true, "description": "Cost region code from `xpms.dim_region`.", "name": "region_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon region multiplier.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "region_code": "NA-SE-MIA", "cost_multiplier": 1, "is_basis": false }, "schema": { "$ref": "#/components/schemas/CanonRegionMultiplier" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/escalation-indices": { "get": { "operationId": "canonEscalationIndices.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_escalation_index", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["index_id"], "numeric": false }, "summary": "List canon escalation index rows", "description": "A price escalation index. Returns a cursor page of canon escalation index rows the caller may see. The default order is `index_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon escalation index rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "index_id": "BLS-CPI-U", "name": "US CPI-U, all items", "applies_to": "US-FL", "note": "Default escalation basis." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonEscalationIndexPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/escalation-indices/{index_id}": { "get": { "operationId": "canonEscalationIndices.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_escalation_index", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon escalation index", "description": "A price escalation index. Returns one canon escalation index with its `ETag`. A canon escalation index the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Index identifier.", "example": "BLS-CPI-U" }, "required": true, "description": "Index identifier.", "name": "index_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon escalation index.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "index_id": "BLS-CPI-U", "name": "US CPI-U, all items", "applies_to": "US-FL", "note": "Default escalation basis." }, "schema": { "$ref": "#/components/schemas/CanonEscalationIndex" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/staleness-policies": { "get": { "operationId": "canonStalenessPolicies.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_staleness_policy", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["age_months_gte"], "numeric": true }, "summary": "List canon staleness policy rows", "description": "A staleness step: how a price band degrades with age. Returns a cursor page of canon staleness policy rows the caller may see. Coded list: the default order is numeric code order by `age_months_gte`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon staleness policy rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "age_months_gte": 12, "action": "degrade", "detail": "Degrade one step." }, { "age_months_gte": 24, "action": "degrade", "detail": "Degrade one step." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonStalenessPolicyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/staleness-policies/{age_months_gte}": { "get": { "operationId": "canonStalenessPolicies.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_staleness_policy", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon staleness policy", "description": "A staleness step: how a price band degrades with age. Returns one canon staleness policy with its `ETag`. A canon staleness policy the caller may not see returns 404.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "description": "Age in months at which the action applies.", "example": 12 }, "required": true, "description": "Age in months at which the action applies.", "name": "age_months_gte", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon staleness policy.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "age_months_gte": 12, "action": "degrade", "detail": "Degrade one step." }, "schema": { "$ref": "#/components/schemas/CanonStalenessPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/permit-rules": { "get": { "operationId": "canonPermitRules.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_permit_rule", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["rule"], "numeric": false }, "summary": "List canon permit rule rows", "description": "A permit rule of the jurisdiction permit engine. Returns a cursor page of canon permit rule rows the caller may see. The default order is `rule` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon permit rule rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "rule": "Assembly occupancy", "trigger_type": "threshold", "condition": "Occupant load of 50 or more.", "permit": "Certificate of occupancy", "ahj": "City Building and Fire", "lead_time": "4-8 wks", "jurisdiction_id": "US-FL", "provenance": "operator", "note": "Triggered by occupant load." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonPermitRulePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/permit-rules/{rule}": { "get": { "operationId": "canonPermitRules.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_permit_rule", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon permit rule", "description": "A permit rule of the jurisdiction permit engine. Returns one canon permit rule with its `ETag`. A canon permit rule the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Rule name.", "example": "Assembly occupancy" }, "required": true, "description": "Rule name.", "name": "rule", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon permit rule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "rule": "Assembly occupancy", "trigger_type": "threshold", "condition": "Occupant load of 50 or more.", "permit": "Certificate of occupancy", "ahj": "City Building and Fire", "lead_time": "4-8 wks", "jurisdiction_id": "US-FL", "provenance": "operator", "note": "Triggered by occupant load." }, "schema": { "$ref": "#/components/schemas/CanonPermitRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/metrics": { "get": { "operationId": "canonMetrics.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_metric", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["item"], "numeric": false }, "summary": "List canon metric rows", "description": "A metric, often code-derived and jurisdiction-bound. Returns a cursor page of canon metric rows the caller may see. The default order is `item` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon metric rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "domain": "capacity", "item": "Stage or performance area", "value_numeric": 15, "qualifier": "IBC 1005.3.2 - 0.2 in per occupant", "source": "IBC 1004.5", "is_code_derived": true, "jurisdiction_id": "US-FL", "is_jurisdiction_neutral": false, "provenance": "operator", "value_text": "Per show day" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonMetricPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/metrics/{item}": { "get": { "operationId": "canonMetrics.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_metric", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon metric", "description": "A metric, often code-derived and jurisdiction-bound. Returns one canon metric with its `ETag`. A canon metric the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Metric item.", "example": "Stage or performance area" }, "required": true, "description": "Metric item.", "name": "item", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon metric.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "domain": "capacity", "item": "Stage or performance area", "value_numeric": 15, "qualifier": "IBC 1005.3.2 - 0.2 in per occupant", "source": "IBC 1004.5", "is_code_derived": true, "jurisdiction_id": "US-FL", "is_jurisdiction_neutral": false, "provenance": "operator", "value_text": "Per show day" }, "schema": { "$ref": "#/components/schemas/CanonMetric" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/identifier-classes": { "get": { "operationId": "canonIdentifierClasses.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_identifier_class", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["class"], "numeric": false }, "summary": "List canon identifier class rows", "description": "Identifier grammar: identifier, code or token (Section 3.6). Returns a cursor page of canon identifier class rows the caller may see. The default order is `class` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon identifier class rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "class": "identifier", "issued_by": "An external authority", "scope": "Global", "is_mutable": false, "rule": "Recorded and validated, never minted.", "examples": "GTIN, MPN, UNSPSC" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonIdentifierClassPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/identifier-classes/{class}": { "get": { "operationId": "canonIdentifierClasses.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_identifier_class", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon identifier class", "description": "Identifier grammar: identifier, code or token (Section 3.6). Returns one canon identifier class with its `ETag`. A canon identifier class the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Identifier class.", "example": "identifier" }, "required": true, "description": "Identifier class.", "name": "class", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon identifier class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "class": "identifier", "issued_by": "An external authority", "scope": "Global", "is_mutable": false, "rule": "Recorded and validated, never minted.", "examples": "GTIN, MPN, UNSPSC" }, "schema": { "$ref": "#/components/schemas/CanonIdentifierClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/grains": { "get": { "operationId": "canonGrains.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_grain", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["grain"], "numeric": false }, "summary": "List canon grain rows", "description": "Grain: class, unit or lot (Section 3.9). Returns a cursor page of canon grain rows the caller may see. The default order is `grain` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon grain rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "grain": "unit", "counts": "One physical thing", "identified_by": "Serial or asset tag", "answers": "Where is this one?", "note": "Tracked individually." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonGrainPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/grains/{grain}": { "get": { "operationId": "canonGrains.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_grain", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon grain", "description": "Grain: class, unit or lot (Section 3.9). Returns one canon grain with its `ETag`. A canon grain the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/GrainCode" }, "required": true, "description": "Grain from `xpms.dim_grain` (Section 3.9).", "name": "grain", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon grain.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "grain": "unit", "counts": "One physical thing", "identified_by": "Serial or asset tag", "answers": "Where is this one?", "note": "Tracked individually." }, "schema": { "$ref": "#/components/schemas/CanonGrain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/provenances": { "get": { "operationId": "canonProvenances.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_provenance", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["provenance"], "numeric": false }, "summary": "List canon provenance rows", "description": "A provenance rank. A lower rank never overwrites a populated higher-rank field. Returns a cursor page of canon provenance rows the caller may see. The default order is `provenance` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon provenance rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "provenance": "operator", "rank": 80, "definition": "A tenant human entering a fact.", "may_overwrite": "Any field not canon-locked", "max_confidence": "QUOTED" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonProvenancePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/provenances/{provenance}": { "get": { "operationId": "canonProvenances.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_provenance", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon provenance", "description": "A provenance rank. A lower rank never overwrites a populated higher-rank field. Returns one canon provenance with its `ETag`. A canon provenance the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/Provenance" }, "required": true, "description": "Provenance from `xpms.dim_provenance` (Section 3.8); a lower rank never overwrites a higher one.", "name": "provenance", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon provenance.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "provenance": "operator", "rank": 80, "definition": "A tenant human entering a fact.", "may_overwrite": "Any field not canon-locked", "max_confidence": "QUOTED" }, "schema": { "$ref": "#/components/schemas/CanonProvenance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/facets": { "get": { "operationId": "canonFacets.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_facet", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["facet"], "numeric": false }, "summary": "List canon facet rows", "description": "A facet carried from canon. Returns a cursor page of canon facet rows the caller may see. The default order is `facet` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon facet rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "facet": "Phase", "form": "Nine gated phases", "rolls_up_to": "Act", "since": "3.0", "note": "Carried from canon." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonFacetPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/facets/{facet}": { "get": { "operationId": "canonFacets.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_facet", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon facet", "description": "A facet carried from canon. Returns one canon facet with its `ETag`. A canon facet the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Facet name.", "example": "Phase" }, "required": true, "description": "Facet name.", "name": "facet", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon facet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "facet": "Phase", "form": "Nine gated phases", "rolls_up_to": "Act", "since": "3.0", "note": "Carried from canon." }, "schema": { "$ref": "#/components/schemas/CanonFacet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/assertion-ranks": { "get": { "operationId": "canonAssertionRanks.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_assertion_rank", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["rank"], "numeric": false }, "summary": "List canon assertion rank rows", "description": "An assertion rank, 4 down to 0, across economics, compliance and capability. Returns a cursor page of canon assertion rank rows the caller may see. The default order is `rank` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon assertion rank rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "rank": 4, "meaning": "Attested by a named accountable party.", "note": "A vendor quote." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonAssertionRankPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/assertion-ranks/{rank}": { "get": { "operationId": "canonAssertionRanks.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_assertion_rank", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon assertion rank", "description": "An assertion rank, 4 down to 0, across economics, compliance and capability. Returns one canon assertion rank with its `ETag`. A canon assertion rank the caller may not see returns 404.", "parameters": [ { "schema": { "type": "integer", "minimum": 0, "description": "Assertion rank.", "example": 4 }, "required": true, "description": "Assertion rank.", "name": "rank", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon assertion rank.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "rank": 4, "meaning": "Attested by a named accountable party.", "note": "A vendor quote." }, "schema": { "$ref": "#/components/schemas/CanonAssertionRank" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/record-kinds": { "get": { "operationId": "canonRecordKinds.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_record_kind", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_kind"], "numeric": false }, "summary": "List canon record kind rows", "description": "A record kind with its class, definition of done and title grammar. Returns a cursor page of canon record kind rows the caller may see. The default order is `record_kind` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon record kind rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_kind": "Task", "definition": "A unit of assigned work.", "definition_of_done": "Done against its acceptance.", "record_class": "Work", "title_grammar": "Imperative verb first." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonRecordKindPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/record-kinds/{record_kind}": { "get": { "operationId": "canonRecordKinds.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_record_kind", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon record kind", "description": "A record kind with its class, definition of done and title grammar. Returns one canon record kind with its `ETag`. A canon record kind the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/RecordKind" }, "required": true, "description": "Record kind from `xpms.dim_record_kind` (26 kinds, Section 3.10).", "name": "record_kind", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon record kind.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_kind": "Task", "definition": "A unit of assigned work.", "definition_of_done": "Done against its acceptance.", "record_class": "Work", "title_grammar": "Imperative verb first." }, "schema": { "$ref": "#/components/schemas/CanonRecordKind" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/record-subtypes": { "get": { "operationId": "canonRecordSubtypes.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_record_subtype", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_subtype"], "numeric": false }, "summary": "List canon record subtype rows", "description": "A kind-scoped record subtype. Returns a cursor page of canon record subtype rows the caller may see. The default order is `record_subtype` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon record subtype rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_kind": "Task", "record_subtype": "Design", "unspsc_segment": "52160000 Audio and visual equipment and accessories" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonRecordSubtypePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/record-subtypes/{record_subtype}": { "get": { "operationId": "canonRecordSubtypes.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_record_subtype", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon record subtype", "description": "A kind-scoped record subtype. Returns one canon record subtype with its `ETag`. A canon record subtype the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/RecordSubtype" }, "required": true, "description": "Kind-scoped record subtype from `xpms.dim_record_subtype`. A subtype of one kind cannot be stored on another.", "name": "record_subtype", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon record subtype.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_kind": "Task", "record_subtype": "Design", "unspsc_segment": "52160000 Audio and visual equipment and accessories" }, "schema": { "$ref": "#/components/schemas/CanonRecordSubtype" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/record-states": { "get": { "operationId": "canonRecordStates.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_record_state", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_state"], "numeric": false }, "summary": "List canon record state rows", "description": "A record state with its meaning, in lifecycle order. Returns a cursor page of canon record state rows the caller may see. The default order is `record_state` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon record state rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "record_state": "Scheduled", "meaning": "Dated and resourced." }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonRecordStatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/record-states/{record_state}": { "get": { "operationId": "canonRecordStates.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_record_state", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon record state", "description": "A record state with its meaning, in lifecycle order. Returns one canon record state with its `ETag`. A canon record state the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/RecordState" }, "required": true, "description": "Record state (Section 3.10). Blocked names its blocker, Deferred carries a replan reason, Canceled is retained.", "name": "record_state", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon record state.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_state": "Scheduled", "meaning": "Dated and resourced." }, "schema": { "$ref": "#/components/schemas/CanonRecordState" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/roles": { "get": { "operationId": "canonRoles.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_role", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["role_code"], "numeric": true }, "summary": "List canon role rows", "description": "A workforce role with its staffing ratio. Returns a cursor page of canon role rows the caller may see. Coded list: the default order is numeric code order by `role_code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon role rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "role_code": "0000.50.01", "role": "Client sponsorship", "dept_code": "0000", "staffing_ratio": 250, "ratio_basis": "Guests", "kit_basis": "Per person", "job_title": "Head Rigger" }, { "role_code": "0000.50.02", "role": "Operator leadership", "dept_code": "0000", "staffing_ratio": 250, "ratio_basis": "Guests", "kit_basis": "Per person", "job_title": "Head Rigger" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonRolePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/roles/{role_code}": { "get": { "operationId": "canonRoles.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_role", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon role", "description": "A workforce role with its staffing ratio. Returns one canon role with its `ETag`. A canon role the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/RoleCode" }, "required": true, "description": "Workforce role code from `xpms.dim_role`, on URID grammar.", "name": "role_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "role_code": "5000.50.01", "role": "Rigging lead", "dept_code": "4000", "staffing_ratio": 250, "ratio_basis": "Guests", "kit_basis": "Per person", "job_title": "Head Rigger" }, "schema": { "$ref": "#/components/schemas/CanonRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/counterparty-types": { "get": { "operationId": "canonCounterpartyTypes.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_counterparty_type", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["counterparty_type"], "numeric": false }, "summary": "List canon counterparty type rows", "description": "A vendor counterparty type. Returns a cursor page of canon counterparty type rows the caller may see. The default order is `counterparty_type` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon counterparty type rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "counterparty_type": "AV Integrator", "definition": "Designs and installs audiovisual systems.", "classification_code": "CP-AVINT", "vendor_class": "Class B", "clearance_tier": "Tier 2 - Technical Lead", "default_account_code": "5400" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonCounterpartyTypePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/counterparty-types/{counterparty_type}": { "get": { "operationId": "canonCounterpartyTypes.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_counterparty_type", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon counterparty type", "description": "A vendor counterparty type. Returns one canon counterparty type with its `ETag`. A canon counterparty type the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/CounterpartyType" }, "required": true, "description": "Counterparty type from `xpms.dim_counterparty_type`.", "name": "counterparty_type", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon counterparty type.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "counterparty_type": "AV Integrator", "definition": "Designs and installs audiovisual systems.", "classification_code": "CP-AVINT", "vendor_class": "Class B", "clearance_tier": "Tier 2 - Technical Lead", "default_account_code": "5400" }, "schema": { "$ref": "#/components/schemas/CanonCounterpartyType" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/gl-accounts": { "get": { "operationId": "canonGlAccounts.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_gl_account", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["account_code"], "numeric": true }, "summary": "List canon gl account rows", "description": "A GL account in the fixed 23-account chart. Tenants cannot add accounts. Returns a cursor page of canon gl account rows the caller may see. Coded list: the default order is numeric code order by `account_code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon gl account rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "account_code": "1000", "account_name": "Cash and Bank", "account_type": "Asset", "tax_type": "None", "description": "Environment class costs.", "normal_balance": "Debit" }, { "account_code": "5400", "account_name": "Environment", "account_type": "Expense", "tax_type": "Tax on Purchases", "description": "Environment class costs.", "normal_balance": "Debit" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonGlAccountPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/gl-accounts/{account_code}": { "get": { "operationId": "canonGlAccounts.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_gl_account", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon gl account", "description": "A GL account in the fixed 23-account chart. Tenants cannot add accounts. Returns one canon gl account with its `ETag`. A canon gl account the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/GlAccountCode" }, "required": true, "description": "GL account code from the fixed chart in `xpms.dim_gl_account` (Section 3.11).", "name": "account_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon gl account.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "account_code": "5400", "account_name": "Environment", "account_type": "Expense", "tax_type": "Tax on Purchases", "description": "Environment class costs.", "normal_balance": "Debit" }, "schema": { "$ref": "#/components/schemas/CanonGlAccount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/cost-center-templates": { "get": { "operationId": "canonCostCenterTemplates.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_cost_center_template", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["cost_center_id"], "numeric": false }, "summary": "List canon cost center template rows", "description": "A cost center template (GL dimension 1). Returns a cursor page of canon cost center template rows the caller may see. The default order is `cost_center_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon cost center template rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "cost_center_id": "CC-VENUE", "cost_center": "Venue Standing Operations", "kind": "Standing", "scope_code": "E01", "note": "Runs whether or not an event does." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonCostCenterTemplatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/cost-center-templates/{cost_center_id}": { "get": { "operationId": "canonCostCenterTemplates.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_cost_center_template", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon cost center template", "description": "A cost center template (GL dimension 1). Returns one canon cost center template with its `ETag`. A canon cost center template the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/CostCenterCode" }, "required": true, "description": "Cost center identifier (GL dimension 1).", "name": "cost_center_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon cost center template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "cost_center_id": "CC-VENUE", "cost_center": "Venue Standing Operations", "kind": "Standing", "scope_code": "E01", "note": "Runs whether or not an event does." }, "schema": { "$ref": "#/components/schemas/CanonCostCenterTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/category-gl": { "get": { "operationId": "canonCategoryGl.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_category_gl", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["cat_urid"], "numeric": true }, "summary": "List canon category gl rows", "description": "The GL account each category posts to. Returns a cursor page of canon category gl rows the caller may see. Coded list: the default order is numeric code order by `cat_urid`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon category gl rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "cat_urid": "0000.01.01", "default_cost_center": "Production", "account_code": "5400" }, { "cat_urid": "0000.02.01", "default_cost_center": "Production", "account_code": "5400" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonCategoryGlPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/category-gl/{cat_urid}": { "get": { "operationId": "canonCategoryGl.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_category_gl", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon category gl", "description": "The GL account each category posts to. Returns one canon category gl with its `ETag`. A canon category gl the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/Urid" }, "required": true, "description": "Category URID `DDDD.DD.DD` from `xpms.dim_category` (Section 3.3). There is no fourth segment.", "name": "cat_urid", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon category gl.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "cat_urid": "4000.01.01", "default_cost_center": "Production", "account_code": "5400" }, "schema": { "$ref": "#/components/schemas/CanonCategoryGl" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/unit-aliases": { "get": { "operationId": "canonUnitAliases.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_unit_alias", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["alias"], "numeric": false }, "summary": "List canon unit alias rows", "description": "An alias of a controlled unit. Returns a cursor page of canon unit alias rows the caller may see. The default order is `alias` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon unit alias rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "alias": "ea", "unit_code": "ea", "dimension_code": "length" }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonUnitAliasPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/unit-aliases/{alias}": { "get": { "operationId": "canonUnitAliases.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_unit_alias", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon unit alias", "description": "An alias of a controlled unit. Returns one canon unit alias with its `ETag`. A canon unit alias the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Alias as written.", "example": "ea" }, "required": true, "description": "Alias as written.", "name": "alias", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon unit alias.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "alias": "ea", "unit_code": "ea", "dimension_code": "length" }, "schema": { "$ref": "#/components/schemas/CanonUnitAlias" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/unit-dimensions": { "get": { "operationId": "canonUnitDimensions.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_unit_dimension", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["dimension_code"], "numeric": false }, "summary": "List canon unit dimension rows", "description": "A controlled unit and the dimension it measures. Returns a cursor page of canon unit dimension rows the caller may see. The default order is `dimension_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon unit dimension rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "dimension_code": "length", "name": "Length" }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonUnitDimensionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/unit-dimensions/{dimension_code}": { "get": { "operationId": "canonUnitDimensions.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_unit_dimension", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon unit dimension", "description": "A controlled unit and the dimension it measures. Returns one canon unit dimension with its `ETag`. A canon unit dimension the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Dimension code.", "example": "length" }, "required": true, "description": "Dimension code.", "name": "dimension_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon unit dimension.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "dimension_code": "length", "name": "Length" }, "schema": { "$ref": "#/components/schemas/CanonUnitDimension" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/urn-namespaces": { "get": { "operationId": "canonUrnNamespaces.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_urn_namespace", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["kind"], "numeric": false }, "summary": "List canon urn namespace rows", "description": "A URN kind under `urn:xpms`. Returns a cursor page of canon urn namespace rows the caller may see. The default order is `kind` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon urn namespace rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "kind": "category", "table_name": "elements", "key_column": "element_id", "label_column": "item" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonUrnNamespacePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/urn-namespaces/{kind}": { "get": { "operationId": "canonUrnNamespaces.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_urn_namespace", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon urn namespace", "description": "A URN kind under `urn:xpms`. Returns one canon urn namespace with its `ETag`. A canon urn namespace the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "URN kind.", "example": "category" }, "required": true, "description": "URN kind.", "name": "kind", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon urn namespace.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "kind": "category", "table_name": "elements", "key_column": "element_id", "label_column": "item" }, "schema": { "$ref": "#/components/schemas/CanonUrnNamespace" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/locales": { "get": { "operationId": "canonLocales.list", "tags": ["Canon"], "x-xos-table": "xpms.dim_locale", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["locale_code"], "numeric": false }, "summary": "List canon locale rows", "description": "A supported locale. Returns a cursor page of canon locale rows the caller may see. The default order is `locale_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon locale rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "locale_code": "en-US", "name": "English (United States)", "is_source": true, "release_stage": "general" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonLocalePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/locales/{locale_code}": { "get": { "operationId": "canonLocales.get", "tags": ["Canon"], "x-xos-table": "xpms.dim_locale", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon locale", "description": "A supported locale. Returns one canon locale with its `ETag`. A canon locale the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$", "description": "BCP 47 locale tag.", "example": "en-US" }, "required": true, "description": "BCP 47 locale tag.", "name": "locale_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon locale.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "locale_code": "en-US", "name": "English (United States)", "is_source": true, "release_stage": "general" }, "schema": { "$ref": "#/components/schemas/CanonLocale" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/elements": { "get": { "operationId": "canonElements.list", "tags": ["Canon"], "x-xos-table": "xpms.elements", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["element_id"], "numeric": true }, "summary": "List canon element rows", "description": "A catalog element, the unit of the catalog. Returns a cursor page of canon element rows the caller may see. Coded list: the default order is numeric code order by `element_id`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon element rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "element_id": "0000.51.01-XOS-001", "urid": "4000.01.01", "item": "Ground Stage Deck", "common_name": "Stage deck", "kind": "rental", "unit_basis": "ea", "xyz": "X", "xyz_basis": "Physical inventory", "grade": "Standard", "description": "Line array for outdoor stages.", "specification": "12 cabinets per side.", "tier_code": "04", "lead_time_hours": 48, "crew": "2 audio technicians", "unspsc": "52161512", "lifecycle_state": "Active", "purchase_account": "5400", "default_cost_center": "CC-CORP", "external_ref": "TECH-VIDO-CAMR-001 · 5000.050.00" }, { "element_id": "4000.01.01-XPMS-001", "urid": "4000.01.01", "item": "Ground Stage Deck", "common_name": "Stage deck", "kind": "rental", "unit_basis": "ea", "xyz": "X", "xyz_basis": "Physical inventory", "grade": "Standard", "description": "Line array for outdoor stages.", "specification": "12 cabinets per side.", "tier_code": "04", "lead_time_hours": 48, "crew": "2 audio technicians", "unspsc": "52161512", "lifecycle_state": "Active", "purchase_account": "5400", "default_cost_center": "CC-CORP", "external_ref": "TECH-VIDO-CAMR-001 · 5000.050.00" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonElementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/elements/{element_id}": { "get": { "operationId": "canonElements.get", "tags": ["Canon"], "x-xos-table": "xpms.elements", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon element", "description": "A catalog element, the unit of the catalog. Returns one canon element with its `ETag`. A canon element the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/ItemId" }, "required": true, "description": "Catalog item identifier `{URID}-{ORG}-{SEQ}` (Section 3.6).", "name": "element_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon element.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "element_id": "4000.01.01-XPMS-001", "urid": "4000.01.01", "item": "Ground Stage Deck", "common_name": "Stage deck", "kind": "rental", "unit_basis": "ea", "xyz": "X", "xyz_basis": "Physical inventory", "grade": "Standard", "description": "Line array for outdoor stages.", "specification": "12 cabinets per side.", "tier_code": "04", "lead_time_hours": 48, "crew": "2 audio technicians", "unspsc": "52161512", "lifecycle_state": "Active", "purchase_account": "5400", "default_cost_center": "CC-CORP", "external_ref": "TECH-VIDO-CAMR-001 · 5000.050.00" }, "schema": { "$ref": "#/components/schemas/CanonElement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/elements/resolve": { "get": { "operationId": "canonElements.resolve", "tags": ["Canon"], "x-xos-table": "xpms.elements", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Resolve an element", "description": "Resolves free text, an MPN or a GTIN to a catalog element through `xpms.resolve_element`. No match returns a 422 refusal with `NO_ANSWER`; the resolver never guesses. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "stage deck" }, "required": true, "name": "query", "in": "query", "description": "Free text, MPN or GTIN." } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "element_id": "4000.01.01-XPMS-001", "urid": "4000.01.01", "item": "Ground Stage Deck", "match": "gtin" }, "schema": { "$ref": "#/components/schemas/ElementResolution" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-price-bands": { "get": { "operationId": "canonElementPriceBands.list", "tags": ["Canon"], "x-xos-table": "xpms.element_price_bands", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["element_id"], "numeric": true }, "summary": "List canon element price band rows", "description": "A price band for an element at one grade. Effective confidence is computed at read time from the staleness policy. Returns a cursor page of canon element price band rows the caller may see. Coded list: the default order is numeric code order by `element_id`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon element price band rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "element_id": "4000.01.01-XPMS-001", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "grade_code": "standard", "amount_minor": 125000, "currency_code": "USD", "assertion_word": "Quoted" }, { "element_id": "4000.01.01-XPMS-002", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "grade_code": "standard", "amount_minor": 125000, "currency_code": "USD", "assertion_word": "Quoted" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonElementPriceBandPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-gtins": { "get": { "operationId": "canonElementGtins.list", "tags": ["Canon"], "x-xos-table": "xpms.element_gtins", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["gtin"], "numeric": false }, "summary": "List canon element gtin rows", "description": "A GTIN mapped to an element. One GTIN maps to at most one element. Returns a cursor page of canon element gtin rows the caller may see. The default order is `gtin` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon element gtin rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "gtin": "00012345678905", "element_id": "4000.01.01-XPMS-001", "confirmed_by": "Canon Ratifier" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonElementGtinPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-gtins/{gtin}": { "get": { "operationId": "canonElementGtins.get", "tags": ["Canon"], "x-xos-table": "xpms.element_gtins", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon element gtin", "description": "A GTIN mapped to an element. One GTIN maps to at most one element. Returns one canon element gtin with its `ETag`. A canon element gtin the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]{8,14}$", "description": "GTIN identifier.", "example": "00012345678905" }, "required": true, "description": "GTIN identifier.", "name": "gtin", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon element gtin.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "gtin": "00012345678905", "element_id": "4000.01.01-XPMS-001", "confirmed_by": "Canon Ratifier" }, "schema": { "$ref": "#/components/schemas/CanonElementGtin" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-gtins/resolve": { "get": { "operationId": "canonElementGtins.resolve", "tags": ["Canon"], "x-xos-table": "xpms.element_gtins", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Resolve a GTIN", "description": "Resolves a GTIN to its element through `xpms.resolve_gtin`. Many GTINs map to one element; one GTIN maps to at most one. An unknown GTIN returns a 422 `NO_ANSWER` refusal. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]{8,14}$", "example": "00012345678905" }, "required": true, "name": "gtin", "in": "query", "description": "GTIN to resolve." } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "element_id": "4000.01.01-XPMS-001", "urid": "4000.01.01", "item": "Ground Stage Deck", "match": "gtin" }, "schema": { "$ref": "#/components/schemas/ElementResolution" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-phases": { "get": { "operationId": "canonElementPhases.list", "tags": ["Canon"], "x-xos-table": "xpms.bridge_element_phase", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["element_id"], "numeric": false }, "summary": "List canon element phase rows", "description": "Phase participation of an element (multi-valued). Returns a cursor page of canon element phase rows the caller may see. The default order is `element_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon element phase rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "element_id": "4000.01.01-XPMS-001", "phase_code": "SCP" }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonElementPhasePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-tags": { "get": { "operationId": "canonElementTags.list", "tags": ["Canon"], "x-xos-table": "xpms.bridge_element_tag", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["element_id"], "numeric": false }, "summary": "List canon element tag rows", "description": "A tag carried by an element. Returns a cursor page of canon element tag rows the caller may see. The default order is `element_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon element tag rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "element_id": "4000.01.01-XPMS-001", "tag_id": "TAG-002" }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonElementTagPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-permits": { "get": { "operationId": "canonElementPermits.list", "tags": ["Canon"], "x-xos-table": "xpms.bridge_element_permit", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["element_id"], "numeric": false }, "summary": "List canon element permit rows", "description": "A permit rule an element can trigger. Returns a cursor page of canon element permit rows the caller may see. The default order is `element_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon element permit rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "element_id": "4000.01.01-XPMS-001", "rule": "Tent or membrane" }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonElementPermitPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-metrics": { "get": { "operationId": "canonElementMetrics.list", "tags": ["Canon"], "x-xos-table": "xpms.bridge_element_metric", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["element_id"], "numeric": false }, "summary": "List canon element metric rows", "description": "A metric that applies to an element. Returns a cursor page of canon element metric rows the caller may see. The default order is `element_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon element metric rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "element_id": "4000.01.01-XPMS-001", "item": "Stage or performance area" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonElementMetricPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/touchpoint-disciplines": { "get": { "operationId": "canonTouchpointDisciplines.list", "tags": ["Canon"], "x-xos-table": "xpms.bridge_touchpoint_discipline", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["touchpoint_id"], "numeric": false }, "summary": "List canon touchpoint discipline rows", "description": "A discipline that delivers a touchpoint. Returns a cursor page of canon touchpoint discipline rows the caller may see. The default order is `touchpoint_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon touchpoint discipline rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "touchpoint_id": "SGT-01", "disc_code": "4000.01" }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonTouchpointDisciplinePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/discipline-teams": { "get": { "operationId": "canonDisciplineTeams.list", "tags": ["Canon"], "x-xos-table": "xpms.bridge_discipline_team", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["disc_code"], "numeric": false }, "summary": "List canon discipline team rows", "description": "A canon team that works in a discipline. Returns a cursor page of canon discipline team rows the caller may see. The default order is `disc_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon discipline team rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "disc_code": "4000.01", "team_id": "4000-T01" }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonDisciplineTeamPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/document-library": { "get": { "operationId": "canonStdDocumentLibrary.list", "tags": ["Canon"], "x-xos-table": "xpms.std_document_library", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_id"], "numeric": false }, "summary": "List std document rows", "description": "A document and asset library entry. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std document rows the caller may see. The default order is `record_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std document rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_id": "SOP-001", "document_name": "Venue Load-In Guide", "document_type": "Guide", "reference_id": "DOC-004", "file_format": "PDF", "version": "v2.0", "issue_date": "2026-10-08", "expiration_date": "2026-10-08", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response", "organization": "GHXSTSHIP", "project": "CSMIA26", "file_size": "48.5 MB", "storage_url": "https://files.example/doc-001.pdf" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdDocumentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/document-library/{record_id}": { "get": { "operationId": "canonStdDocumentLibrary.get", "tags": ["Canon"], "x-xos-table": "xpms.std_document_library", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std document", "description": "A document and asset library entry. Standard Library row, copied into each new org as editable org data. Returns one std document with its `ETag`. A std document the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "record_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std document.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_id": "SOP-001", "document_name": "Venue Load-In Guide", "document_type": "Guide", "reference_id": "DOC-004", "file_format": "PDF", "version": "v2.0", "issue_date": "2026-10-08", "expiration_date": "2026-10-08", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response", "organization": "GHXSTSHIP", "project": "CSMIA26", "file_size": "48.5 MB", "storage_url": "https://files.example/doc-001.pdf" }, "schema": { "$ref": "#/components/schemas/StdDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/emergency-codes": { "get": { "operationId": "canonStdEmergencyCodes.list", "tags": ["Canon"], "x-xos-table": "xpms.emergency_code", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["code"], "numeric": true }, "summary": "List std emergency code rows", "description": "An emergency code. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std emergency code rows the caller may see. Coded list: the default order is numeric code order by `code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std emergency code rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "code": "10", "label": "Medical Assist", "emergency": "Dispatch the medical team to the location.", "swatch": "ecode-red", "sort_order": 1 }, { "code": "20", "label": "Medical Assist", "emergency": "Dispatch the medical team to the location.", "swatch": "ecode-red", "sort_order": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdEmergencyCodePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/emergency-codes/{code}": { "get": { "operationId": "canonStdEmergencyCodes.get", "tags": ["Canon"], "x-xos-table": "xpms.emergency_code", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std emergency code", "description": "An emergency code. Standard Library row, copied into each new org as editable org data. Returns one std emergency code with its `ETag`. A std emergency code the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std emergency code.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "code": "SOP-001", "label": "Medical Assist", "emergency": "Dispatch the medical team to the location.", "swatch": "ecode-red", "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/StdEmergencyCode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/enumerations": { "get": { "operationId": "canonStdEnumerations.list", "tags": ["Canon"], "x-xos-table": "xpms.std_enumeration", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_id"], "numeric": false }, "summary": "List std enumeration rows", "description": "A controlled enumeration value. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std enumeration rows the caller may see. The default order is `record_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std enumeration rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_id": "SOP-001", "enum_domain": "Incident Severity", "enum_code": "SEV_L3_MODERATE", "enum_label": "Level 3 - Moderate", "description": "Non-life-threatening medical case.", "sort_order": 3, "color_code": "Amber", "target_entity": "Incident CAD Log", "is_default": false, "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdEnumerationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/enumerations/{record_id}": { "get": { "operationId": "canonStdEnumerations.get", "tags": ["Canon"], "x-xos-table": "xpms.std_enumeration", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std enumeration", "description": "A controlled enumeration value. Standard Library row, copied into each new org as editable org data. Returns one std enumeration with its `ETag`. A std enumeration the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "record_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std enumeration.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_id": "SOP-001", "enum_domain": "Incident Severity", "enum_code": "SEV_L3_MODERATE", "enum_label": "Level 3 - Moderate", "description": "Non-life-threatening medical case.", "sort_order": 3, "color_code": "Amber", "target_entity": "Incident CAD Log", "is_default": false, "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" }, "schema": { "$ref": "#/components/schemas/StdEnumeration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/labor-rate-cards": { "get": { "operationId": "canonStdLaborRateCards.list", "tags": ["Canon"], "x-xos-table": "xpms.rate_card_resolved", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["rate_card_id"], "numeric": false }, "summary": "List std labor rate card rows", "description": "A labor rate card line. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std labor rate card rows the caller may see. The default order is `rate_card_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std labor rate card rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "rate_card_id": "LRC-001", "role_code": "5000.50.01", "job_title": "Head Rigger", "class_code": "4000", "department": "Production", "worker_classification": "Employee", "pay_basis": "Hourly", "arrangement": "Per Engagement", "standard_rate_minor": 4500, "min_grade_rate_minor": 3800, "max_grade_rate_minor": 5200, "per_diem_rate_minor": 6500, "currency_code": "USD", "overtime_rule_id": "OTR-001", "ot_multiplier": 1.5, "dt_multiplier": 2, "gl_account": "5400", "gl_account_name": "Production Labor" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdLaborRateCardPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/labor-rate-cards/{rate_card_id}": { "get": { "operationId": "canonStdLaborRateCards.get", "tags": ["Canon"], "x-xos-table": "xpms.rate_card_resolved", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std labor rate card", "description": "A labor rate card line. Standard Library row, copied into each new org as editable org data. Returns one std labor rate card with its `ETag`. A std labor rate card the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Canon rate card identifier.", "example": "LRC-001" }, "required": true, "description": "Canon rate card identifier.", "name": "rate_card_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std labor rate card.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "rate_card_id": "LRC-001", "role_code": "5000.50.01", "job_title": "Head Rigger", "class_code": "4000", "department": "Production", "worker_classification": "Employee", "pay_basis": "Hourly", "arrangement": "Per Engagement", "standard_rate_minor": 4500, "min_grade_rate_minor": 3800, "max_grade_rate_minor": 5200, "per_diem_rate_minor": 6500, "currency_code": "USD", "overtime_rule_id": "OTR-001", "ot_multiplier": 1.5, "dt_multiplier": 2, "gl_account": "5400", "gl_account_name": "Production Labor" }, "schema": { "$ref": "#/components/schemas/StdLaborRateCard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/radio-channels": { "get": { "operationId": "canonStdRadioChannels.list", "tags": ["Canon"], "x-xos-table": "xpms.std_radio_channel", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["channel"], "numeric": true }, "summary": "List std radio channel rows", "description": "A radio channel plan entry. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std radio channel rows the caller may see. Coded list: the default order is numeric code order by `channel`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std radio channel rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_id": "SOP-001", "channel": 1, "zone": 1, "assignment": "Emergency", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" }, { "record_id": "SOP-001", "channel": 2, "zone": 1, "assignment": "Emergency", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdRadioChannelPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/radio-channels/{record_id}": { "get": { "operationId": "canonStdRadioChannels.get", "tags": ["Canon"], "x-xos-table": "xpms.std_radio_channel", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std radio channel", "description": "A radio channel plan entry. Standard Library row, copied into each new org as editable org data. Returns one std radio channel with its `ETag`. A std radio channel the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "record_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std radio channel.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_id": "SOP-001", "channel": 1, "zone": 1, "assignment": "Emergency", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" }, "schema": { "$ref": "#/components/schemas/StdRadioChannel" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/roles": { "get": { "operationId": "canonStdRoles.list", "tags": ["Canon"], "x-xos-table": "xpms.role", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["role_code"], "numeric": false }, "summary": "List std role rows", "description": "A Roles Library entry. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std role rows the caller may see. The default order is `role_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std role rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "role_code": "5000.50.01", "class_code": "4000", "job_title": "Head Rigger", "discipline": "Rigging", "rank": "Lead", "job_summary": "Leads the rigging crew.", "key_responsibilities": "Plans and signs off every point.", "qualifications": "ETCP Certified Rigger.", "physical_requirements": "Works at height.", "required_certifications": "ETCP", "default_clearance_tier": "Tier 2", "default_radio_channel": "RCH-004", "notes": "Union call." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdRolePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/roles/{role_code}": { "get": { "operationId": "canonStdRoles.get", "tags": ["Canon"], "x-xos-table": "xpms.role", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std role", "description": "A Roles Library entry. Standard Library row, copied into each new org as editable org data. Returns one std role with its `ETag`. A std role the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/RoleCode" }, "required": true, "description": "Workforce role code from `xpms.dim_role`, on URID grammar.", "name": "role_code", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "role_code": "5000.50.01", "class_code": "4000", "job_title": "Head Rigger", "discipline": "Rigging", "rank": "Lead", "job_summary": "Leads the rigging crew.", "key_responsibilities": "Plans and signs off every point.", "qualifications": "ETCP Certified Rigger.", "physical_requirements": "Works at height.", "required_certifications": "ETCP", "default_clearance_tier": "Tier 2", "default_radio_channel": "RCH-004", "notes": "Union call." }, "schema": { "$ref": "#/components/schemas/StdRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/sops": { "get": { "operationId": "canonStdSops.list", "tags": ["Canon"], "x-xos-table": "xpms.std_sop", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["sop_id"], "numeric": false }, "summary": "List std sop rows", "description": "A standard operating procedure. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std sop rows the caller may see. The default order is `sop_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std sop rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "sop_id": "SOP-001", "title": "Working at Height", "operational_domain": "Structural & Rigging Safety", "revision": "v2.0", "accountable_role_code": "5000.51.02", "required_ppe_compliance_tag": "TAG-002 OSHA", "prerequisites_and_hazards": "Verify the drop zone.", "procedure_step_1": "Inspect every hoist.", "procedure_step_2": "Lift to trim.", "procedure_step_3": "Load test.", "procedure_step_4": "Sign off.", "reference_doc_id": "DOC-004", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response", "organization": "GHXSTSHIP", "project": "CSMIA26" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdSopPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/sops/{sop_id}": { "get": { "operationId": "canonStdSops.get", "tags": ["Canon"], "x-xos-table": "xpms.std_sop", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std sop", "description": "A standard operating procedure. Standard Library row, copied into each new org as editable org data. Returns one std sop with its `ETag`. A std sop the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "sop_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std sop.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "sop_id": "SOP-001", "title": "Working at Height", "operational_domain": "Structural & Rigging Safety", "revision": "v2.0", "accountable_role_code": "5000.51.02", "required_ppe_compliance_tag": "TAG-002 OSHA", "prerequisites_and_hazards": "Verify the drop zone.", "procedure_step_1": "Inspect every hoist.", "procedure_step_2": "Lift to trim.", "procedure_step_3": "Load test.", "procedure_step_4": "Sign off.", "reference_doc_id": "DOC-004", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response", "organization": "GHXSTSHIP", "project": "CSMIA26" }, "schema": { "$ref": "#/components/schemas/StdSop" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/vendor-classes": { "get": { "operationId": "canonStdVendorClasses.list", "tags": ["Canon"], "x-xos-table": "xpms.std_vendor_class", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_id"], "numeric": false }, "summary": "List std vendor class rows", "description": "A vendor class. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std vendor class rows the caller may see. The default order is `record_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std vendor class rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_id": "SOP-001", "class": "Staging Vendor", "description": "Stages, decks and risers.", "clearance_tier": "Tier 2", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdVendorClassPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/vendor-classes/{record_id}": { "get": { "operationId": "canonStdVendorClasses.get", "tags": ["Canon"], "x-xos-table": "xpms.std_vendor_class", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std vendor class", "description": "A vendor class. Standard Library row, copied into each new org as editable org data. Returns one std vendor class with its `ETag`. A std vendor class the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "record_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std vendor class.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_id": "SOP-001", "class": "Staging Vendor", "description": "Stages, decks and risers.", "clearance_tier": "Tier 2", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" }, "schema": { "$ref": "#/components/schemas/StdVendorClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/vendor-entitlements": { "get": { "operationId": "canonStdVendorEntitlements.list", "tags": ["Canon"], "x-xos-table": "xpms.std_vendor_entitlement", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_id"], "numeric": false }, "summary": "List std vendor entitlement rows", "description": "A vendor or sponsor entitlement. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std vendor entitlement rows the caller may see. The default order is `record_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std vendor entitlement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_id": "SOP-001", "vendor_class": "VCL-001", "module": "Advance", "permitted": true, "status": "Active", "notes": "Primary life safety and incident response" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdVendorEntitlementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/vendor-entitlements/{record_id}": { "get": { "operationId": "canonStdVendorEntitlements.get", "tags": ["Canon"], "x-xos-table": "xpms.std_vendor_entitlement", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std vendor entitlement", "description": "A vendor or sponsor entitlement. Standard Library row, copied into each new org as editable org data. Returns one std vendor entitlement with its `ETag`. A std vendor entitlement the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "record_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std vendor entitlement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_id": "SOP-001", "vendor_class": "VCL-001", "module": "Advance", "permitted": true, "status": "Active", "notes": "Primary life safety and incident response" }, "schema": { "$ref": "#/components/schemas/StdVendorEntitlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/verbiage": { "get": { "operationId": "canonStdVerbiage.list", "tags": ["Canon"], "x-xos-table": "xpms.std_verbiage", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_id"], "numeric": false }, "summary": "List std verbiage rows", "description": "A controlled vocabulary term. Standard Library row, copied into each new org as editable org data. Returns a cursor page of std verbiage rows the caller may see. The default order is `record_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of std verbiage rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_id": "SOP-001", "verbiage": "Load-In", "title": "Load-In Announcement", "body": "All crew to the loading dock.", "description": "Read at the start of load-in.", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/StdVerbiagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/verbiage/{record_id}": { "get": { "operationId": "canonStdVerbiage.get", "tags": ["Canon"], "x-xos-table": "xpms.std_verbiage", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a std verbiage", "description": "A controlled vocabulary term. Standard Library row, copied into each new org as editable org data. Returns one std verbiage with its `ETag`. A std verbiage the caller may not see returns 404.", "parameters": [ { "schema": { "$ref": "#/components/schemas/StdCode" }, "required": true, "description": "Natural code of a Standard Library row (Section 2.1).", "name": "record_id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The std verbiage.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_id": "SOP-001", "verbiage": "Load-In", "title": "Load-In Announcement", "body": "All crew to the loading dock.", "description": "Read at the start of load-in.", "department": "5000 Production", "category": "5000.05.02", "sub_category": "Overhead Rigging", "status": "Active", "notes": "Primary life safety and incident response" }, "schema": { "$ref": "#/components/schemas/StdVerbiage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/supersessions": { "get": { "operationId": "canonSupersessions.list", "tags": ["Canon"], "x-xos-table": "xpms.supersession", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["domain", "code"], "numeric": false }, "summary": "List canon supersession rows", "description": "A supersession edge. The graph stays acyclic. Returns a cursor page of canon supersession rows the caller may see. The default order is `domain`, then `code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon supersession rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "code": "DIS", "successor_code": "SCP", "domain": "phase", "label": "Discovery", "reason": "Renamed in 4.0." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonSupersessionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/ratifications": { "get": { "operationId": "canonRatifications.list", "tags": ["Canon"], "x-xos-table": "xpms.ratification", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["subject"], "numeric": false }, "summary": "List canon ratification rows", "description": "A ratification record. 4.0 grammar is proposed until a named ratifier is recorded. Returns a cursor page of canon ratification rows the caller may see. The default order is `subject` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon ratification rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "subject": "4.0 phase grammar", "ratifier": "Canon Ratifier", "ratified_at": "2026-10-08T14:30:00Z", "note": "Ratified at the canon review." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonRatificationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/ratifications/{subject}": { "get": { "operationId": "canonRatifications.get", "tags": ["Canon"], "x-xos-table": "xpms.ratification", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon ratification", "description": "A ratification record. 4.0 grammar is proposed until a named ratifier is recorded. Returns one canon ratification with its `ETag`. A canon ratification the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 300, "description": "What was ratified.", "example": "4.0 phase grammar" }, "required": true, "description": "What was ratified.", "name": "subject", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon ratification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "subject": "4.0 phase grammar", "ratifier": "Canon Ratifier", "ratified_at": "2026-10-08T14:30:00Z", "note": "Ratified at the canon review." }, "schema": { "$ref": "#/components/schemas/CanonRatification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/versions": { "get": { "operationId": "canonVersions.list", "tags": ["Canon"], "x-xos-table": "xpms.version", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["generation"], "numeric": false }, "summary": "List canon version rows", "description": "The current canon version and generation. Canon responses are cached by generation. Returns a cursor page of canon version rows the caller may see. The default order is `generation` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of canon version rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "version_code": "4.0", "generation": 1, "bible_generated_at": "2026-10-01 09:00:00" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonVersionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/versions/{generation}": { "get": { "operationId": "canonVersions.get", "tags": ["Canon"], "x-xos-table": "xpms.version", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get a canon version", "description": "The current canon version and generation. Canon responses are cached by generation. Returns one canon version with its `ETag`. A canon version the caller may not see returns 404.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "Canon generation, incremented by every canon data migration.", "example": 1 }, "required": true, "description": "Canon generation, incremented by every canon data migration.", "name": "generation", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The canon version.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "version_code": "4.0", "generation": 1, "bible_generated_at": "2026-10-01 09:00:00" }, "schema": { "$ref": "#/components/schemas/CanonVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/coordinate-matrix": { "get": { "operationId": "canonCoordinateMatrix.list", "tags": ["Canon"], "x-xos-table": "xpms.v_coordinate_matrix", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["dept_code", "phase_code"], "numeric": true }, "summary": "List coordinate matrix cell rows", "description": "One of 90 coordinates: a department by a phase, counting participation. Returns a cursor page of coordinate matrix cell rows the caller may see. Coded list: the default order is numeric code order by `dept_code`, then `phase_code`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of coordinate matrix cell rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dept_code": "0000", "phase_code": "SCP", "element_count": 42 }, { "dept_code": "1000", "phase_code": "SCP", "element_count": 42 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CoordinateMatrixCellPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/phase-coverage": { "get": { "operationId": "canonPhaseCoverage.list", "tags": ["Canon"], "x-xos-table": "xpms.v_phase_coverage", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["phase_code"], "numeric": false }, "summary": "List phase coverage rows", "description": "Coverage of a phase: Active elements or a declared gap. Returns a cursor page of phase coverage rows the caller may see. The default order is `phase_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of phase coverage rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "phase_code": "SCP", "active_element_count": 120, "declared_gap": false, "gate": 3, "phase": "Advance", "element_count": 42, "category_count": 7, "has_active_element": true, "declared_gap_reason": null } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PhaseCoveragePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/element-economics": { "get": { "operationId": "canonElementEconomics.list", "tags": ["Canon"], "x-xos-table": "xpms.v_element_economics", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["element_id"], "numeric": false }, "summary": "List element economics rows", "description": "Element economics with effective confidence at read time. Returns a cursor page of element economics rows the caller may see. The default order is `element_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of element economics rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "element_id": "4000.01.01-XPMS-001", "currency_code": "USD", "effective_confidence": "QUOTED", "item": "Line Array", "urid": "4000.01.01", "unit_basis": "day", "grade_code": "standard", "amount_minor": 125000, "assertion_word": "Quoted", "valid_from": "2026-10-08", "valid_to": "2026-10-08", "is_unpriced": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ElementEconomicsPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/crosswalk-coverage": { "get": { "operationId": "canonCrosswalkCoverage.list", "tags": ["Canon"], "x-xos-table": "xpms.v_crosswalk_coverage", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["cat_urid"], "numeric": true }, "summary": "List crosswalk coverage rows", "description": "Crosswalk coverage from GTIN to GPC brick to UNSPSC to URID. Returns a cursor page of crosswalk coverage rows the caller may see. Coded list: the default order is numeric code order by `cat_urid`. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of crosswalk coverage rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "cat_urid": "4000.01.01", "element_count": 12, "category": "Production Leadership", "unspsc_element_count": 12, "gtin_element_count": 4, "gtin_count": 9 }, { "cat_urid": "4000.01.02", "element_count": 12, "category": "Production Leadership", "unspsc_element_count": 12, "gtin_element_count": 4, "gtin_count": 9 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CrosswalkCoveragePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/urns/resolve": { "get": { "operationId": "canonUrns.resolve", "tags": ["Canon"], "x-xos-table": "xpms.urn_resolve", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Resolve a URN", "description": "Resolves a `urn:xpms` URN to its canon row through `xpms.urn_resolve`. An unknown URN returns a 422 `NO_ANSWER` refusal. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "pattern": "^urn:xpms:[a-z_]+:.+$", "description": "URN in the `urn:xpms` namespace.", "example": "urn:xpms:category:4000.01.01" }, "required": true, "description": "URN to resolve.", "name": "urn", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "urn": "urn:xpms:category:4000.01.01", "kind": "category", "key": "4000.01.01", "label": "Production Leadership", "resolved_key": "SCP", "is_superseded": false }, "schema": { "$ref": "#/components/schemas/UrnResolution" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/extensions/propose": { "post": { "operationId": "canonExtensions.propose", "tags": ["Canon"], "x-xos-table": "xpms.intake", "x-xos-capability": "canon.extension.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Propose a tenant canon extension", "description": "Proposes a tenant extension discipline or category in the `.50` to `.99` range, scoped to the caller's org. Codes outside the range are refused. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "proposed_kind": "category", "proposed_code": "4000.01.50", "proposed_label": "Modular Stage Systems", "rationale": "Several orgs track modular stage systems." }, "schema": { "$ref": "#/components/schemas/CanonIntakeCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "proposed_kind": "category", "proposed_code": "4000.01.50", "proposed_label": "Modular Stage Systems", "rationale": "Several orgs track modular stage systems.", "intake_state": "Proposed" }, "schema": { "$ref": "#/components/schemas/CanonIntake" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/me": { "get": { "operationId": "me.get", "tags": ["Identity"], "x-xos-table": "app.v_me", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get the caller", "description": "Returns the calling person, their memberships and engagements, and the organization the credential is bound to. A rule that refuses the request returns 422 with `refusal` and `reason`.", "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "active_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_count": 2, "engagement_count": 5 }, "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/people": { "get": { "operationId": "people.list", "tags": ["Identity"], "x-xos-table": "app.people", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List person rows", "description": "One human, linked to one sign-in. Personal facts are owned by the person. Returns a cursor page of person rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of person rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "full_name": "Alex Rivera", "given_name": "Ivy", "family_name": "Marchetti" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PersonPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/people/{id}": { "get": { "operationId": "people.get", "tags": ["Identity"], "x-xos-table": "app.people", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get a person", "description": "One human, linked to one sign-in. Personal facts are owned by the person. Returns one person with its `ETag`. A person the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the person.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The person.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "full_name": "Alex Rivera", "given_name": "Ivy", "family_name": "Marchetti" }, "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "people.update", "tags": ["Identity"], "x-xos-table": "app.people", "x-xos-capability": "people.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Update a person", "description": "One human, linked to one sign-in. Personal facts are owned by the person. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the person.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the person.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "full_name": "Alex Rivera", "given_name": "Ivy", "family_name": "Marchetti" }, "schema": { "$ref": "#/components/schemas/PersonUpdate" } } } }, "responses": { "200": { "description": "The updated person.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "full_name": "Alex Rivera", "given_name": "Ivy", "family_name": "Marchetti" }, "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organizations": { "get": { "operationId": "organizations.list", "tags": ["Identity"], "x-xos-table": "app.organizations", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List organization rows", "description": "Every company on the platform: a tenant (with a subscription), an external account, or both. A partner org cannot have a parent partner. Returns a cursor page of organization rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of organization rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "name": "Northwind Live", "slug": "northwind-live", "parent_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_type": "For-Profit" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrganizationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "organizations.create", "tags": ["Identity"], "x-xos-table": "app.organizations", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.create_organization", "summary": "Create an organization", "description": "Creates an organization with the caller as its Owner, in one transaction, through `app.create_organization`. It starts a 14-day Pro trial with no card and moves to the Access plan when the trial ends unless a card is added (Section 14.7). A reserved or taken slug is refused with 422. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Northwind Live", "slug": "northwind-live" }, "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "name": "Northwind Live", "slug": "northwind-live", "parent_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_type": "For-Profit" }, "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organizations/{id}": { "get": { "operationId": "organizations.get", "tags": ["Identity"], "x-xos-table": "app.organizations", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an organization", "description": "Every company on the platform: a tenant (with a subscription), an external account, or both. A partner org cannot have a parent partner. Returns one organization with its `ETag`. A organization the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the organization.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The organization.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "name": "Northwind Live", "slug": "northwind-live", "parent_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_type": "For-Profit" }, "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "organizations.update", "tags": ["Identity"], "x-xos-table": "app.organizations", "x-xos-capability": "org.general.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an organization", "description": "Every company on the platform: a tenant (with a subscription), an external account, or both. A partner org cannot have a parent partner. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the organization.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the organization.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Northwind Live", "slug": "northwind-live", "parent_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_type": "For-Profit" }, "schema": { "$ref": "#/components/schemas/OrganizationUpdate" } } } }, "responses": { "200": { "description": "The updated organization.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "name": "Northwind Live", "slug": "northwind-live", "parent_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_type": "For-Profit" }, "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organizations/clients": { "post": { "operationId": "organizations.createClient", "tags": ["Identity"], "x-xos-table": "app.organizations", "x-xos-capability": "org.partner.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "app.create_client_organization", "summary": "Create a client organization", "description": "Partner console (Section 4.6.1): creates a client organization under the caller's partner organization, on the given plan, with an Owner invite for the client, through `app.create_client_organization`. Requires `org.partner.manage` in the partner organization; partner staff gain no access to the client organization. The invite token is returned once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harbor City Events", "slug": "northwind-live", "owner_email": "alex.rivera@northwindlive.example", "plan_code": "access" }, "schema": { "$ref": "#/components/schemas/CreateClientOrganizationRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invite_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invite_token": "xinv_3f9a1c0d7e2b4a6f8c1d0e9b7a5c3f1e" }, "schema": { "$ref": "#/components/schemas/CreateClientOrganizationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organizations/leave-partner": { "post": { "operationId": "organizations.leavePartner", "tags": ["Identity"], "x-xos-table": "app.organizations", "x-xos-capability": "org.billing.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "leave_partner", "summary": "Leave the partner", "description": "The client Owner (org.billing.manage) types the bound org's name; the org leaves its partner and becomes a direct customer (app.leave_partner). Its rendered brand becomes its own, the partner's support sessions and standing grants end, and billing moves to the org as a 14-day trial of the same plan that stays once a card is added. Data and members are untouched. An org without a partner answers 422. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "confirm_name": "Tidewater Events" }, "schema": { "$ref": "#/components/schemas/LeavePartnerRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "name": "Northwind Live", "slug": "northwind-live", "parent_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_type": "For-Profit" }, "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/memberships": { "get": { "operationId": "memberships.list", "tags": ["Identity"], "x-xos-table": "app.memberships", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List membership rows", "description": "A person in an organization as an internal member, with time-boxed validity. Returns a cursor page of membership rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of membership rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MembershipPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/memberships/{id}": { "get": { "operationId": "memberships.get", "tags": ["Identity"], "x-xos-table": "app.memberships", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a membership", "description": "A person in an organization as an internal member, with time-boxed validity. Returns one membership with its `ETag`. A membership the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the membership.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The membership.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Membership" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/memberships/leave": { "post": { "operationId": "memberships.leave", "tags": ["Identity"], "x-xos-table": "app.memberships", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.leave_organization", "summary": "Leave the organization", "description": "Ends the caller's membership in the organization the credential is bound to, now, through `app.leave_organization`; access ends at once (Section 7.5 invariant 3). The sole Owner is refused with 422. Returns the ended membership. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Membership" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/memberships/{id}/end": { "post": { "operationId": "memberships.end", "tags": ["Identity"], "x-xos-table": "app.memberships", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "app.end_membership", "summary": "End a membership", "description": "Ends another member's membership now through `app.end_membership`. Requires `org.members.manage` at or above the member's band; the sole Owner is refused with 422. Returns the ended membership. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the membership.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Membership" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/memberships/{id}/offboard": { "post": { "operationId": "memberships.offboard", "tags": ["Identity"], "x-xos-table": "app.memberships", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Offboard a member", "description": "Ends access at once and opens the offboarding checklist. A sole Owner cannot remove or demote themselves. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the membership.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Membership" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/membership-roles": { "get": { "operationId": "membershipRoles.list", "tags": ["Identity"], "x-xos-table": "app.membership_roles", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List membership role rows", "description": "A role held through a membership. A person may hold several; capabilities are the union. A person cannot grant themselves a role. Returns a cursor page of membership role rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of membership role rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MembershipRolePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "membershipRoles.create", "tags": ["Identity"], "x-xos-table": "app.membership_roles", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a membership role", "description": "A role held through a membership. A person may hold several; capabilities are the union. A person cannot grant themselves a role. Creates a membership role. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/MembershipRoleCreate" } } } }, "responses": { "201": { "description": "The created membership role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/MembershipRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/membership-roles/{id}": { "get": { "operationId": "membershipRoles.get", "tags": ["Identity"], "x-xos-table": "app.membership_roles", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a membership role", "description": "A role held through a membership. A person may hold several; capabilities are the union. A person cannot grant themselves a role. Returns one membership role with its `ETag`. A membership role the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the membership role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the membership role.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The membership role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/MembershipRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "membershipRoles.delete", "tags": ["Identity"], "x-xos-table": "app.membership_roles", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a membership role", "description": "A role held through a membership. A person may hold several; capabilities are the union. A person cannot grant themselves a role. Soft-deletes the membership role: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the membership role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the membership role.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The membership role moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-assignments": { "get": { "operationId": "projectAssignments.list", "tags": ["Identity"], "x-xos-table": "app.project_members", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project assignment rows", "description": "A person on a project, with scope nodes and dates. Returns a cursor page of project assignment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project assignment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectAssignmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "projectAssignments.create", "tags": ["Identity"], "x-xos-table": "app.project_members", "x-xos-capability": "projects.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a project assignment", "description": "A person on a project, with scope nodes and dates. Creates a project assignment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignmentCreate" } } } }, "responses": { "201": { "description": "The created project assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-assignments/{id}": { "get": { "operationId": "projectAssignments.get", "tags": ["Identity"], "x-xos-table": "app.project_members", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project assignment", "description": "A person on a project, with scope nodes and dates. Returns one project assignment with its `ETag`. A project assignment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "projectAssignments.update", "tags": ["Identity"], "x-xos-table": "app.project_members", "x-xos-capability": "projects.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a project assignment", "description": "A person on a project, with scope nodes and dates. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignmentUpdate" } } } }, "responses": { "200": { "description": "The updated project assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "projectAssignments.delete", "tags": ["Identity"], "x-xos-table": "app.project_members", "x-xos-capability": "projects.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a project assignment", "description": "A person on a project, with scope nodes and dates. Soft-deletes the project assignment: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project assignment.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The project assignment moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-assignment-roles": { "get": { "operationId": "projectAssignmentRoles.list", "tags": ["Identity"], "x-xos-table": "app.project_member_roles", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project assignment role rows", "description": "A project role held through a project assignment. Returns a cursor page of project assignment role rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project assignment role rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_member_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectAssignmentRolePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "projectAssignmentRoles.create", "tags": ["Identity"], "x-xos-table": "app.project_member_roles", "x-xos-capability": "projects.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a project assignment role", "description": "A project role held through a project assignment. Creates a project assignment role. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_member_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignmentRoleCreate" } } } }, "responses": { "201": { "description": "The created project assignment role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_member_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignmentRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-assignment-roles/{id}": { "get": { "operationId": "projectAssignmentRoles.get", "tags": ["Identity"], "x-xos-table": "app.project_member_roles", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project assignment role", "description": "A project role held through a project assignment. Returns one project assignment role with its `ETag`. A project assignment role the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project assignment role.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project assignment role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_member_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_role": "Producer" }, "schema": { "$ref": "#/components/schemas/ProjectAssignmentRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "projectAssignmentRoles.delete", "tags": ["Identity"], "x-xos-table": "app.project_member_roles", "x-xos-capability": "projects.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a project assignment role", "description": "A project role held through a project assignment. Soft-deletes the project assignment role: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project assignment role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project assignment role.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The project assignment role moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/account-memberships": { "get": { "operationId": "accountMemberships.list", "tags": ["Identity"], "x-xos-table": "app.account_memberships", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List account membership rows", "description": "A person in an external organization's account. Returns a cursor page of account membership rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of account membership rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AccountMembershipPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "accountMemberships.create", "tags": ["Identity"], "x-xos-table": "app.account_memberships", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an account membership", "description": "A person in an external organization's account. Creates an account membership. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_role": "Account Finance" }, "schema": { "$ref": "#/components/schemas/AccountMembershipCreate" } } } }, "responses": { "201": { "description": "The created account membership.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccountMembership" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/account-memberships/{id}": { "get": { "operationId": "accountMemberships.get", "tags": ["Identity"], "x-xos-table": "app.account_memberships", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get an account membership", "description": "A person in an external organization's account. Returns one account membership with its `ETag`. A account membership the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the account membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the account membership.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The account membership.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccountMembership" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "accountMemberships.delete", "tags": ["Identity"], "x-xos-table": "app.account_memberships", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete an account membership", "description": "A person in an external organization's account. Soft-deletes the account membership: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the account membership.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the account membership.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The account membership moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/account-membership-roles": { "get": { "operationId": "accountMembershipRoles.list", "tags": ["Identity"], "x-xos-table": "app.account_membership_roles", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List account membership role rows", "description": "An account role held through an account membership. Returns a cursor page of account membership role rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of account membership role rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "account_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_role": "Account Finance", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AccountMembershipRolePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "accountMembershipRoles.create", "tags": ["Identity"], "x-xos-table": "app.account_membership_roles", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an account membership role", "description": "An account role held through an account membership. Creates an account membership role. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "account_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_role": "Account Finance" }, "schema": { "$ref": "#/components/schemas/AccountMembershipRoleCreate" } } } }, "responses": { "201": { "description": "The created account membership role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "account_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_role": "Account Finance", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AccountMembershipRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/account-membership-roles/{id}": { "get": { "operationId": "accountMembershipRoles.get", "tags": ["Identity"], "x-xos-table": "app.account_membership_roles", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get an account membership role", "description": "An account role held through an account membership. Returns one account membership role with its `ETag`. A account membership role the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the account membership role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the account membership role.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The account membership role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "account_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_role": "Account Finance", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AccountMembershipRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "accountMembershipRoles.delete", "tags": ["Identity"], "x-xos-table": "app.account_membership_roles", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete an account membership role", "description": "An account role held through an account membership. Soft-deletes the account membership role: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the account membership role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the account membership role.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The account membership role moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organization-relationships": { "get": { "operationId": "organizationRelationships.list", "tags": ["Identity"], "x-xos-table": "app.counterparties", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List organization relationship rows", "description": "One organization's relationship to another, with the org-owned facts. Never visible to another org. Returns a cursor page of organization relationship rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of organization relationship rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrganizationRelationshipPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "organizationRelationships.create", "tags": ["Identity"], "x-xos-table": "app.counterparties", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create an organization relationship", "description": "One organization's relationship to another, with the org-owned facts. Never visible to another org. Creates an organization relationship. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator" }, "schema": { "$ref": "#/components/schemas/OrganizationRelationshipCreate" } } } }, "responses": { "201": { "description": "The created organization relationship.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator" }, "schema": { "$ref": "#/components/schemas/OrganizationRelationship" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organization-relationships/{id}": { "get": { "operationId": "organizationRelationships.get", "tags": ["Identity"], "x-xos-table": "app.counterparties", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get an organization relationship", "description": "One organization's relationship to another, with the org-owned facts. Never visible to another org. Returns one organization relationship with its `ETag`. A organization relationship the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the organization relationship.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the organization relationship.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The organization relationship.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator" }, "schema": { "$ref": "#/components/schemas/OrganizationRelationship" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "organizationRelationships.update", "tags": ["Identity"], "x-xos-table": "app.counterparties", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update an organization relationship", "description": "One organization's relationship to another, with the org-owned facts. Never visible to another org. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the organization relationship.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the organization relationship.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "counterparty_type": "AV Integrator" }, "schema": { "$ref": "#/components/schemas/OrganizationRelationshipUpdate" } } } }, "responses": { "200": { "description": "The updated organization relationship.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_type": "AV Integrator" }, "schema": { "$ref": "#/components/schemas/OrganizationRelationship" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "organizationRelationships.delete", "tags": ["Identity"], "x-xos-table": "app.counterparties", "x-xos-capability": "vendors.vendor.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete an organization relationship", "description": "One organization's relationship to another, with the org-owned facts. Never visible to another org. Soft-deletes the organization relationship: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the organization relationship.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the organization relationship.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The organization relationship moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/representations": { "get": { "operationId": "representations.list", "tags": ["Identity"], "x-xos-table": "app.representations", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List representation rows", "description": "One party acting for another, with scopes and expiry. The artist accepts it. Returns a cursor page of representation rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of representation rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "representative_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "artist_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["Offers", "Advance"], "expires_on": "2026-10-08", "accepted_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RepresentationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "representations.create", "tags": ["Identity"], "x-xos-table": "app.representations", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a representation", "description": "One party acting for another, with scopes and expiry. The artist accepts it. Creates a representation. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "representative_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "artist_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["Offers", "Advance"], "expires_on": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/RepresentationCreate" } } } }, "responses": { "201": { "description": "The created representation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "representative_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "artist_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["Offers", "Advance"], "expires_on": "2026-10-08", "accepted_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Representation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/representations/{id}": { "get": { "operationId": "representations.get", "tags": ["Identity"], "x-xos-table": "app.representations", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a representation", "description": "One party acting for another, with scopes and expiry. The artist accepts it. Returns one representation with its `ETag`. A representation the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the representation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the representation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The representation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "representative_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "artist_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["Offers", "Advance"], "expires_on": "2026-10-08", "accepted_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Representation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "representations.delete", "tags": ["Identity"], "x-xos-table": "app.representations", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a representation", "description": "One party acting for another, with scopes and expiry. The artist accepts it. Soft-deletes the representation: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the representation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the representation.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The representation moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/representations/{id}/accept": { "post": { "operationId": "representations.accept", "tags": ["Identity"], "x-xos-table": "app.representations", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Accept a representation", "description": "Accepts the representation as the represented artist. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the representation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the representation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "representative_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "artist_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["Offers", "Advance"], "expires_on": "2026-10-08", "accepted_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Representation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/join-requests": { "get": { "operationId": "joinRequests.list", "tags": ["Identity"], "x-xos-table": "app.join_requests", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List join request rows", "description": "A request to join an org, approved by an Admin. Returns a cursor page of join request rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of join request rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "I run audio for the summer series.", "join_request_state": "Proposed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/JoinRequestPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "joinRequests.create", "tags": ["Identity"], "x-xos-table": "app.join_requests", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a join request", "description": "A request to join an org, approved by an Admin. Creates a join request. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "I run audio for the summer series." }, "schema": { "$ref": "#/components/schemas/JoinRequestCreate" } } } }, "responses": { "201": { "description": "The created join request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "I run audio for the summer series.", "join_request_state": "Proposed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JoinRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/join-requests/{id}": { "get": { "operationId": "joinRequests.get", "tags": ["Identity"], "x-xos-table": "app.join_requests", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a join request", "description": "A request to join an org, approved by an Admin. Returns one join request with its `ETag`. A join request the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the join request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the join request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The join request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "I run audio for the summer series.", "join_request_state": "Proposed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JoinRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/join-requests/{id}/approve": { "post": { "operationId": "joinRequests.approve", "tags": ["Identity"], "x-xos-table": "app.join_requests", "x-xos-capability": "org.members.invite", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Approve a join request", "description": "Approves the request and creates the membership. Requires an Admin. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the join request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the join request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "I run audio for the summer series.", "join_request_state": "Proposed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JoinRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/join-requests/{id}/decline": { "post": { "operationId": "joinRequests.decline", "tags": ["Identity"], "x-xos-table": "app.join_requests", "x-xos-capability": "org.members.invite", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Decline a join request", "description": "Declines the request. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the join request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the join request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "I run audio for the summer series.", "join_request_state": "Proposed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/JoinRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invitation-links": { "get": { "operationId": "invitationLinks.list", "tags": ["Identity"], "x-xos-table": "app.invite_links", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List invitation link rows", "description": "An invitation link with a role and an expiry. The token is shown once. Returns a cursor page of invitation link rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of invitation link rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role": "Manager", "expires_at": "2026-10-08T14:30:00Z", "max_uses": 10, "revoked_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InvitationLinkPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "invitationLinks.create", "tags": ["Identity"], "x-xos-table": "app.invite_links", "x-xos-capability": "org.members.invite", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an invitation link", "description": "An invitation link with a role and an expiry. The token is shown once. Creates an invitation link. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "role": "Manager", "expires_at": "2026-10-08T14:30:00Z", "max_uses": 10 }, "schema": { "$ref": "#/components/schemas/InvitationLinkCreate" } } } }, "responses": { "201": { "description": "The created invitation link.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role": "Manager", "expires_at": "2026-10-08T14:30:00Z", "max_uses": 10, "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/InvitationLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invitation-links/{id}": { "get": { "operationId": "invitationLinks.get", "tags": ["Identity"], "x-xos-table": "app.invite_links", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an invitation link", "description": "An invitation link with a role and an expiry. The token is shown once. Returns one invitation link with its `ETag`. A invitation link the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invitation link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invitation link.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The invitation link.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role": "Manager", "expires_at": "2026-10-08T14:30:00Z", "max_uses": 10, "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/InvitationLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invitation-links/{id}/revoke": { "post": { "operationId": "invitationLinks.revoke", "tags": ["Identity"], "x-xos-table": "app.invite_links", "x-xos-capability": "org.members.invite", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Revoke an invitation link", "description": "Revokes the link; later uses are refused. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invitation link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invitation link.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role": "Manager", "expires_at": "2026-10-08T14:30:00Z", "max_uses": 10, "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/InvitationLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invites": { "get": { "operationId": "invites.list", "tags": ["Identity"], "x-xos-table": "app.invites", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List invite rows", "description": "An email invitation to join an org. Created through `invites.create` (the `app.invite_member` RPC); the token is never stored or returned again. Returns a cursor page of invite rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of invite rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "email": "alex.rivera@northwindlive.example", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_at": "2026-10-08T14:30:00Z", "invited_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accepted_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "partner_bootstrap": false, "accepted_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InvitePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "invites.create", "tags": ["Identity"], "x-xos-table": "app.invites", "x-xos-capability": "org.members.invite", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "app.invite_member", "summary": "Invite a member", "description": "Invites an email to the caller's organization with a role the inviter may grant and an expiry of 1 hour to 30 days, through `app.invite_member`. Replaces any pending invite for the same email. Refused with 422 for a role above the inviter's band, a capability the inviter does not hold, an out-of-range expiry or a self-invite. The token is returned once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "email": "alex.rivera@northwindlive.example", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_for_hours": 336 }, "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "invite_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "invite_token": "xinv_3f9a1c0d7e2b4a6f8c1d0e9b7a5c3f1e" }, "schema": { "$ref": "#/components/schemas/InviteMemberResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invites/{id}": { "get": { "operationId": "invites.get", "tags": ["Identity"], "x-xos-table": "app.invites", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an invite", "description": "An email invitation to join an org. Created through `invites.create` (the `app.invite_member` RPC); the token is never stored or returned again. Returns one invite with its `ETag`. A invite the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invite.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invite.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The invite.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "email": "alex.rivera@northwindlive.example", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_at": "2026-10-08T14:30:00Z", "invited_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "accepted_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "partner_bootstrap": false, "accepted_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Invite" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "invites.delete", "tags": ["Identity"], "x-xos-table": "app.invites", "x-xos-capability": "org.members.invite", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an invite", "description": "An email invitation to join an org. Created through `invites.create` (the `app.invite_member` RPC); the token is never stored or returned again. Soft-deletes the invite: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the invite.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the invite.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The invite moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invites/preview": { "post": { "operationId": "invites.preview", "tags": ["Identity"], "x-xos-table": "app.invites", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.preview_invite", "summary": "Preview an invite", "description": "Shows the organization, role and expiry an invite offers, only to the confirmed sign-in it was sent to, through `app.preview_invite`. An invalid, expired, locked or mismatched token returns a 422 `REFUSE` with its reason; repeated failures rate-limit the caller. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "token": "xinv_3f9a1c0d7e2b4a6f8c1d0e9b7a5c3f1e" }, "schema": { "$ref": "#/components/schemas/InviteTokenRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "org_name": "Northwind Live", "role_code": "member", "role_name": "Member", "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/InvitePreview" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invites/accept": { "post": { "operationId": "invites.accept", "tags": ["Identity"], "x-xos-table": "app.invites", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.accept_invite", "summary": "Accept an invite", "description": "Accepts an invite for the confirmed sign-in it was sent to, through `app.accept_invite`: joins the organization, or reuses the active membership, and receives the role. Refused with 422 when the token is invalid or the inviter no longer holds `org.members.invite`. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "token": "xinv_3f9a1c0d7e2b4a6f8c1d0e9b7a5c3f1e" }, "schema": { "$ref": "#/components/schemas/InviteTokenRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AcceptInviteResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verified-domains": { "get": { "operationId": "verifiedDomains.list", "tags": ["Identity"], "x-xos-table": "app.org_domains", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List verified domain rows", "description": "A verified email domain with automatic join and a default role. Returns a cursor page of verified domain rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of verified domain rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hostname": "gateway.northwindlive.example", "purpose": "Atlas", "verification_state": "Pending", "verification_token": "xos-verify=6f1c2d", "last_checked_at": "2026-10-08T14:30:00Z", "auto_join_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provisioning_status": "Pending DNS", "dns_records": [ { "type": "CNAME", "name": "atlas.northwindlive.example", "value": "cname.vercel-dns.com", "purpose": "routing" } ], "tls_ready": false, "provisioning_error": "Vercel returned 400" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VerifiedDomainPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "verifiedDomains.create", "tags": ["Identity"], "x-xos-table": "app.org_domains", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a verified domain", "description": "A verified email domain with automatic join and a default role. Creates a verified domain. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "hostname": "gateway.northwindlive.example", "purpose": "Atlas", "auto_join_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/VerifiedDomainCreate" } } } }, "responses": { "201": { "description": "The created verified domain.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hostname": "gateway.northwindlive.example", "purpose": "Atlas", "verification_state": "Pending", "verification_token": "xos-verify=6f1c2d", "last_checked_at": "2026-10-08T14:30:00Z", "auto_join_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provisioning_status": "Pending DNS", "dns_records": [ { "type": "CNAME", "name": "atlas.northwindlive.example", "value": "cname.vercel-dns.com", "purpose": "routing" } ], "tls_ready": false, "provisioning_error": "Vercel returned 400" }, "schema": { "$ref": "#/components/schemas/VerifiedDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verified-domains/{id}": { "get": { "operationId": "verifiedDomains.get", "tags": ["Identity"], "x-xos-table": "app.org_domains", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a verified domain", "description": "A verified email domain with automatic join and a default role. Returns one verified domain with its `ETag`. A verified domain the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verified domain.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verified domain.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The verified domain.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hostname": "gateway.northwindlive.example", "purpose": "Atlas", "verification_state": "Pending", "verification_token": "xos-verify=6f1c2d", "last_checked_at": "2026-10-08T14:30:00Z", "auto_join_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provisioning_status": "Pending DNS", "dns_records": [ { "type": "CNAME", "name": "atlas.northwindlive.example", "value": "cname.vercel-dns.com", "purpose": "routing" } ], "tls_ready": false, "provisioning_error": "Vercel returned 400" }, "schema": { "$ref": "#/components/schemas/VerifiedDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "verifiedDomains.update", "tags": ["Identity"], "x-xos-table": "app.org_domains", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a verified domain", "description": "A verified email domain with automatic join and a default role. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verified domain.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verified domain.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "auto_join_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/VerifiedDomainUpdate" } } } }, "responses": { "200": { "description": "The updated verified domain.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hostname": "gateway.northwindlive.example", "purpose": "Atlas", "verification_state": "Pending", "verification_token": "xos-verify=6f1c2d", "last_checked_at": "2026-10-08T14:30:00Z", "auto_join_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provisioning_status": "Pending DNS", "dns_records": [ { "type": "CNAME", "name": "atlas.northwindlive.example", "value": "cname.vercel-dns.com", "purpose": "routing" } ], "tls_ready": false, "provisioning_error": "Vercel returned 400" }, "schema": { "$ref": "#/components/schemas/VerifiedDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "verifiedDomains.delete", "tags": ["Identity"], "x-xos-table": "app.org_domains", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a verified domain", "description": "A verified email domain with automatic join and a default role. Soft-deletes the verified domain: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verified domain.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verified domain.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The verified domain moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verified-domains/{id}/check": { "post": { "operationId": "verifiedDomains.check", "tags": ["Identity"], "x-xos-table": "app.org_domains", "x-xos-capability": "org.white_label.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "request_domain_check", "summary": "Check a custom domain again", "description": "Queues the provider worker for a custom Atlas, Gateway or sending domain (app.request_domain_check): provisioning again when it never reached the provider, otherwise checking DNS verification and TLS now. Verified domains answer 422 (domain_not_provisioned). Returns the domain. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verified domain.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verified domain.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hostname": "gateway.northwindlive.example", "purpose": "Atlas", "verification_state": "Pending", "verification_token": "xos-verify=6f1c2d", "last_checked_at": "2026-10-08T14:30:00Z", "auto_join_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provisioning_status": "Pending DNS", "dns_records": [ { "type": "CNAME", "name": "atlas.northwindlive.example", "value": "cname.vercel-dns.com", "purpose": "routing" } ], "tls_ready": false, "provisioning_error": "Vercel returned 400" }, "schema": { "$ref": "#/components/schemas/VerifiedDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offboarding-checklists": { "get": { "operationId": "offboardingChecklists.list", "tags": ["Identity"], "x-xos-table": "app.offboardings", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List offboarding checklist rows", "description": "The checklist that reassigns a departing member's open records. Returns a cursor page of offboarding checklist rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of offboarding checklist rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reassign_to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "open_record_count": 4, "completed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OffboardingChecklistPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/offboarding-checklists/{id}": { "get": { "operationId": "offboardingChecklists.get", "tags": ["Identity"], "x-xos-table": "app.offboardings", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an offboarding checklist", "description": "The checklist that reassigns a departing member's open records. Returns one offboarding checklist with its `ETag`. A offboarding checklist the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offboarding checklist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offboarding checklist.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The offboarding checklist.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reassign_to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "open_record_count": 4, "completed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OffboardingChecklist" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "offboardingChecklists.update", "tags": ["Identity"], "x-xos-table": "app.offboardings", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an offboarding checklist", "description": "The checklist that reassigns a departing member's open records. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the offboarding checklist.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the offboarding checklist.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reassign_to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/OffboardingChecklistUpdate" } } } }, "responses": { "200": { "description": "The updated offboarding checklist.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reassign_to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "open_record_count": 4, "completed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OffboardingChecklist" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/person-profiles": { "get": { "operationId": "personProfiles.list", "tags": ["Identity"], "x-xos-table": "app.person_profiles", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List person profile rows", "description": "A person's profile page, owned by the person. New profiles start Private. Returns a cursor page of person profile rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of person profile rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "headline": "Head Rigger, Festivals and Arenas", "bio": "Fifteen years rigging touring shows.", "pronouns": "they/them", "locality": "Miami", "country": "US", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "preferred_name": "Alex" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PersonProfilePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "personProfiles.create", "tags": ["Identity"], "x-xos-table": "app.person_profiles", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a person profile", "description": "A person's profile page, owned by the person. New profiles start Private. Creates a person profile. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "headline": "Head Rigger, Festivals and Arenas", "bio": "Fifteen years rigging touring shows.", "pronouns": "they/them", "locality": "Miami", "country": "US", "visibility": "Private", "search_indexing": false }, "schema": { "$ref": "#/components/schemas/PersonProfileCreate" } } } }, "responses": { "201": { "description": "The created person profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "headline": "Head Rigger, Festivals and Arenas", "bio": "Fifteen years rigging touring shows.", "pronouns": "they/them", "locality": "Miami", "country": "US", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "preferred_name": "Alex" }, "schema": { "$ref": "#/components/schemas/PersonProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/person-profiles/{id}": { "get": { "operationId": "personProfiles.get", "tags": ["Identity"], "x-xos-table": "app.person_profiles", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get a person profile", "description": "A person's profile page, owned by the person. New profiles start Private. Returns one person profile with its `ETag`. A person profile the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the person profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the person profile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The person profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "headline": "Head Rigger, Festivals and Arenas", "bio": "Fifteen years rigging touring shows.", "pronouns": "they/them", "locality": "Miami", "country": "US", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "preferred_name": "Alex" }, "schema": { "$ref": "#/components/schemas/PersonProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "personProfiles.update", "tags": ["Identity"], "x-xos-table": "app.person_profiles", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a person profile", "description": "A person's profile page, owned by the person. New profiles start Private. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the person profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the person profile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "headline": "Head Rigger, Festivals and Arenas", "bio": "Fifteen years rigging touring shows.", "pronouns": "they/them", "locality": "Miami", "country": "US", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "preferred_name": "Alex" }, "schema": { "$ref": "#/components/schemas/PersonProfileUpdate" } } } }, "responses": { "200": { "description": "The updated person profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "headline": "Head Rigger, Festivals and Arenas", "bio": "Fifteen years rigging touring shows.", "pronouns": "they/them", "locality": "Miami", "country": "US", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "preferred_name": "Alex" }, "schema": { "$ref": "#/components/schemas/PersonProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organization-profiles": { "get": { "operationId": "organizationProfiles.list", "tags": ["Identity"], "x-xos-table": "app.organization_profiles", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List organization profile rows", "description": "An organization's profile page. New organizations start Network. Returns a cursor page of organization profile rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of organization profile rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "about": "Live event production for waterfront venues.", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "website_url": "https://northwindlive.example/files/site-plan.pdf", "contact_email": "alex.rivera@northwindlive.example" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrganizationProfilePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "organizationProfiles.create", "tags": ["Identity"], "x-xos-table": "app.organization_profiles", "x-xos-capability": "org.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an organization profile", "description": "An organization's profile page. New organizations start Network. Creates an organization profile. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "about": "Live event production for waterfront venues.", "visibility": "Private", "search_indexing": false }, "schema": { "$ref": "#/components/schemas/OrganizationProfileCreate" } } } }, "responses": { "201": { "description": "The created organization profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "about": "Live event production for waterfront venues.", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "website_url": "https://northwindlive.example/files/site-plan.pdf", "contact_email": "alex.rivera@northwindlive.example" }, "schema": { "$ref": "#/components/schemas/OrganizationProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/organization-profiles/{id}": { "get": { "operationId": "organizationProfiles.get", "tags": ["Identity"], "x-xos-table": "app.organization_profiles", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an organization profile", "description": "An organization's profile page. New organizations start Network. Returns one organization profile with its `ETag`. A organization profile the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the organization profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the organization profile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The organization profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "about": "Live event production for waterfront venues.", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "website_url": "https://northwindlive.example/files/site-plan.pdf", "contact_email": "alex.rivera@northwindlive.example" }, "schema": { "$ref": "#/components/schemas/OrganizationProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "organizationProfiles.update", "tags": ["Identity"], "x-xos-table": "app.organization_profiles", "x-xos-capability": "org.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an organization profile", "description": "An organization's profile page. New organizations start Network. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the organization profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the organization profile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "about": "Live event production for waterfront venues.", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "website_url": "https://northwindlive.example/files/site-plan.pdf", "contact_email": "alex.rivera@northwindlive.example" }, "schema": { "$ref": "#/components/schemas/OrganizationProfileUpdate" } } } }, "responses": { "200": { "description": "The updated organization profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "about": "Live event production for waterfront venues.", "visibility": "Private", "search_indexing": false, "handle": "northwind-live", "handle_changed_at": "2026-10-08T14:30:00Z", "website_url": "https://northwindlive.example/files/site-plan.pdf", "contact_email": "alex.rivera@northwindlive.example" }, "schema": { "$ref": "#/components/schemas/OrganizationProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/profile-visibility": { "get": { "operationId": "profileVisibilityRules.list", "tags": ["Identity"], "x-xos-table": "app.profile_section_visibility", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List profile visibility rule rows", "description": "Visibility of one profile section or field. It can be lower than the profile, never higher. Returns a cursor page of profile visibility rule rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of profile visibility rule rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "section": "photo", "visibility": "Private" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProfileVisibilityRulePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "profileVisibilityRules.create", "tags": ["Identity"], "x-xos-table": "app.profile_section_visibility", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a profile visibility rule", "description": "Visibility of one profile section or field. It can be lower than the profile, never higher. Creates a profile visibility rule. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "section": "photo", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/ProfileVisibilityRuleCreate" } } } }, "responses": { "201": { "description": "The created profile visibility rule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "section": "photo", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/ProfileVisibilityRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/profile-visibility/{id}": { "get": { "operationId": "profileVisibilityRules.get", "tags": ["Identity"], "x-xos-table": "app.profile_section_visibility", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a profile visibility rule", "description": "Visibility of one profile section or field. It can be lower than the profile, never higher. Returns one profile visibility rule with its `ETag`. A profile visibility rule the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the profile visibility rule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the profile visibility rule.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The profile visibility rule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "section": "photo", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/ProfileVisibilityRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "profileVisibilityRules.update", "tags": ["Identity"], "x-xos-table": "app.profile_section_visibility", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a profile visibility rule", "description": "Visibility of one profile section or field. It can be lower than the profile, never higher. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the profile visibility rule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the profile visibility rule.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/ProfileVisibilityRuleUpdate" } } } }, "responses": { "200": { "description": "The updated profile visibility rule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "section": "photo", "visibility": "Private" }, "schema": { "$ref": "#/components/schemas/ProfileVisibilityRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "profileVisibilityRules.delete", "tags": ["Identity"], "x-xos-table": "app.profile_section_visibility", "x-xos-capability": "me.profile.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a profile visibility rule", "description": "Visibility of one profile section or field. It can be lower than the profile, never higher. Soft-deletes the profile visibility rule: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the profile visibility rule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the profile visibility rule.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The profile visibility rule moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verifications": { "get": { "operationId": "verifications.list", "tags": ["Identity"], "x-xos-table": "app.organization_verifications", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List verification rows", "description": "A verification badge, shown only after the platform or a provider checks the claim. Returns a cursor page of verification rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of verification rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "verified_at": "2026-10-08T14:30:00Z", "method": "Stripe Identity", "provider_reference": "vs_1Pq2Rs3Tu4", "expires_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revocation_reason": "The registry record lapsed." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/VerificationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/verifications/{id}": { "get": { "operationId": "verifications.get", "tags": ["Identity"], "x-xos-table": "app.organization_verifications", "x-xos-capability": "people.directory.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "summary": "Get a verification", "description": "A verification badge, shown only after the platform or a provider checks the claim. Returns one verification with its `ETag`. A verification the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the verification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the verification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The verification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "verified_at": "2026-10-08T14:30:00Z", "method": "Stripe Identity", "provider_reference": "vs_1Pq2Rs3Tu4", "expires_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revocation_reason": "The registry record lapsed." }, "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/blocks": { "get": { "operationId": "blocks.list", "tags": ["Identity"], "x-xos-table": "app.blocks", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List block rows", "description": "A person's block of another person or an organization (Section 4.5.6 Profile Privacy). It hides the blocker's profile from the blocked person and from every member of a blocked organization, and the blocked profile from the blocker. Memberships and engagements are not affected. Returns a cursor page of block rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of block rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "blocked_urn": "urn:xpms:person:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BlockPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "blocks.create", "tags": ["Identity"], "x-xos-table": "app.blocks", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a block", "description": "A person's block of another person or an organization (Section 4.5.6 Profile Privacy). It hides the blocker's profile from the blocked person and from every member of a blocked organization, and the blocked profile from the blocker. Memberships and engagements are not affected. Creates a block. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "blocked_urn": "urn:xpms:person:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/BlockCreate" } } } }, "responses": { "201": { "description": "The created block.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "blocked_urn": "urn:xpms:person:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Block" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/blocks/{id}": { "get": { "operationId": "blocks.get", "tags": ["Identity"], "x-xos-table": "app.blocks", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a block", "description": "A person's block of another person or an organization (Section 4.5.6 Profile Privacy). It hides the blocker's profile from the blocked person and from every member of a blocked organization, and the blocked profile from the blocker. Memberships and engagements are not affected. Returns one block with its `ETag`. A block the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the block.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the block.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The block.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "blocked_urn": "urn:xpms:person:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Block" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "blocks.delete", "tags": ["Identity"], "x-xos-table": "app.blocks", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a block", "description": "A person's block of another person or an organization (Section 4.5.6 Profile Privacy). It hides the blocker's profile from the blocked person and from every member of a blocked organization, and the blocked profile from the blocker. Memberships and engagements are not affected. Soft-deletes the block: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the block.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the block.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The block moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/subscriptions": { "get": { "operationId": "subscriptions.list", "tags": ["Settings"], "x-xos-table": "app.subscriptions", "x-xos-capability": "org.billing.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List subscription rows", "description": "Present only when an organization uses Atlas: plan, billing and tenant settings. Returns a cursor page of subscription rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of subscription rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "plan_code": "pro", "subscription_state": "trialing", "trial_ends_at": "2026-10-08T14:30:00Z", "extra_seats": 3, "seats_grandfathered": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SubscriptionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/subscriptions/{id}": { "get": { "operationId": "subscriptions.get", "tags": ["Settings"], "x-xos-table": "app.subscriptions", "x-xos-capability": "org.billing.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a subscription", "description": "Present only when an organization uses Atlas: plan, billing and tenant settings. Returns one subscription with its `ETag`. A subscription the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the subscription.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the subscription.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The subscription.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "plan_code": "pro", "subscription_state": "trialing", "trial_ends_at": "2026-10-08T14:30:00Z", "extra_seats": 3, "seats_grandfathered": false }, "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/plans": { "get": { "operationId": "plans.list", "tags": ["Settings"], "x-xos-table": "app.plans", "x-xos-capability": "org.billing.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["code"], "numeric": false }, "summary": "List plan rows", "description": "A plan generated from `plans.yaml`. Returns a cursor page of plan rows the caller may see. The default order is `code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of plan rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [{ "code": "pro", "sort_order": 1 }], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PlanPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workspaces": { "get": { "operationId": "workspaces.list", "tags": ["Settings"], "x-xos-table": "app.workspaces", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List workspace rows", "description": "A workspace inside an organization. Returns a cursor page of workspace rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of workspace rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Festivals", "slug": "festivals" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkspacePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workspaces.create", "tags": ["Settings"], "x-xos-table": "app.workspaces", "x-xos-capability": "org.workspaces.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a workspace", "description": "A workspace inside an organization. Creates a workspace. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Festivals", "slug": "festivals" }, "schema": { "$ref": "#/components/schemas/WorkspaceCreate" } } } }, "responses": { "201": { "description": "The created workspace.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Festivals", "slug": "festivals" }, "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workspaces/{id}": { "get": { "operationId": "workspaces.get", "tags": ["Settings"], "x-xos-table": "app.workspaces", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a workspace", "description": "A workspace inside an organization. Returns one workspace with its `ETag`. A workspace the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workspace.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The workspace.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Festivals", "slug": "festivals" }, "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "workspaces.update", "tags": ["Settings"], "x-xos-table": "app.workspaces", "x-xos-capability": "org.workspaces.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a workspace", "description": "A workspace inside an organization. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workspace.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Festivals", "slug": "festivals" }, "schema": { "$ref": "#/components/schemas/WorkspaceUpdate" } } } }, "responses": { "200": { "description": "The updated workspace.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Festivals", "slug": "festivals" }, "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "workspaces.delete", "tags": ["Settings"], "x-xos-table": "app.workspaces", "x-xos-capability": "org.workspaces.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a workspace", "description": "A workspace inside an organization. Soft-deletes the workspace: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workspace.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workspace.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The workspace moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workspace-members": { "get": { "operationId": "workspaceMembers.list", "tags": ["Settings"], "x-xos-table": "app.workspace_members", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List workspace member rows", "description": "A member of a workspace. Returns a cursor page of workspace member rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of workspace member rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkspaceMemberPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workspaceMembers.create", "tags": ["Settings"], "x-xos-table": "app.workspace_members", "x-xos-capability": "org.workspaces.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a workspace member", "description": "A member of a workspace. Creates a workspace member. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WorkspaceMemberCreate" } } } }, "responses": { "201": { "description": "The created workspace member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WorkspaceMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workspace-members/{id}": { "get": { "operationId": "workspaceMembers.get", "tags": ["Settings"], "x-xos-table": "app.workspace_members", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a workspace member", "description": "A member of a workspace. Returns one workspace member with its `ETag`. A workspace member the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workspace member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workspace member.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The workspace member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workspace_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WorkspaceMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "workspaceMembers.delete", "tags": ["Settings"], "x-xos-table": "app.workspace_members", "x-xos-capability": "org.workspaces.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a workspace member", "description": "A member of a workspace. Soft-deletes the workspace member: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workspace member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workspace member.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The workspace member moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/teams": { "get": { "operationId": "teams.list", "tags": ["Settings"], "x-xos-table": "app.teams", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List team rows", "description": "A working group, distinct from canon teams. Returns a cursor page of team rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of team rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Control" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TeamPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "teams.create", "tags": ["Settings"], "x-xos-table": "app.teams", "x-xos-capability": "org.teams.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a team", "description": "A working group, distinct from canon teams. Creates a team. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Show Control" }, "schema": { "$ref": "#/components/schemas/TeamCreate" } } } }, "responses": { "201": { "description": "The created team.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Control" }, "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/teams/{id}": { "get": { "operationId": "teams.get", "tags": ["Settings"], "x-xos-table": "app.teams", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a team", "description": "A working group, distinct from canon teams. Returns one team with its `ETag`. A team the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the team.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The team.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Control" }, "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "teams.update", "tags": ["Settings"], "x-xos-table": "app.teams", "x-xos-capability": "org.teams.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a team", "description": "A working group, distinct from canon teams. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the team.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Show Control" }, "schema": { "$ref": "#/components/schemas/TeamUpdate" } } } }, "responses": { "200": { "description": "The updated team.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Control" }, "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "teams.delete", "tags": ["Settings"], "x-xos-table": "app.teams", "x-xos-capability": "org.teams.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a team", "description": "A working group, distinct from canon teams. Soft-deletes the team: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the team.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The team moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/team-members": { "get": { "operationId": "teamMembers.list", "tags": ["Settings"], "x-xos-table": "app.team_members", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List team member rows", "description": "A member of a team. Returns a cursor page of team member rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of team member rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TeamMemberPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "teamMembers.create", "tags": ["Settings"], "x-xos-table": "app.team_members", "x-xos-capability": "org.teams.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a team member", "description": "A member of a team. Creates a team member. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TeamMemberCreate" } } } }, "responses": { "201": { "description": "The created team member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/team-members/{id}": { "get": { "operationId": "teamMembers.get", "tags": ["Settings"], "x-xos-table": "app.team_members", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a team member", "description": "A member of a team. Returns one team member with its `ETag`. A team member the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the team member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the team member.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The team member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "teamMembers.delete", "tags": ["Settings"], "x-xos-table": "app.team_members", "x-xos-capability": "org.teams.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a team member", "description": "A member of a team. Soft-deletes the team member: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the team member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the team member.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The team member moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-branding": { "get": { "operationId": "orgBrandings.list", "tags": ["Settings"], "x-xos-table": "app.org_brands", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List org branding rows", "description": "White label brand settings for Atlas, Gateway, email and Compass. Returns a cursor page of org branding rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of org branding rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "display_name": "Northwind Live", "logo_light_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "logo_dark_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "favicon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "app_icon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "accent_hex": "#1F6FEB", "neutral_tint_hex": "#1F6FEB", "font_family": "Inter", "radius_scale": "Compact", "email_sender_name": "Northwind Live", "support_email": "alex.rivera@northwindlive.example", "legal_entity_name": "Northwind Live LLC", "suppress_powered_by": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrgBrandingPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "orgBrandings.create", "tags": ["Settings"], "x-xos-table": "app.org_brands", "x-xos-capability": "org.white_label.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an org branding", "description": "White label brand settings for Atlas, Gateway, email and Compass. Creates an org branding. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "display_name": "Northwind Live", "logo_light_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "logo_dark_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "favicon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "app_icon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "accent_hex": "#1F6FEB", "neutral_tint_hex": "#1F6FEB", "font_family": "Inter", "radius_scale": "Compact", "email_sender_name": "Northwind Live", "support_email": "alex.rivera@northwindlive.example", "legal_entity_name": "Northwind Live LLC", "suppress_powered_by": false }, "schema": { "$ref": "#/components/schemas/OrgBrandingCreate" } } } }, "responses": { "201": { "description": "The created org branding.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "display_name": "Northwind Live", "logo_light_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "logo_dark_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "favicon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "app_icon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "accent_hex": "#1F6FEB", "neutral_tint_hex": "#1F6FEB", "font_family": "Inter", "radius_scale": "Compact", "email_sender_name": "Northwind Live", "support_email": "alex.rivera@northwindlive.example", "legal_entity_name": "Northwind Live LLC", "suppress_powered_by": false }, "schema": { "$ref": "#/components/schemas/OrgBranding" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-branding/{id}": { "get": { "operationId": "orgBrandings.get", "tags": ["Settings"], "x-xos-table": "app.org_brands", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an org branding", "description": "White label brand settings for Atlas, Gateway, email and Compass. Returns one org branding with its `ETag`. A org branding the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org branding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org branding.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The org branding.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "display_name": "Northwind Live", "logo_light_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "logo_dark_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "favicon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "app_icon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "accent_hex": "#1F6FEB", "neutral_tint_hex": "#1F6FEB", "font_family": "Inter", "radius_scale": "Compact", "email_sender_name": "Northwind Live", "support_email": "alex.rivera@northwindlive.example", "legal_entity_name": "Northwind Live LLC", "suppress_powered_by": false }, "schema": { "$ref": "#/components/schemas/OrgBranding" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "orgBrandings.update", "tags": ["Settings"], "x-xos-table": "app.org_brands", "x-xos-capability": "org.white_label.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an org branding", "description": "White label brand settings for Atlas, Gateway, email and Compass. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org branding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org branding.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "display_name": "Northwind Live", "logo_light_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "logo_dark_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "favicon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "app_icon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "accent_hex": "#1F6FEB", "neutral_tint_hex": "#1F6FEB", "font_family": "Inter", "radius_scale": "Compact", "email_sender_name": "Northwind Live", "support_email": "alex.rivera@northwindlive.example", "legal_entity_name": "Northwind Live LLC", "suppress_powered_by": false }, "schema": { "$ref": "#/components/schemas/OrgBrandingUpdate" } } } }, "responses": { "200": { "description": "The updated org branding.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "display_name": "Northwind Live", "logo_light_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "logo_dark_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "favicon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "app_icon_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/logo-light.svg", "accent_hex": "#1F6FEB", "neutral_tint_hex": "#1F6FEB", "font_family": "Inter", "radius_scale": "Compact", "email_sender_name": "Northwind Live", "support_email": "alex.rivera@northwindlive.example", "legal_entity_name": "Northwind Live LLC", "suppress_powered_by": false }, "schema": { "$ref": "#/components/schemas/OrgBranding" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "orgBrandings.delete", "tags": ["Settings"], "x-xos-table": "app.org_brands", "x-xos-capability": "org.white_label.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an org branding", "description": "White label brand settings for Atlas, Gateway, email and Compass. Soft-deletes the org branding: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org branding.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org branding.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The org branding moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-legal-entities": { "get": { "operationId": "orgLegalEntities.list", "tags": ["Settings"], "x-xos-table": "app.org_legal_entities_masked", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List org legal entity rows", "description": "A legal entity of the organization with its fiscal settings. Returns a cursor page of org legal entity rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of org legal entity rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "legal_name": "Northwind Live LLC", "country_code": "US", "tax_identifier": "123456789", "fiscal_year_start_month": 1, "base_currency": "USD", "is_primary": true, "tax_identifier_last4": "6789" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrgLegalEntityPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "orgLegalEntities.create", "tags": ["Settings"], "x-xos-table": "app.org_legal_entities_masked", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an org legal entity", "description": "A legal entity of the organization with its fiscal settings. Creates an org legal entity. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "legal_name": "Northwind Live LLC", "country_code": "US", "tax_identifier": "123456789", "fiscal_year_start_month": 1, "base_currency": "USD", "is_primary": true }, "schema": { "$ref": "#/components/schemas/OrgLegalEntityCreate" } } } }, "responses": { "201": { "description": "The created org legal entity.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "legal_name": "Northwind Live LLC", "country_code": "US", "tax_identifier": "123456789", "fiscal_year_start_month": 1, "base_currency": "USD", "is_primary": true, "tax_identifier_last4": "6789" }, "schema": { "$ref": "#/components/schemas/OrgLegalEntity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-legal-entities/{id}": { "get": { "operationId": "orgLegalEntities.get", "tags": ["Settings"], "x-xos-table": "app.org_legal_entities_masked", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an org legal entity", "description": "A legal entity of the organization with its fiscal settings. Returns one org legal entity with its `ETag`. A org legal entity the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org legal entity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org legal entity.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The org legal entity.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "legal_name": "Northwind Live LLC", "country_code": "US", "tax_identifier": "123456789", "fiscal_year_start_month": 1, "base_currency": "USD", "is_primary": true, "tax_identifier_last4": "6789" }, "schema": { "$ref": "#/components/schemas/OrgLegalEntity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "orgLegalEntities.update", "tags": ["Settings"], "x-xos-table": "app.org_legal_entities_masked", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an org legal entity", "description": "A legal entity of the organization with its fiscal settings. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org legal entity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org legal entity.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "legal_name": "Northwind Live LLC", "country_code": "US", "tax_identifier": "123456789", "fiscal_year_start_month": 1, "base_currency": "USD", "is_primary": true }, "schema": { "$ref": "#/components/schemas/OrgLegalEntityUpdate" } } } }, "responses": { "200": { "description": "The updated org legal entity.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "legal_name": "Northwind Live LLC", "country_code": "US", "tax_identifier": "123456789", "fiscal_year_start_month": 1, "base_currency": "USD", "is_primary": true, "tax_identifier_last4": "6789" }, "schema": { "$ref": "#/components/schemas/OrgLegalEntity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "orgLegalEntities.delete", "tags": ["Settings"], "x-xos-table": "app.org_legal_entities_masked", "x-xos-capability": "org.legal_entities.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an org legal entity", "description": "A legal entity of the organization with its fiscal settings. Soft-deletes the org legal entity: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org legal entity.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org legal entity.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The org legal entity moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-ip-allowlist": { "get": { "operationId": "orgIpAllowlistEntries.list", "tags": ["Settings"], "x-xos-table": "app.org_ip_allowlist", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List IP allow-list entry rows", "description": "An allowed network for Atlas and the API. Returns a cursor page of IP allow-list entry rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of IP allow-list entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cidr": "203.0.113.0/24", "label": "Office" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrgIpAllowlistEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "orgIpAllowlistEntries.create", "tags": ["Settings"], "x-xos-table": "app.org_ip_allowlist", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an IP allow-list entry", "description": "An allowed network for Atlas and the API. Creates an IP allow-list entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "cidr": "203.0.113.0/24", "label": "Office" }, "schema": { "$ref": "#/components/schemas/OrgIpAllowlistEntryCreate" } } } }, "responses": { "201": { "description": "The created IP allow-list entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cidr": "203.0.113.0/24", "label": "Office" }, "schema": { "$ref": "#/components/schemas/OrgIpAllowlistEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-ip-allowlist/{id}": { "get": { "operationId": "orgIpAllowlistEntries.get", "tags": ["Settings"], "x-xos-table": "app.org_ip_allowlist", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an IP allow-list entry", "description": "An allowed network for Atlas and the API. Returns one IP allow-list entry with its `ETag`. A IP allow-list entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org ip allowlist entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org ip allowlist entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The IP allow-list entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cidr": "203.0.113.0/24", "label": "Office" }, "schema": { "$ref": "#/components/schemas/OrgIpAllowlistEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "orgIpAllowlistEntries.update", "tags": ["Settings"], "x-xos-table": "app.org_ip_allowlist", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an IP allow-list entry", "description": "An allowed network for Atlas and the API. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org ip allowlist entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org ip allowlist entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "label": "Office" }, "schema": { "$ref": "#/components/schemas/OrgIpAllowlistEntryUpdate" } } } }, "responses": { "200": { "description": "The updated IP allow-list entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cidr": "203.0.113.0/24", "label": "Office" }, "schema": { "$ref": "#/components/schemas/OrgIpAllowlistEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "orgIpAllowlistEntries.delete", "tags": ["Settings"], "x-xos-table": "app.org_ip_allowlist", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an IP allow-list entry", "description": "An allowed network for Atlas and the API. Soft-deletes the IP allow-list entry: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org ip allowlist entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org ip allowlist entry.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The IP allow-list entry moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/roles": { "get": { "operationId": "roles.list", "tags": ["Settings"], "x-xos-table": "app.roles", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List role rows", "description": "A role: a platform role or an org custom role built from the capability set. Returns a cursor page of role rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of role rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Finance Approver", "description": "Approves purchase orders up to the spend limit.", "code": "site_lead", "band": 4 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RolePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "roles.create", "tags": ["Settings"], "x-xos-table": "app.roles", "x-xos-capability": "org.roles.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a role", "description": "A role: a platform role or an org custom role built from the capability set. Creates a role. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Finance Approver", "description": "Approves purchase orders up to the spend limit.", "code": "site_lead", "band": 4 }, "schema": { "$ref": "#/components/schemas/RoleCreate" } } } }, "responses": { "201": { "description": "The created role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Finance Approver", "description": "Approves purchase orders up to the spend limit.", "code": "site_lead", "band": 4 }, "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/roles/{id}": { "get": { "operationId": "roles.get", "tags": ["Settings"], "x-xos-table": "app.roles", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a role", "description": "A role: a platform role or an org custom role built from the capability set. Returns one role with its `ETag`. A role the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Finance Approver", "description": "Approves purchase orders up to the spend limit.", "code": "site_lead", "band": 4 }, "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "roles.update", "tags": ["Settings"], "x-xos-table": "app.roles", "x-xos-capability": "org.roles.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a role", "description": "A role: a platform role or an org custom role built from the capability set. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Finance Approver", "description": "Approves purchase orders up to the spend limit.", "band": 4 }, "schema": { "$ref": "#/components/schemas/RoleUpdate" } } } }, "responses": { "200": { "description": "The updated role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Finance Approver", "description": "Approves purchase orders up to the spend limit.", "code": "site_lead", "band": 4 }, "schema": { "$ref": "#/components/schemas/Role" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "roles.delete", "tags": ["Settings"], "x-xos-table": "app.roles", "x-xos-capability": "org.roles.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a role", "description": "A role: a platform role or an org custom role built from the capability set. Soft-deletes the role: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The role moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/capabilities": { "get": { "operationId": "capabilities.list", "tags": ["Settings"], "x-xos-table": "app.capabilities", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["code"], "numeric": false }, "summary": "List capability rows", "description": "A capability from `packages/schemas/capabilities.yaml`. Read-only. Returns a cursor page of capability rows the caller may see. The default order is `code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of capability rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "code": "finance.po.approve", "module_code": "finance", "capability_class": "read", "description": "Approve purchase orders within spend authority.", "sort_order": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CapabilityPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/role-capabilities": { "get": { "operationId": "roleCapabilities.list", "tags": ["Settings"], "x-xos-table": "app.role_capabilities", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List role capability rows", "description": "A capability granted to a role. Returns a cursor page of role capability rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of role capability rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reach": "own" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RoleCapabilityPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "roleCapabilities.create", "tags": ["Settings"], "x-xos-table": "app.role_capabilities", "x-xos-capability": "org.roles.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a role capability", "description": "A capability granted to a role. Creates a role capability. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reach": "own" }, "schema": { "$ref": "#/components/schemas/RoleCapabilityCreate" } } } }, "responses": { "201": { "description": "The created role capability.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reach": "own" }, "schema": { "$ref": "#/components/schemas/RoleCapability" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/role-capabilities/{id}": { "get": { "operationId": "roleCapabilities.get", "tags": ["Settings"], "x-xos-table": "app.role_capabilities", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a role capability", "description": "A capability granted to a role. Returns one role capability with its `ETag`. A role capability the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role capability.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The role capability.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reach": "own" }, "schema": { "$ref": "#/components/schemas/RoleCapability" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "roleCapabilities.delete", "tags": ["Settings"], "x-xos-table": "app.role_capabilities", "x-xos-capability": "org.roles.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a role capability", "description": "A capability granted to a role. Soft-deletes the role capability: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the role capability.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the role capability.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The role capability moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/user-capability-grants": { "get": { "operationId": "userCapabilityGrants.list", "tags": ["Settings"], "x-xos-table": "app.user_capability_grants", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List user capability grant rows", "description": "A time-boxed capability grant to a person. A person cannot grant themselves a capability. Returns a cursor page of user capability grant rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of user capability grant rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "crew.timesheet.approve", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_kind": "organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Covering approvals during the tour." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/UserCapabilityGrantPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "userCapabilityGrants.create", "tags": ["Settings"], "x-xos-table": "app.user_capability_grants", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a user capability grant", "description": "A time-boxed capability grant to a person. A person cannot grant themselves a capability. Creates a user capability grant. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "capability_code": "crew.timesheet.approve", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_kind": "organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Covering approvals during the tour." }, "schema": { "$ref": "#/components/schemas/UserCapabilityGrantCreate" } } } }, "responses": { "201": { "description": "The created user capability grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "crew.timesheet.approve", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_kind": "organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Covering approvals during the tour." }, "schema": { "$ref": "#/components/schemas/UserCapabilityGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/user-capability-grants/{id}": { "get": { "operationId": "userCapabilityGrants.get", "tags": ["Settings"], "x-xos-table": "app.user_capability_grants", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a user capability grant", "description": "A time-boxed capability grant to a person. A person cannot grant themselves a capability. Returns one user capability grant with its `ETag`. A user capability grant the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the user capability grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the user capability grant.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The user capability grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "crew.timesheet.approve", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_kind": "organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Covering approvals during the tour." }, "schema": { "$ref": "#/components/schemas/UserCapabilityGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "userCapabilityGrants.update", "tags": ["Settings"], "x-xos-table": "app.user_capability_grants", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a user capability grant", "description": "A time-boxed capability grant to a person. A person cannot grant themselves a capability. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the user capability grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the user capability grant.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "scope_kind": "organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Covering approvals during the tour." }, "schema": { "$ref": "#/components/schemas/UserCapabilityGrantUpdate" } } } }, "responses": { "200": { "description": "The updated user capability grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "crew.timesheet.approve", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_kind": "organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Covering approvals during the tour." }, "schema": { "$ref": "#/components/schemas/UserCapabilityGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "userCapabilityGrants.delete", "tags": ["Settings"], "x-xos-table": "app.user_capability_grants", "x-xos-capability": "org.members.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a user capability grant", "description": "A time-boxed capability grant to a person. A person cannot grant themselves a capability. Soft-deletes the user capability grant: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the user capability grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the user capability grant.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The user capability grant moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-grants": { "get": { "operationId": "recordGrants.list", "tags": ["Settings"], "x-xos-table": "app.record_grants", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List record grant rows", "description": "A grant on specific records, with scope and expiry. Returns a cursor page of record grant rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of record grant rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "records.read", "valid_to": "2026-10-08T14:30:00Z", "target_kind": "organization", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Partner agreement, clause 4.2." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecordGrantPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "recordGrants.create", "tags": ["Settings"], "x-xos-table": "app.record_grants", "x-xos-capability": "org.access_grants.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a record grant", "description": "A grant on specific records, with scope and expiry. Creates a record grant. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "capability_code": "records.read", "valid_to": "2026-10-08T14:30:00Z", "target_kind": "organization", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "reason": "Partner agreement, clause 4.2." }, "schema": { "$ref": "#/components/schemas/RecordGrantCreate" } } } }, "responses": { "201": { "description": "The created record grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "records.read", "valid_to": "2026-10-08T14:30:00Z", "target_kind": "organization", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Partner agreement, clause 4.2." }, "schema": { "$ref": "#/components/schemas/RecordGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/record-grants/{id}": { "get": { "operationId": "recordGrants.get", "tags": ["Settings"], "x-xos-table": "app.record_grants", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a record grant", "description": "A grant on specific records, with scope and expiry. Returns one record grant with its `ETag`. A record grant the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record grant.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The record grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "records.read", "valid_to": "2026-10-08T14:30:00Z", "target_kind": "organization", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Partner agreement, clause 4.2." }, "schema": { "$ref": "#/components/schemas/RecordGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "recordGrants.update", "tags": ["Settings"], "x-xos-table": "app.record_grants", "x-xos-capability": "org.access_grants.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a record grant", "description": "A grant on specific records, with scope and expiry. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record grant.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "capability_code": "records.read", "valid_to": "2026-10-08T14:30:00Z", "grantee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "reason": "Partner agreement, clause 4.2." }, "schema": { "$ref": "#/components/schemas/RecordGrantUpdate" } } } }, "responses": { "200": { "description": "The updated record grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "records.read", "valid_to": "2026-10-08T14:30:00Z", "target_kind": "organization", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "granted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Partner agreement, clause 4.2." }, "schema": { "$ref": "#/components/schemas/RecordGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "recordGrants.delete", "tags": ["Settings"], "x-xos-table": "app.record_grants", "x-xos-capability": "org.access_grants.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a record grant", "description": "A grant on specific records, with scope and expiry. Soft-deletes the record grant: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the record grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the record grant.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The record grant moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/delegations": { "get": { "operationId": "delegations.list", "tags": ["Settings"], "x-xos-table": "app.delegations", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List delegation rows", "description": "A time-boxed delegation of approvals from one person to another. Returns a cursor page of delegation rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of delegation rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "delegator_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delegate_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reason": "Annual leave, 12 to 26 May." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DelegationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "delegations.create", "tags": ["Settings"], "x-xos-table": "app.delegations", "x-xos-capability": "me.out_of_office.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a delegation", "description": "A time-boxed delegation of approvals from one person to another. Creates a delegation. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "delegator_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delegate_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reason": "Annual leave, 12 to 26 May." }, "schema": { "$ref": "#/components/schemas/DelegationCreate" } } } }, "responses": { "201": { "description": "The created delegation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "delegator_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delegate_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reason": "Annual leave, 12 to 26 May." }, "schema": { "$ref": "#/components/schemas/Delegation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/delegations/{id}": { "get": { "operationId": "delegations.get", "tags": ["Settings"], "x-xos-table": "app.delegations", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a delegation", "description": "A time-boxed delegation of approvals from one person to another. Returns one delegation with its `ETag`. A delegation the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the delegation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the delegation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The delegation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "delegator_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delegate_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reason": "Annual leave, 12 to 26 May." }, "schema": { "$ref": "#/components/schemas/Delegation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "delegations.update", "tags": ["Settings"], "x-xos-table": "app.delegations", "x-xos-capability": "me.out_of_office.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a delegation", "description": "A time-boxed delegation of approvals from one person to another. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the delegation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the delegation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "capability_code": "finance.po.approve", "reason": "Annual leave, 12 to 26 May." }, "schema": { "$ref": "#/components/schemas/DelegationUpdate" } } } }, "responses": { "200": { "description": "The updated delegation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "delegator_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delegate_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "finance.po.approve", "reason": "Annual leave, 12 to 26 May." }, "schema": { "$ref": "#/components/schemas/Delegation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "delegations.delete", "tags": ["Settings"], "x-xos-table": "app.delegations", "x-xos-capability": "me.out_of_office.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a delegation", "description": "A time-boxed delegation of approvals from one person to another. Soft-deletes the delegation: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the delegation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the delegation.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The delegation moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/spend-authority": { "get": { "operationId": "spendAuthorityLimits.list", "tags": ["Settings"], "x-xos-table": "app.spend_authorities", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List spend authority limit rows", "description": "A spend limit by role or person and document type, enforced in the approval RPCs. Returns a cursor page of spend authority limit rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of spend authority limit rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_type": "Purchase Order", "limit_minor": 2500000, "dual_approval_above_minor": 10000000, "currency_code": "USD", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5100", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SpendAuthorityPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "spendAuthorityLimits.create", "tags": ["Settings"], "x-xos-table": "app.spend_authorities", "x-xos-capability": "org.spend_authority.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a spend authority limit", "description": "A spend limit by role or person and document type, enforced in the approval RPCs. Creates a spend authority limit. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_type": "Purchase Order", "limit_minor": 2500000, "dual_approval_above_minor": 10000000, "currency_code": "USD", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5100", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SpendAuthorityCreate" } } } }, "responses": { "201": { "description": "The created spend authority limit.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_type": "Purchase Order", "limit_minor": 2500000, "dual_approval_above_minor": 10000000, "currency_code": "USD", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5100", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SpendAuthority" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/spend-authority/{id}": { "get": { "operationId": "spendAuthorityLimits.get", "tags": ["Settings"], "x-xos-table": "app.spend_authorities", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a spend authority limit", "description": "A spend limit by role or person and document type, enforced in the approval RPCs. Returns one spend authority limit with its `ETag`. A spend authority limit the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the spend authority.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the spend authority.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The spend authority limit.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_type": "Purchase Order", "limit_minor": 2500000, "dual_approval_above_minor": 10000000, "currency_code": "USD", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5100", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SpendAuthority" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "spendAuthorityLimits.update", "tags": ["Settings"], "x-xos-table": "app.spend_authorities", "x-xos-capability": "org.spend_authority.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a spend authority limit", "description": "A spend limit by role or person and document type, enforced in the approval RPCs. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the spend authority.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the spend authority.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_type": "Purchase Order", "limit_minor": 2500000, "dual_approval_above_minor": 10000000, "currency_code": "USD", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5100", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SpendAuthorityUpdate" } } } }, "responses": { "200": { "description": "The updated spend authority limit.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "document_type": "Purchase Order", "limit_minor": 2500000, "dual_approval_above_minor": 10000000, "currency_code": "USD", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "account_code": "5100", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SpendAuthority" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "spendAuthorityLimits.delete", "tags": ["Settings"], "x-xos-table": "app.spend_authorities", "x-xos-capability": "org.spend_authority.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a spend authority limit", "description": "A spend limit by role or person and document type, enforced in the approval RPCs. Soft-deletes the spend authority limit: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the spend authority.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the spend authority.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The spend authority limit moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/separation-of-duties-rules": { "get": { "operationId": "separationOfDutiesRules.list", "tags": ["Settings"], "x-xos-table": "app.separation_of_duties_rules", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["code"], "numeric": false }, "summary": "List separation of duties rule rows", "description": "A separation of duties rule. Orgs may tighten defaults but never remove them. Returns a cursor page of separation of duties rule rows the caller may see. The default order is `code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of separation of duties rule rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "code": "sod_approval_requester", "enforced_on": "Purchase orders", "description": "The requester of a spend document cannot approve it." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SeparationOfDutiesRulePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/column-classifications": { "get": { "operationId": "columnClassifications.list", "tags": ["Settings"], "x-xos-table": "app.column_classifications", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["table_name"], "numeric": false }, "summary": "List column classification rows", "description": "The classification of one column in the column registry. Returns a cursor page of column classification rows the caller may see. The default order is `table_name` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of column classification rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "table_name": "app.pay_rates", "column_name": "rate_minor", "classification": "Restricted", "read_capability": "data.restricted.read.payroll" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ColumnClassificationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-review-campaigns": { "get": { "operationId": "accessReviewCampaigns.list", "tags": ["Settings"], "x-xos-table": "app.access_review_campaigns", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List access review campaign rows", "description": "A quarterly access review campaign. Returns a cursor page of access review campaign rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of access review campaign rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Q4 Access Review", "due_on": "2026-10-08", "auto_remove_unreviewed": false, "campaign_state": "Active", "opened_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AccessReviewCampaignPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "accessReviewCampaigns.create", "tags": ["Settings"], "x-xos-table": "app.access_review_campaigns", "x-xos-capability": "org.access_reviews.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an access review campaign", "description": "A quarterly access review campaign. Creates an access review campaign. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Q4 Access Review", "due_on": "2026-10-08", "auto_remove_unreviewed": false }, "schema": { "$ref": "#/components/schemas/AccessReviewCampaignCreate" } } } }, "responses": { "201": { "description": "The created access review campaign.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Q4 Access Review", "due_on": "2026-10-08", "auto_remove_unreviewed": false, "campaign_state": "Active", "opened_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccessReviewCampaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-review-campaigns/{id}": { "get": { "operationId": "accessReviewCampaigns.get", "tags": ["Settings"], "x-xos-table": "app.access_review_campaigns", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an access review campaign", "description": "A quarterly access review campaign. Returns one access review campaign with its `ETag`. A access review campaign the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access review campaign.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access review campaign.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The access review campaign.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Q4 Access Review", "due_on": "2026-10-08", "auto_remove_unreviewed": false, "campaign_state": "Active", "opened_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccessReviewCampaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "accessReviewCampaigns.update", "tags": ["Settings"], "x-xos-table": "app.access_review_campaigns", "x-xos-capability": "org.access_reviews.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an access review campaign", "description": "A quarterly access review campaign. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access review campaign.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access review campaign.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Q4 Access Review", "due_on": "2026-10-08", "auto_remove_unreviewed": false }, "schema": { "$ref": "#/components/schemas/AccessReviewCampaignUpdate" } } } }, "responses": { "200": { "description": "The updated access review campaign.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Q4 Access Review", "due_on": "2026-10-08", "auto_remove_unreviewed": false, "campaign_state": "Active", "opened_at": "2026-10-08T14:30:00Z", "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccessReviewCampaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "accessReviewCampaigns.delete", "tags": ["Settings"], "x-xos-table": "app.access_review_campaigns", "x-xos-capability": "org.access_reviews.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an access review campaign", "description": "A quarterly access review campaign. Soft-deletes the access review campaign: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access review campaign.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access review campaign.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The access review campaign moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-review-items": { "get": { "operationId": "accessReviewItems.list", "tags": ["Settings"], "x-xos-table": "app.access_review_items", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List access review item rows", "description": "One membership role to confirm or remove. Returns a cursor page of access review item rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of access review item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_review_campaign_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decision": "Confirmed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "flagged_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AccessReviewItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/access-review-items/{id}": { "get": { "operationId": "accessReviewItems.get", "tags": ["Settings"], "x-xos-table": "app.access_review_items", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an access review item", "description": "One membership role to confirm or remove. Returns one access review item with its `ETag`. A access review item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access review item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access review item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The access review item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_review_campaign_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decision": "Confirmed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "flagged_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccessReviewItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "accessReviewItems.update", "tags": ["Settings"], "x-xos-table": "app.access_review_items", "x-xos-capability": "org.access_reviews.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an access review item", "description": "One membership role to confirm or remove. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the access review item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the access review item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "decision": "Confirmed" }, "schema": { "$ref": "#/components/schemas/AccessReviewItemUpdate" } } } }, "responses": { "200": { "description": "The updated access review item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_review_campaign_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decision": "Confirmed", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "flagged_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AccessReviewItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/break-glass-sessions": { "get": { "operationId": "breakGlassSessions.list", "tags": ["Settings"], "x-xos-table": "app.break_glass_sessions", "x-xos-capability": "audit.log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["audit"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List break glass session rows", "description": "One hour of emergency full access for an Owner. Requires MFA and a reason; every Admin is notified. Returns a cursor page of break glass session rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of break glass session rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Payroll export failed during show day and must run now.", "started_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/BreakGlassSessionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "breakGlassSessions.create", "tags": ["Settings"], "x-xos-table": "app.break_glass_sessions", "x-xos-capability": "org.break_glass.use", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a break glass session", "description": "One hour of emergency full access for an Owner. Requires MFA and a reason; every Admin is notified. Creates a break glass session. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Payroll export failed during show day and must run now." }, "schema": { "$ref": "#/components/schemas/BreakGlassSessionCreate" } } } }, "responses": { "201": { "description": "The created break glass session.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Payroll export failed during show day and must run now.", "started_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/BreakGlassSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/break-glass-sessions/{id}": { "get": { "operationId": "breakGlassSessions.get", "tags": ["Settings"], "x-xos-table": "app.break_glass_sessions", "x-xos-capability": "audit.log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["audit"] }], "summary": "Get a break glass session", "description": "One hour of emergency full access for an Owner. Requires MFA and a reason; every Admin is notified. Returns one break glass session with its `ETag`. A break glass session the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the break glass session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the break glass session.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The break glass session.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Payroll export failed during show day and must run now.", "started_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/BreakGlassSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/break-glass-sessions/{id}/end": { "post": { "operationId": "breakGlassSessions.end", "tags": ["Settings"], "x-xos-table": "app.break_glass_sessions", "x-xos-capability": "org.break_glass.use", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "app.end_break_glass", "summary": "End emergency access", "description": "Ends the caller's own open break-glass session before its hour is up, through `app.end_break_glass`. Another person's session is refused with 403; one that already ended with 422. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the break glass session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the break glass session.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Payroll export failed during show day and must run now.", "started_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/BreakGlassSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-shares": { "get": { "operationId": "projectShares.list", "tags": ["Settings"], "x-xos-table": "app.project_shares", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project share rows", "description": "A project shared with a partner org, mapping its roles onto project roles. Returns a cursor page of project share rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project share rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08T14:30:00Z", "project_role": "Producer", "scope_node_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "valid_from": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectSharePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "projectShares.create", "tags": ["Settings"], "x-xos-table": "app.project_shares", "x-xos-capability": "org.access_grants.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a project share", "description": "A project shared with a partner org, mapping its roles onto project roles. Creates a project share. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08T14:30:00Z", "project_role": "Producer", "scope_node_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"] }, "schema": { "$ref": "#/components/schemas/ProjectShareCreate" } } } }, "responses": { "201": { "description": "The created project share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08T14:30:00Z", "project_role": "Producer", "scope_node_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "valid_from": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ProjectShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-shares/{id}": { "get": { "operationId": "projectShares.get", "tags": ["Settings"], "x-xos-table": "app.project_shares", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project share", "description": "A project shared with a partner org, mapping its roles onto project roles. Returns one project share with its `ETag`. A project share the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08T14:30:00Z", "project_role": "Producer", "scope_node_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "valid_from": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ProjectShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "projectShares.update", "tags": ["Settings"], "x-xos-table": "app.project_shares", "x-xos-capability": "org.access_grants.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a project share", "description": "A project shared with a partner org, mapping its roles onto project roles. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "valid_to": "2026-10-08T14:30:00Z", "project_role": "Producer", "scope_node_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"] }, "schema": { "$ref": "#/components/schemas/ProjectShareUpdate" } } } }, "responses": { "200": { "description": "The updated project share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "valid_to": "2026-10-08T14:30:00Z", "project_role": "Producer", "scope_node_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "valid_from": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ProjectShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "projectShares.delete", "tags": ["Settings"], "x-xos-table": "app.project_shares", "x-xos-capability": "org.access_grants.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a project share", "description": "A project shared with a partner org, mapping its roles onto project roles. Soft-deletes the project share: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project share.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The project share moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/scim-group-mappings": { "get": { "operationId": "scimGroupMappings.list", "tags": ["Settings"], "x-xos-table": "app.scim_group_mappings", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List SCIM group mapping rows", "description": "An identity-provider group mapped to a role or team. Returns a cursor page of SCIM group mapping rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of SCIM group mapping rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "idp_group": "event-finance", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identity_provider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ScimGroupMappingPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "scimGroupMappings.create", "tags": ["Settings"], "x-xos-table": "app.scim_group_mappings", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a SCIM group mapping", "description": "An identity-provider group mapped to a role or team. Creates a SCIM group mapping. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "idp_group": "event-finance", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identity_provider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ScimGroupMappingCreate" } } } }, "responses": { "201": { "description": "The created SCIM group mapping.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "idp_group": "event-finance", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identity_provider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ScimGroupMapping" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/scim-group-mappings/{id}": { "get": { "operationId": "scimGroupMappings.get", "tags": ["Settings"], "x-xos-table": "app.scim_group_mappings", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a SCIM group mapping", "description": "An identity-provider group mapped to a role or team. Returns one SCIM group mapping with its `ETag`. A SCIM group mapping the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the scim group mapping.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the scim group mapping.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The SCIM group mapping.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "idp_group": "event-finance", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identity_provider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ScimGroupMapping" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "scimGroupMappings.update", "tags": ["Settings"], "x-xos-table": "app.scim_group_mappings", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a SCIM group mapping", "description": "An identity-provider group mapped to a role or team. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the scim group mapping.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the scim group mapping.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "idp_group": "event-finance", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ScimGroupMappingUpdate" } } } }, "responses": { "200": { "description": "The updated SCIM group mapping.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "idp_group": "event-finance", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "identity_provider_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ScimGroupMapping" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "scimGroupMappings.delete", "tags": ["Settings"], "x-xos-table": "app.scim_group_mappings", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a SCIM group mapping", "description": "An identity-provider group mapped to a role or team. Soft-deletes the SCIM group mapping: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the scim group mapping.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the scim group mapping.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The SCIM group mapping moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api-keys": { "get": { "operationId": "apiKeys.list", "tags": ["Settings"], "x-xos-table": "app.api_keys", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List API key rows", "description": "An org-scoped API key with capability scopes and expiry. The secret is shown once and stored hashed. Returns a cursor page of API key rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of API key rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Accounting Sync", "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["finance"], "expires_at": "2026-10-08T14:30:00Z", "prefix": "xos_live_7Hq2", "last_used_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ApiKeyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "apiKeys.create", "tags": ["Settings"], "x-xos-table": "app.api_keys", "x-xos-capability": "org.api_keys.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "app.create_api_key", "summary": "Create an API key", "description": "Creates an API key with scopes and an expiry, optionally for a service account, through `app.create_api_key`. The full secret is returned once; only its hash is stored. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Accounting Sync", "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["finance"], "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ApiKeyCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "api_key_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "secret": "xos_live_7Hq2wQ1nC8vL0pR4tY6u" }, "schema": { "$ref": "#/components/schemas/ApiKeySecret" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api-keys/{id}": { "get": { "operationId": "apiKeys.get", "tags": ["Settings"], "x-xos-table": "app.api_keys", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an API key", "description": "An org-scoped API key with capability scopes and expiry. The secret is shown once and stored hashed. Returns one API key with its `ETag`. A API key the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the api key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the api key.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The API key.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Accounting Sync", "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["finance"], "expires_at": "2026-10-08T14:30:00Z", "prefix": "xos_live_7Hq2", "last_used_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "apiKeys.update", "tags": ["Settings"], "x-xos-table": "app.api_keys", "x-xos-capability": "org.api_keys.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an API key", "description": "An org-scoped API key with capability scopes and expiry. The secret is shown once and stored hashed. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the api key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the api key.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Accounting Sync", "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["finance"], "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ApiKeyUpdate" } } } }, "responses": { "200": { "description": "The updated API key.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Accounting Sync", "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["finance"], "expires_at": "2026-10-08T14:30:00Z", "prefix": "xos_live_7Hq2", "last_used_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api-keys/{id}/revoke": { "post": { "operationId": "apiKeys.revoke", "tags": ["Settings"], "x-xos-table": "app.api_keys", "x-xos-capability": "org.api_keys.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Revoke an API key", "description": "Revokes the key at once. Requires step-up authentication. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the api key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the api key.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Accounting Sync", "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["finance"], "expires_at": "2026-10-08T14:30:00Z", "prefix": "xos_live_7Hq2", "last_used_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api-keys/{id}/rotate": { "post": { "operationId": "apiKeys.rotate", "tags": ["Settings"], "x-xos-table": "app.api_keys", "x-xos-capability": "org.api_keys.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Rotate an API key", "description": "Issues a new secret and revokes the old one. The secret is shown once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the api key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the api key.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "api_key_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "secret": "xos_live_7Hq2wQ1nC8vL0pR4tY6u" }, "schema": { "$ref": "#/components/schemas/ApiKeySecret" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/service-accounts": { "get": { "operationId": "serviceAccounts.list", "tags": ["Settings"], "x-xos-table": "app.service_accounts", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List service account rows", "description": "A non-human member with its own audit identity. Returns a cursor page of service account rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of service account rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Ledger Export Bot", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_at": "2026-10-08T14:30:00Z", "user_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ServiceAccountPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "serviceAccounts.create", "tags": ["Settings"], "x-xos-table": "app.service_accounts", "x-xos-capability": "org.api_keys.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a service account", "description": "A non-human member with its own audit identity. Creates a service account. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Ledger Export Bot", "expires_at": "2026-10-08T14:30:00Z", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ServiceAccountCreate" } } } }, "responses": { "201": { "description": "The created service account.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Ledger Export Bot", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_at": "2026-10-08T14:30:00Z", "user_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ServiceAccount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/service-accounts/{id}": { "get": { "operationId": "serviceAccounts.get", "tags": ["Settings"], "x-xos-table": "app.service_accounts", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a service account", "description": "A non-human member with its own audit identity. Returns one service account with its `ETag`. A service account the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the service account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the service account.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The service account.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Ledger Export Bot", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_at": "2026-10-08T14:30:00Z", "user_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ServiceAccount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "serviceAccounts.update", "tags": ["Settings"], "x-xos-table": "app.service_accounts", "x-xos-capability": "org.api_keys.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a service account", "description": "A non-human member with its own audit identity. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the service account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the service account.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Ledger Export Bot", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ServiceAccountUpdate" } } } }, "responses": { "200": { "description": "The updated service account.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Ledger Export Bot", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expires_at": "2026-10-08T14:30:00Z", "user_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ServiceAccount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "serviceAccounts.delete", "tags": ["Settings"], "x-xos-table": "app.service_accounts", "x-xos-capability": "org.api_keys.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a service account", "description": "A non-human member with its own audit identity. Soft-deletes the service account: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the service account.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the service account.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The service account moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/oauth-apps": { "get": { "operationId": "oauthApps.list", "tags": ["Settings"], "x-xos-table": "app.oauth_apps", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List OAuth app rows", "description": "An OAuth 2.1 client using PKCE. Returns a cursor page of OAuth app rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of OAuth app rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Planner", "client_id": "xos_client_31f9", "redirect_uri": "https://northwindlive.example/files/site-plan.pdf" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OauthAppPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "oauthApps.create", "tags": ["Settings"], "x-xos-table": "app.oauth_apps", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an OAuth app", "description": "An OAuth 2.1 client using PKCE. Creates an OAuth app. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Show Planner", "redirect_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/OauthAppCreate" } } } }, "responses": { "201": { "description": "The created OAuth app.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Planner", "client_id": "xos_client_31f9", "redirect_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/OauthApp" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/oauth-apps/{id}": { "get": { "operationId": "oauthApps.get", "tags": ["Settings"], "x-xos-table": "app.oauth_apps", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an OAuth app", "description": "An OAuth 2.1 client using PKCE. Returns one OAuth app with its `ETag`. A OAuth app the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the oauth app.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the oauth app.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The OAuth app.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Planner", "client_id": "xos_client_31f9", "redirect_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/OauthApp" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "oauthApps.update", "tags": ["Settings"], "x-xos-table": "app.oauth_apps", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an OAuth app", "description": "An OAuth 2.1 client using PKCE. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the oauth app.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the oauth app.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Show Planner", "redirect_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/OauthAppUpdate" } } } }, "responses": { "200": { "description": "The updated OAuth app.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Planner", "client_id": "xos_client_31f9", "redirect_uri": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/OauthApp" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "oauthApps.delete", "tags": ["Settings"], "x-xos-table": "app.oauth_apps", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an OAuth app", "description": "An OAuth 2.1 client using PKCE. Soft-deletes the OAuth app: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the oauth app.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the oauth app.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The OAuth app moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/oauth-grants": { "get": { "operationId": "oauthGrants.list", "tags": ["Settings"], "x-xos-table": "app.oauth_grants", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List OAuth grant rows", "description": "A user's consent grant to an OAuth app. Revocable. Returns a cursor page of OAuth grant rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of OAuth grant rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "oauth_app_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["records"], "granted_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OauthGrantPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/oauth-grants/{id}": { "get": { "operationId": "oauthGrants.get", "tags": ["Settings"], "x-xos-table": "app.oauth_grants", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get an OAuth grant", "description": "A user's consent grant to an OAuth app. Revocable. Returns one OAuth grant with its `ETag`. A OAuth grant the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the oauth grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the oauth grant.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The OAuth grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "oauth_app_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["records"], "granted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OauthGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "oauthGrants.delete", "tags": ["Settings"], "x-xos-table": "app.oauth_grants", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete an OAuth grant", "description": "A user's consent grant to an OAuth app. Revocable. Soft-deletes the OAuth grant: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the oauth grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the oauth grant.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The OAuth grant moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/integrations": { "get": { "operationId": "integrations.list", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List integration rows", "description": "An integration connection (Section 17). Credentials are stored in Supabase Vault through the credential action and never returned. Returns a cursor page of integration rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of integration rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider_code": "xero", "last_synced_at": "2026-10-08T14:30:00Z", "display_name": "Northwind Xero", "external_account_id": "tenant-nwl", "connection_state": "Connected", "credential_kind": "OAuth Token", "credential_expires_at": "2026-10-08T14:30:00Z", "last_error_code": "credential_refused", "last_error_message": "Xero refused the token." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/IntegrationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "integrations.create", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an integration", "description": "An integration connection (Section 17). Credentials are stored in Supabase Vault through the credential action and never returned. Creates an integration. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "provider_code": "xero", "display_name": "Northwind Xero", "external_account_id": "tenant-nwl" }, "schema": { "$ref": "#/components/schemas/IntegrationCreate" } } } }, "responses": { "201": { "description": "The created integration.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider_code": "xero", "last_synced_at": "2026-10-08T14:30:00Z", "display_name": "Northwind Xero", "external_account_id": "tenant-nwl", "connection_state": "Connected", "credential_kind": "OAuth Token", "credential_expires_at": "2026-10-08T14:30:00Z", "last_error_code": "credential_refused", "last_error_message": "Xero refused the token." }, "schema": { "$ref": "#/components/schemas/Integration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/integrations/{id}": { "get": { "operationId": "integrations.get", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an integration", "description": "An integration connection (Section 17). Credentials are stored in Supabase Vault through the credential action and never returned. Returns one integration with its `ETag`. A integration the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the integration.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the integration.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The integration.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider_code": "xero", "last_synced_at": "2026-10-08T14:30:00Z", "display_name": "Northwind Xero", "external_account_id": "tenant-nwl", "connection_state": "Connected", "credential_kind": "OAuth Token", "credential_expires_at": "2026-10-08T14:30:00Z", "last_error_code": "credential_refused", "last_error_message": "Xero refused the token." }, "schema": { "$ref": "#/components/schemas/Integration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "integrations.update", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an integration", "description": "An integration connection (Section 17). Credentials are stored in Supabase Vault through the credential action and never returned. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the integration.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the integration.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "display_name": "Northwind Xero", "external_account_id": "tenant-nwl" }, "schema": { "$ref": "#/components/schemas/IntegrationUpdate" } } } }, "responses": { "200": { "description": "The updated integration.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider_code": "xero", "last_synced_at": "2026-10-08T14:30:00Z", "display_name": "Northwind Xero", "external_account_id": "tenant-nwl", "connection_state": "Connected", "credential_kind": "OAuth Token", "credential_expires_at": "2026-10-08T14:30:00Z", "last_error_code": "credential_refused", "last_error_message": "Xero refused the token." }, "schema": { "$ref": "#/components/schemas/Integration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "integrations.delete", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an integration", "description": "An integration connection (Section 17). Credentials are stored in Supabase Vault through the credential action and never returned. Soft-deletes the integration: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the integration.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the integration.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The integration moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/integrations/{id}/transitions": { "post": { "operationId": "integrations.transition", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Change an integration's state", "description": "Moves a connection with compare-and-set: connect (needs a stored, unexpired credential unless the provider needs none), pause, resume or disconnect (destroys the Vault secret and cancels queued runs). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the integration.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the integration.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Connected", "next_state": "Connected", "reason": "Authorized in Xero." }, "schema": { "$ref": "#/components/schemas/IntegrationTransition" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider_code": "xero", "last_synced_at": "2026-10-08T14:30:00Z", "display_name": "Northwind Xero", "external_account_id": "tenant-nwl", "connection_state": "Connected", "credential_kind": "OAuth Token", "credential_expires_at": "2026-10-08T14:30:00Z", "last_error_code": "credential_refused", "last_error_message": "Xero refused the token." }, "schema": { "$ref": "#/components/schemas/Integration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/integrations/{id}/credential": { "post": { "operationId": "integrations.storeCredential", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Store an integration credential", "description": "Stores or rotates the connection's secret in Supabase Vault. The secret is never returned. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the integration.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the integration.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "secret": "{\"access_token\":\"...\"}", "kind": "OAuth Token", "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/IntegrationCredential" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "provider_code": "xero", "last_synced_at": "2026-10-08T14:30:00Z", "display_name": "Northwind Xero", "external_account_id": "tenant-nwl", "connection_state": "Connected", "credential_kind": "OAuth Token", "credential_expires_at": "2026-10-08T14:30:00Z", "last_error_code": "credential_refused", "last_error_message": "Xero refused the token." }, "schema": { "$ref": "#/components/schemas/Integration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/integrations/{id}/syncs": { "post": { "operationId": "integrations.sync", "tags": ["Settings"], "x-xos-table": "app.integration_connections", "x-xos-capability": "org.integrations.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Queue an integration sync", "description": "Queues a sync run on a Connected connection; the run is attempted by the platform job queue with retries. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the integration.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the integration.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "scope": "Ledger Export", "direction": "Outbound", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/IntegrationSyncRequest" } } } }, "responses": { "202": { "description": "Accepted for processing.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "sync_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/IntegrationSyncQueued" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook-endpoints": { "get": { "operationId": "webhookEndpoints.list", "tags": ["Settings"], "x-xos-table": "app.webhook_endpoints", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List webhook endpoint rows", "description": "A webhook endpoint. Deliveries are signed with HMAC-SHA256 and retried for 72 hours. Returns a cursor page of webhook endpoint rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of webhook endpoint rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "url": "https://northwindlive.example/files/site-plan.pdf", "events": ["record.state_changed", "po.approved"], "description": "Sync approved POs to the ERP.", "disabled_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WebhookEndpointPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "webhookEndpoints.create", "tags": ["Settings"], "x-xos-table": "app.webhook_endpoints", "x-xos-capability": "org.webhooks.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "app.create_webhook_endpoint", "summary": "Create a webhook endpoint", "description": "Creates an endpoint subscribed to the given event types through `app.create_webhook_endpoint`. The signing secret is returned once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "url": "https://northwindlive.example/files/site-plan.pdf", "events": ["record.state_changed", "po.approved"], "description": "Sync approved POs to the ERP." }, "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "webhook_endpoint_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "signing_secret": "whsec_5Jk2pQ8xL1nV7cR3" }, "schema": { "$ref": "#/components/schemas/WebhookEndpointSecret" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook-endpoints/{id}": { "get": { "operationId": "webhookEndpoints.get", "tags": ["Settings"], "x-xos-table": "app.webhook_endpoints", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a webhook endpoint", "description": "A webhook endpoint. Deliveries are signed with HMAC-SHA256 and retried for 72 hours. Returns one webhook endpoint with its `ETag`. A webhook endpoint the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the webhook endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the webhook endpoint.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The webhook endpoint.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "url": "https://northwindlive.example/files/site-plan.pdf", "events": ["record.state_changed", "po.approved"], "description": "Sync approved POs to the ERP.", "disabled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "webhookEndpoints.update", "tags": ["Settings"], "x-xos-table": "app.webhook_endpoints", "x-xos-capability": "org.webhooks.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a webhook endpoint", "description": "A webhook endpoint. Deliveries are signed with HMAC-SHA256 and retried for 72 hours. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the webhook endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the webhook endpoint.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "url": "https://northwindlive.example/files/site-plan.pdf", "events": ["record.state_changed", "po.approved"], "description": "Sync approved POs to the ERP.", "disabled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } } }, "responses": { "200": { "description": "The updated webhook endpoint.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "url": "https://northwindlive.example/files/site-plan.pdf", "events": ["record.state_changed", "po.approved"], "description": "Sync approved POs to the ERP.", "disabled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "webhookEndpoints.delete", "tags": ["Settings"], "x-xos-table": "app.webhook_endpoints", "x-xos-capability": "org.webhooks.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a webhook endpoint", "description": "A webhook endpoint. Deliveries are signed with HMAC-SHA256 and retried for 72 hours. Soft-deletes the webhook endpoint: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the webhook endpoint.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the webhook endpoint.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The webhook endpoint moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook-deliveries": { "get": { "operationId": "webhookDeliveries.list", "tags": ["Settings"], "x-xos-table": "app.webhook_deliveries", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List webhook delivery rows", "description": "A webhook delivery attempt, replayable from Atlas. Returns a cursor page of webhook delivery rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of webhook delivery rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "webhook_endpoint_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_status": "Delivered", "delivered_at": "2026-10-08T14:30:00Z", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attempt_count": 1, "next_attempt_at": "2026-10-08T14:30:00Z", "last_attempt_at": "2026-10-08T14:30:00Z", "last_response_status": 200, "last_error": "Connection timed out.", "replay_requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WebhookDeliveryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook-deliveries/{id}": { "get": { "operationId": "webhookDeliveries.get", "tags": ["Settings"], "x-xos-table": "app.webhook_deliveries", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a webhook delivery", "description": "A webhook delivery attempt, replayable from Atlas. Returns one webhook delivery with its `ETag`. A webhook delivery the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the webhook delivery.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the webhook delivery.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The webhook delivery.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "webhook_endpoint_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_status": "Delivered", "delivered_at": "2026-10-08T14:30:00Z", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attempt_count": 1, "next_attempt_at": "2026-10-08T14:30:00Z", "last_attempt_at": "2026-10-08T14:30:00Z", "last_response_status": 200, "last_error": "Connection timed out.", "replay_requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook-deliveries/{id}/replay": { "post": { "operationId": "webhookDeliveries.replay", "tags": ["Settings"], "x-xos-table": "app.webhook_deliveries", "x-xos-capability": "org.webhooks.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Replay a webhook delivery", "description": "Sends the delivery again with a fresh signature. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the webhook delivery.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the webhook delivery.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Accepted for processing.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "webhook_endpoint_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "delivery_status": "Delivered", "delivered_at": "2026-10-08T14:30:00Z", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attempt_count": 1, "next_attempt_at": "2026-10-08T14:30:00Z", "last_attempt_at": "2026-10-08T14:30:00Z", "last_response_status": 200, "last_error": "Connection timed out.", "replay_requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhook-events": { "get": { "operationId": "webhookEventTypes.list", "tags": ["Settings"], "x-xos-table": "app.domain_event_catalog", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["code"], "numeric": false }, "summary": "List webhook event type rows", "description": "A webhook event from the domain event table. Returns a cursor page of webhook event type rows the caller may see. The default order is `code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of webhook event type rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "code": "record.state_changed", "description": "A record moved to another state.", "subject": "purchase_orders" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WebhookEventTypePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/setting-definitions": { "get": { "operationId": "settingDefinitions.list", "tags": ["Settings"], "x-xos-table": "app.setting_definitions", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["setting_key"], "numeric": false }, "summary": "List setting definition rows", "description": "A setting generated from `settings.yaml`. Returns a cursor page of setting definition rows the caller may see. The default order is `setting_key` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of setting definition rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "setting_key": "finance.base_currency", "scope": "Organization", "value_type": "string", "edit_capability": "settings.finance.write", "overridable": true } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SettingDefinitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/setting-values": { "get": { "operationId": "settingValues.list", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List setting value rows", "description": "A setting value at one scope. The most specific scope wins unless a lock applies. Returns a cursor page of setting value rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of setting value rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_type": "Organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "finance.base_currency", "value": "USD" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SettingValuePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "settingValues.create", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.general.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a setting value", "description": "A setting value at one scope. The most specific scope wins unless a lock applies. Creates a setting value. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "scope_type": "Organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "finance.base_currency", "value": "USD" }, "schema": { "$ref": "#/components/schemas/SettingValueCreate" } } } }, "responses": { "201": { "description": "The created setting value.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_type": "Organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "finance.base_currency", "value": "USD" }, "schema": { "$ref": "#/components/schemas/SettingValue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/setting-values/{id}": { "get": { "operationId": "settingValues.get", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a setting value", "description": "A setting value at one scope. The most specific scope wins unless a lock applies. Returns one setting value with its `ETag`. A setting value the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the setting value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the setting value.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The setting value.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_type": "Organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "finance.base_currency", "value": "USD" }, "schema": { "$ref": "#/components/schemas/SettingValue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "settingValues.update", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.general.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a setting value", "description": "A setting value at one scope. The most specific scope wins unless a lock applies. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the setting value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the setting value.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "value": "USD" }, "schema": { "$ref": "#/components/schemas/SettingValueUpdate" } } } }, "responses": { "200": { "description": "The updated setting value.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_type": "Organization", "scope_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "finance.base_currency", "value": "USD" }, "schema": { "$ref": "#/components/schemas/SettingValue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "settingValues.delete", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.general.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a setting value", "description": "A setting value at one scope. The most specific scope wins unless a lock applies. Soft-deletes the setting value: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the setting value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the setting value.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The setting value moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/setting-locks": { "get": { "operationId": "settingLocks.list", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List setting lock rows", "description": "A lock that stops lower scopes from overriding a setting. Returns a cursor page of setting lock rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of setting lock rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "security.mfa_required" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SettingLockPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "settingLocks.create", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a setting lock", "description": "A lock that stops lower scopes from overriding a setting. Creates a setting lock. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "setting_key": "security.mfa_required" }, "schema": { "$ref": "#/components/schemas/SettingLockCreate" } } } }, "responses": { "201": { "description": "The created setting lock.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "security.mfa_required" }, "schema": { "$ref": "#/components/schemas/SettingLock" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/setting-locks/{id}": { "get": { "operationId": "settingLocks.get", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a setting lock", "description": "A lock that stops lower scopes from overriding a setting. Returns one setting lock with its `ETag`. A setting lock the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the setting lock.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the setting lock.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The setting lock.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "setting_key": "security.mfa_required" }, "schema": { "$ref": "#/components/schemas/SettingLock" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "settingLocks.delete", "tags": ["Settings"], "x-xos-table": "app.setting_values", "x-xos-capability": "org.security.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a setting lock", "description": "A lock that stops lower scopes from overriding a setting. Soft-deletes the setting lock: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the setting lock.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the setting lock.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The setting lock moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/audit-events": { "get": { "operationId": "auditEvents.list", "tags": ["Settings"], "x-xos-table": "app.audit_events", "x-xos-capability": "audit.log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["audit"] }], "x-xos-order": { "by": ["id"], "numeric": false }, "summary": "List audit event rows", "description": "An append-only compliance audit event, retained 7 years. Returns a cursor page of audit event rows the caller may see. The default order is `id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of audit event rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "action": "purchase_order.approved", "diff": { "type": "doc" }, "actor_kind": "Person", "actor_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "purchase_orders", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actor_ip": "203.0.113.24", "user_agent": "Mozilla/5.0", "request_id": "req_01J9Z6", "redacted_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AuditEventPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/audit-events/{id}": { "get": { "operationId": "auditEvents.get", "tags": ["Settings"], "x-xos-table": "app.audit_events", "x-xos-capability": "audit.log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["audit"] }], "summary": "Get an audit event", "description": "An append-only compliance audit event, retained 7 years. Returns one audit event with its `ETag`. A audit event the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the audit event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the audit event.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The audit event.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "action": "purchase_order.approved", "diff": { "type": "doc" }, "actor_kind": "Person", "actor_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "purchase_orders", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actor_ip": "203.0.113.24", "user_agent": "Mozilla/5.0", "request_id": "req_01J9Z6", "redacted_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AuditEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/consent-records": { "get": { "operationId": "consentRecords.list", "tags": ["Settings"], "x-xos-table": "app.consent_records", "x-xos-capability": "data.request.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List consent record rows", "description": "A consent given or withdrawn. Returns a cursor page of consent record rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of consent record rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose_code": "marketing_email", "notice_version": "2026-10-01", "source": "Web", "captured_at": "2026-10-08T14:30:00Z", "captured_ip": "203.0.113.24", "withdrawn_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ConsentRecordPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "consentRecords.create", "tags": ["Settings"], "x-xos-table": "app.consent_records", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a consent record", "description": "A consent given or withdrawn. Creates a consent record. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose_code": "marketing_email", "notice_version": "2026-10-01", "source": "Web" }, "schema": { "$ref": "#/components/schemas/ConsentRecordCreate" } } } }, "responses": { "201": { "description": "The created consent record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose_code": "marketing_email", "notice_version": "2026-10-01", "source": "Web", "captured_at": "2026-10-08T14:30:00Z", "captured_ip": "203.0.113.24", "withdrawn_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ConsentRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/consent-records/{id}": { "get": { "operationId": "consentRecords.get", "tags": ["Settings"], "x-xos-table": "app.consent_records", "x-xos-capability": "data.request.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get a consent record", "description": "A consent given or withdrawn. Returns one consent record with its `ETag`. A consent record the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the consent record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the consent record.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The consent record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose_code": "marketing_email", "notice_version": "2026-10-01", "source": "Web", "captured_at": "2026-10-08T14:30:00Z", "captured_ip": "203.0.113.24", "withdrawn_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ConsentRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dsar-requests": { "get": { "operationId": "dsarRequests.list", "tags": ["Settings"], "x-xos-table": "app.dsar_requests", "x-xos-capability": "data.request.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List DSAR request rows", "description": "A data subject access request. Returns a cursor page of DSAR request rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of DSAR request rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_type": "Access", "dsar_state": "In Review", "subject_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_email": "alex.rivera@northwindlive.example", "details": "Send me my timesheets.", "received_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DsarRequestPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "dsarRequests.create", "tags": ["Settings"], "x-xos-table": "app.dsar_requests", "x-xos-capability": "data.request.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Create a DSAR request", "description": "A data subject access request. Creates a DSAR request. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "request_type": "Access", "subject_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_email": "alex.rivera@northwindlive.example", "details": "Send me my timesheets." }, "schema": { "$ref": "#/components/schemas/DsarRequestCreate" } } } }, "responses": { "201": { "description": "The created DSAR request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_type": "Access", "dsar_state": "In Review", "subject_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_email": "alex.rivera@northwindlive.example", "details": "Send me my timesheets.", "received_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DsarRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dsar-requests/{id}": { "get": { "operationId": "dsarRequests.get", "tags": ["Settings"], "x-xos-table": "app.dsar_requests", "x-xos-capability": "data.request.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get a DSAR request", "description": "A data subject access request. Returns one DSAR request with its `ETag`. A DSAR request the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dsar request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dsar request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The DSAR request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_type": "Access", "dsar_state": "In Review", "subject_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_email": "alex.rivera@northwindlive.example", "details": "Send me my timesheets.", "received_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DsarRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/retention-policies": { "get": { "operationId": "retentionPolicies.list", "tags": ["Settings"], "x-xos-table": "app.retention_policies", "x-xos-capability": "data.retention.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["table_name"], "numeric": false }, "summary": "List retention policy rows", "description": "Retention of soft-deleted rows per table. Returns a cursor page of retention policy rows the caller may see. The default order is `table_name` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of retention policy rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "table_name": "app.activity_events", "basis": "Soft Deleted", "time_column": "deleted_at", "retention": "7 years", "purge_method": "Delete", "redact_personal_data_after": "90 days", "rationale": "Tax records are kept seven years." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RetentionPolicyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-exports": { "get": { "operationId": "orgExports.list", "tags": ["Settings"], "x-xos-table": "app.org_exports", "x-xos-capability": "org.organization.delete", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List org export rows", "description": "A full organization export. Returns a cursor page of org export rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of org export rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "table_count": 412, "row_count": 182340, "file_count": 96, "manifest_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrgExportPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "orgExports.create", "tags": ["Settings"], "x-xos-table": "app.org_exports", "x-xos-capability": "org.organization.delete", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an org export", "description": "A full organization export. Creates an org export. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "table_count": 412, "row_count": 182340, "file_count": 96, "manifest_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/OrgExportCreate" } } } }, "responses": { "201": { "description": "The created org export.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "table_count": 412, "row_count": 182340, "file_count": 96, "manifest_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/OrgExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-exports/{id}": { "get": { "operationId": "orgExports.get", "tags": ["Settings"], "x-xos-table": "app.org_exports", "x-xos-capability": "org.organization.delete", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an org export", "description": "A full organization export. Returns one org export with its `ETag`. A org export the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org export.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org export.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The org export.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "table_count": 412, "row_count": 182340, "file_count": 96, "manifest_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b" }, "schema": { "$ref": "#/components/schemas/OrgExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-settings": { "get": { "operationId": "aiSettings.list", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List AI settings rows", "description": "AI feature switches. Every feature is off until an Admin turns it on. Returns a cursor page of AI settings rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of AI settings rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assistant_enabled": false, "extraction_enabled": false, "drafting_enabled": false, "plain_language_enabled": false, "summaries_enabled": false, "mapping_enabled": false } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AiSettingsPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-settings/{id}": { "get": { "operationId": "aiSettings.get", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an AI settings", "description": "AI feature switches. Every feature is off until an Admin turns it on. Returns one AI settings with its `ETag`. A AI settings the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai settings.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai settings.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The AI settings.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assistant_enabled": false, "extraction_enabled": false, "drafting_enabled": false, "plain_language_enabled": false, "summaries_enabled": false, "mapping_enabled": false }, "schema": { "$ref": "#/components/schemas/AiSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "aiSettings.update", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "org.ai.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an AI settings", "description": "AI feature switches. Every feature is off until an Admin turns it on. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai settings.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai settings.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "assistant_enabled": false, "extraction_enabled": false, "drafting_enabled": false, "plain_language_enabled": false, "summaries_enabled": false, "mapping_enabled": false }, "schema": { "$ref": "#/components/schemas/AiSettingsUpdate" } } } }, "responses": { "200": { "description": "The updated AI settings.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assistant_enabled": false, "extraction_enabled": false, "drafting_enabled": false, "plain_language_enabled": false, "summaries_enabled": false, "mapping_enabled": false }, "schema": { "$ref": "#/components/schemas/AiSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-settings/save": { "post": { "operationId": "aiSettings.save", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "org.ai.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Save the AI feature switches", "description": "Creates or updates the caller's org switches in one call (org.ai.write). Turning a feature on while the plan lacks aurora_ai is a 422 refusal, aurora_not_in_plan. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "assistant_enabled": false, "plain_language_enabled": false, "extraction_enabled": false, "drafting_enabled": false, "summaries_enabled": false, "mapping_enabled": false }, "schema": { "$ref": "#/components/schemas/AiSettingsSaveRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assistant_enabled": false, "extraction_enabled": false, "drafting_enabled": false, "plain_language_enabled": false, "summaries_enabled": false, "mapping_enabled": false }, "schema": { "$ref": "#/components/schemas/AiSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-definitions": { "get": { "operationId": "reportDefinitions.list", "tags": ["Reports"], "x-xos-table": "app.report_definitions", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List report definition rows", "description": "A report definition with NULL-aware aggregates. Reports respect RLS and masking. Returns a cursor page of report definition rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of report definition rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Labor by Department", "source_code": "crew", "chart": "Table", "group_by_field": "dept_code", "shared": false, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportDefinitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "reportDefinitions.create", "tags": ["Reports"], "x-xos-table": "app.report_definitions", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Create a report definition", "description": "A report definition with NULL-aware aggregates. Reports respect RLS and masking. Creates a report definition. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Labor by Department", "source_code": "crew", "chart": "Table", "group_by_field": "dept_code", "shared": false, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportDefinitionCreate" } } } }, "responses": { "201": { "description": "The created report definition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Labor by Department", "source_code": "crew", "chart": "Table", "group_by_field": "dept_code", "shared": false, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-definitions/{id}": { "get": { "operationId": "reportDefinitions.get", "tags": ["Reports"], "x-xos-table": "app.report_definitions", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Get a report definition", "description": "A report definition with NULL-aware aggregates. Reports respect RLS and masking. Returns one report definition with its `ETag`. A report definition the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report definition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The report definition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Labor by Department", "source_code": "crew", "chart": "Table", "group_by_field": "dept_code", "shared": false, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "reportDefinitions.update", "tags": ["Reports"], "x-xos-table": "app.report_definitions", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Update a report definition", "description": "A report definition with NULL-aware aggregates. Reports respect RLS and masking. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report definition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Labor by Department", "source_code": "crew", "chart": "Table", "group_by_field": "dept_code", "shared": false, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportDefinitionUpdate" } } } }, "responses": { "200": { "description": "The updated report definition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Labor by Department", "source_code": "crew", "chart": "Table", "group_by_field": "dept_code", "shared": false, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "reportDefinitions.delete", "tags": ["Reports"], "x-xos-table": "app.report_definitions", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Delete a report definition", "description": "A report definition with NULL-aware aggregates. Reports respect RLS and masking. Soft-deletes the report definition: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report definition.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The report definition moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-runs": { "get": { "operationId": "reportRuns.list", "tags": ["Reports"], "x-xos-table": "app.report_runs", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List report run rows", "description": "A run of a report definition. Returns a cursor page of report run rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of report run rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV", "run_status": "Queued", "finished_at": "2026-10-08T14:30:00Z", "run_for_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "started_at": "2026-10-08T14:30:00Z", "row_count": 42, "unpriced_count": 2, "last_error": "The source was removed." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportRunPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "reportRuns.create", "tags": ["Reports"], "x-xos-table": "app.report_runs", "x-xos-capability": "reports.report.export", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Create a report run", "description": "A run of a report definition. Creates a report run. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV" }, "schema": { "$ref": "#/components/schemas/ReportRunCreate" } } } }, "responses": { "201": { "description": "The created report run.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV", "run_status": "Queued", "finished_at": "2026-10-08T14:30:00Z", "run_for_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "started_at": "2026-10-08T14:30:00Z", "row_count": 42, "unpriced_count": 2, "last_error": "The source was removed." }, "schema": { "$ref": "#/components/schemas/ReportRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-runs/{id}": { "get": { "operationId": "reportRuns.get", "tags": ["Reports"], "x-xos-table": "app.report_runs", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Get a report run", "description": "A run of a report definition. Returns one report run with its `ETag`. A report run the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The report run.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV", "run_status": "Queued", "finished_at": "2026-10-08T14:30:00Z", "run_for_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "started_at": "2026-10-08T14:30:00Z", "row_count": 42, "unpriced_count": 2, "last_error": "The source was removed." }, "schema": { "$ref": "#/components/schemas/ReportRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-schedules": { "get": { "operationId": "reportSchedules.list", "tags": ["Reports"], "x-xos-table": "app.report_schedules", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List report schedule rows", "description": "A scheduled email delivery of a report to org members only. Returns a cursor page of report schedule rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of report schedule rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "cadence": "Daily", "local_hour": 8, "weekday": 1, "month_day": 1, "export_format": "CSV", "next_run_at": "2026-10-08T14:30:00Z", "paused_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportSchedulePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "reportSchedules.create", "tags": ["Reports"], "x-xos-table": "app.report_schedules", "x-xos-capability": "reports.schedule.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Create a report schedule", "description": "A scheduled email delivery of a report to org members only. Creates a report schedule. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "cadence": "Daily", "local_hour": 8, "weekday": 1, "month_day": 1, "export_format": "CSV", "paused_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ReportScheduleCreate" } } } }, "responses": { "201": { "description": "The created report schedule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "cadence": "Daily", "local_hour": 8, "weekday": 1, "month_day": 1, "export_format": "CSV", "next_run_at": "2026-10-08T14:30:00Z", "paused_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ReportSchedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-schedules/{id}": { "get": { "operationId": "reportSchedules.get", "tags": ["Reports"], "x-xos-table": "app.report_schedules", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Get a report schedule", "description": "A scheduled email delivery of a report to org members only. Returns one report schedule with its `ETag`. A report schedule the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report schedule.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The report schedule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "cadence": "Daily", "local_hour": 8, "weekday": 1, "month_day": 1, "export_format": "CSV", "next_run_at": "2026-10-08T14:30:00Z", "paused_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ReportSchedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "reportSchedules.update", "tags": ["Reports"], "x-xos-table": "app.report_schedules", "x-xos-capability": "reports.schedule.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Update a report schedule", "description": "A scheduled email delivery of a report to org members only. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report schedule.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "time_zone": "America/New_York", "cadence": "Daily", "local_hour": 8, "weekday": 1, "month_day": 1, "export_format": "CSV", "paused_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ReportScheduleUpdate" } } } }, "responses": { "200": { "description": "The updated report schedule.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "time_zone": "America/New_York", "cadence": "Daily", "local_hour": 8, "weekday": 1, "month_day": 1, "export_format": "CSV", "next_run_at": "2026-10-08T14:30:00Z", "paused_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ReportSchedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "reportSchedules.delete", "tags": ["Reports"], "x-xos-table": "app.report_schedules", "x-xos-capability": "reports.schedule.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Delete a report schedule", "description": "A scheduled email delivery of a report to org members only. Soft-deletes the report schedule: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report schedule.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The report schedule moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dashboards": { "get": { "operationId": "dashboards.list", "tags": ["Reports"], "x-xos-table": "app.dashboards", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List dashboard rows", "description": "A grid of report tiles, saved per user or per team. Returns a cursor page of dashboard rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of dashboard rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Week", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DashboardPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "dashboards.create", "tags": ["Reports"], "x-xos-table": "app.dashboards", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Create a dashboard", "description": "A grid of report tiles, saved per user or per team. Creates a dashboard. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Show Week", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DashboardCreate" } } } }, "responses": { "201": { "description": "The created dashboard.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Week", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dashboards/{id}": { "get": { "operationId": "dashboards.get", "tags": ["Reports"], "x-xos-table": "app.dashboards", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Get a dashboard", "description": "A grid of report tiles, saved per user or per team. Returns one dashboard with its `ETag`. A dashboard the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dashboard.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The dashboard.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Week", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "dashboards.update", "tags": ["Reports"], "x-xos-table": "app.dashboards", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Update a dashboard", "description": "A grid of report tiles, saved per user or per team. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dashboard.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Show Week", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DashboardUpdate" } } } }, "responses": { "200": { "description": "The updated dashboard.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Show Week", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "dashboards.delete", "tags": ["Reports"], "x-xos-table": "app.dashboards", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Delete a dashboard", "description": "A grid of report tiles, saved per user or per team. Soft-deletes the dashboard: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dashboard.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The dashboard moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dashboard-tiles": { "get": { "operationId": "dashboardTiles.list", "tags": ["Reports"], "x-xos-table": "app.dashboard_tiles", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List dashboard tile rows", "description": "A report tile on a dashboard. Returns a cursor page of dashboard tile rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of dashboard tile rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dashboard_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grid_column": 1, "grid_row": 1, "column_span": 6, "row_span": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DashboardTilePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "dashboardTiles.create", "tags": ["Reports"], "x-xos-table": "app.dashboard_tiles", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Create a dashboard tile", "description": "A report tile on a dashboard. Creates a dashboard tile. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "dashboard_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grid_column": 1, "grid_row": 1, "column_span": 6, "row_span": 1 }, "schema": { "$ref": "#/components/schemas/DashboardTileCreate" } } } }, "responses": { "201": { "description": "The created dashboard tile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dashboard_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grid_column": 1, "grid_row": 1, "column_span": 6, "row_span": 1 }, "schema": { "$ref": "#/components/schemas/DashboardTile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/dashboard-tiles/{id}": { "get": { "operationId": "dashboardTiles.get", "tags": ["Reports"], "x-xos-table": "app.dashboard_tiles", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Get a dashboard tile", "description": "A report tile on a dashboard. Returns one dashboard tile with its `ETag`. A dashboard tile the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard tile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dashboard tile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The dashboard tile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dashboard_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grid_column": 1, "grid_row": 1, "column_span": 6, "row_span": 1 }, "schema": { "$ref": "#/components/schemas/DashboardTile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "dashboardTiles.update", "tags": ["Reports"], "x-xos-table": "app.dashboard_tiles", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Update a dashboard tile", "description": "A report tile on a dashboard. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard tile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dashboard tile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grid_column": 1, "grid_row": 1, "column_span": 6, "row_span": 1 }, "schema": { "$ref": "#/components/schemas/DashboardTileUpdate" } } } }, "responses": { "200": { "description": "The updated dashboard tile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "dashboard_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grid_column": 1, "grid_row": 1, "column_span": 6, "row_span": 1 }, "schema": { "$ref": "#/components/schemas/DashboardTile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "dashboardTiles.delete", "tags": ["Reports"], "x-xos-table": "app.dashboard_tiles", "x-xos-capability": "reports.report.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Delete a dashboard tile", "description": "A report tile on a dashboard. Soft-deletes the dashboard tile: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the dashboard tile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the dashboard tile.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The dashboard tile moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/budget-vs-actual": { "get": { "operationId": "reports.budgetVsActual", "tags": ["Reports"], "x-xos-table": "app.mv_reports", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Budget versus actual", "description": "Revised budget (working budget plus approved change orders) against actual spend, grouped by one dimension. Unpriced lines stay out of each sum and are counted in `unpriced_count`. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Only this project; every visible project when omitted." }, "required": false, "description": "Only this project; every visible project when omitted.", "name": "project_id", "in": "query" }, { "schema": { "type": "string", "enum": ["account", "costCenter", "department", "urid", "project"], "description": "Grouping dimension; defaults to account.", "example": "account" }, "required": false, "description": "Grouping dimension; defaults to account.", "name": "dimension", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dimension": "5400", "budget": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "actual": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 } } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportRowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/labor-cost": { "get": { "operationId": "reports.laborCost", "tags": ["Reports"], "x-xos-table": "app.mv_reports", "x-xos-capability": "data.restricted.read.payroll", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Labor", "description": "Worked hours, timesheets and timesheets with an open entry, per readable project, from submitted time (app.timesheet_hours). Pay is Restricted and never reported here. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Only this project; every visible project when omitted." }, "required": false, "description": "Only this project; every visible project when omitted.", "name": "project_id", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dimension": "NWL", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "measure": "worked_hours", "unit": "Hours", "value": 312.5 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportMetricRowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/po-exposure": { "get": { "operationId": "reports.poExposure", "tags": ["Reports"], "x-xos-table": "app.mv_reports", "x-xos-capability": "procurement.po.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["procurement"] }], "summary": "PO exposure", "description": "Committed purchase order value (lines plus approved changes) against value received, by vendor. An order with an unpriced line stays out of each sum and is counted in `unpriced_count`. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Only this project; every visible project when omitted." }, "required": false, "description": "Only this project; every visible project when omitted.", "name": "project_id", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dimension": "5400", "budget": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "actual": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 } } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportRowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/incident-rates": { "get": { "operationId": "reports.incidentRates", "tags": ["Reports"], "x-xos-table": "app.mv_reports", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Incident rates", "description": "Incidents and open incidents per canon severity, optionally for one project and a window of occurrence. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Only this project; every visible project when omitted." }, "required": false, "description": "Only this project; every visible project when omitted.", "name": "project_id", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Occurred on or after this day.", "example": "2026-10-08" }, "required": false, "description": "Occurred on or after this day.", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Occurred on or before this day.", "example": "2026-10-08" }, "required": false, "description": "Occurred on or before this day.", "name": "to", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dimension": "NWL", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "measure": "worked_hours", "unit": "Hours", "value": 312.5 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportMetricRowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/final-cost-report": { "get": { "operationId": "reports.finalCostReport", "tags": ["Reports"], "x-xos-table": "app.mv_reports", "x-xos-capability": "finance.budget.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "Final cost report", "description": "Final cost of one project by GL account: the gate 3 baseline plus approved change orders against posted actuals from the Universal Posting Line. A project without a baseline answers 422 NO_ANSWER, never zero. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "The project reported on." }, "required": true, "description": "The project reported on.", "name": "project_id", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dimension": "5400", "budget": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 }, "actual": { "total_minor": 1250000, "currency": "USD", "unpriced_count": 2 } } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportRowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/gate-readiness": { "get": { "operationId": "reports.gateReadiness", "tags": ["Reports"], "x-xos-table": "app.mv_reports", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Gate readiness", "description": "Criteria with evidence against the next gate of each readable project: blocking and other criteria met and in total, and whether the gate is ready. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Only this project; every visible project when omitted." }, "required": false, "description": "Only this project; every visible project when omitted.", "name": "project_id", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "dimension": "NWL", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "measure": "worked_hours", "unit": "Hours", "value": 312.5 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportMetricRowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-object-types": { "get": { "operationId": "customObjectTypes.list", "tags": ["Platform"], "x-xos-table": "app.custom_object_types", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List custom object type rows", "description": "A custom object type with its own API routes at `/objects/{objectKey}`. Returns a cursor page of custom object type rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of custom object type rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "object_key": "sponsor_activation", "label": "Sponsor Activation", "icon": "sparkles", "default_view": "table" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CustomObjectTypePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "customObjectTypes.create", "tags": ["Platform"], "x-xos-table": "app.custom_object_types", "x-xos-capability": "org.custom_objects.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a custom object type", "description": "A custom object type with its own API routes at `/objects/{objectKey}`. Creates a custom object type. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "object_key": "sponsor_activation", "label": "Sponsor Activation", "icon": "sparkles", "default_view": "table" }, "schema": { "$ref": "#/components/schemas/CustomObjectTypeCreate" } } } }, "responses": { "201": { "description": "The created custom object type.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "object_key": "sponsor_activation", "label": "Sponsor Activation", "icon": "sparkles", "default_view": "table" }, "schema": { "$ref": "#/components/schemas/CustomObjectType" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-object-types/{id}": { "get": { "operationId": "customObjectTypes.get", "tags": ["Platform"], "x-xos-table": "app.custom_object_types", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a custom object type", "description": "A custom object type with its own API routes at `/objects/{objectKey}`. Returns one custom object type with its `ETag`. A custom object type the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object type.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object type.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The custom object type.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "object_key": "sponsor_activation", "label": "Sponsor Activation", "icon": "sparkles", "default_view": "table" }, "schema": { "$ref": "#/components/schemas/CustomObjectType" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "customObjectTypes.update", "tags": ["Platform"], "x-xos-table": "app.custom_object_types", "x-xos-capability": "org.custom_objects.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a custom object type", "description": "A custom object type with its own API routes at `/objects/{objectKey}`. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object type.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object type.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "label": "Sponsor Activation", "icon": "sparkles", "default_view": "table" }, "schema": { "$ref": "#/components/schemas/CustomObjectTypeUpdate" } } } }, "responses": { "200": { "description": "The updated custom object type.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "object_key": "sponsor_activation", "label": "Sponsor Activation", "icon": "sparkles", "default_view": "table" }, "schema": { "$ref": "#/components/schemas/CustomObjectType" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "customObjectTypes.delete", "tags": ["Platform"], "x-xos-table": "app.custom_object_types", "x-xos-capability": "org.custom_objects.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a custom object type", "description": "A custom object type with its own API routes at `/objects/{objectKey}`. Soft-deletes the custom object type: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object type.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object type.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The custom object type moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-object-fields": { "get": { "operationId": "customObjectFields.list", "tags": ["Platform"], "x-xos-table": "app.custom_object_fields", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List custom object field rows", "description": "A typed field of a custom object type. Returns a cursor page of custom object field rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of custom object field rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "field_key": "activation_date", "label": "Activation Date", "data_type": "date", "required": false, "filterable": true, "sort_order": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CustomObjectFieldPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "customObjectFields.create", "tags": ["Platform"], "x-xos-table": "app.custom_object_fields", "x-xos-capability": "org.custom_objects.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a custom object field", "description": "A typed field of a custom object type. Creates a custom object field. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "field_key": "activation_date", "label": "Activation Date", "data_type": "date", "required": false, "filterable": true, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomObjectFieldCreate" } } } }, "responses": { "201": { "description": "The created custom object field.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "field_key": "activation_date", "label": "Activation Date", "data_type": "date", "required": false, "filterable": true, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomObjectField" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-object-fields/{id}": { "get": { "operationId": "customObjectFields.get", "tags": ["Platform"], "x-xos-table": "app.custom_object_fields", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a custom object field", "description": "A typed field of a custom object type. Returns one custom object field with its `ETag`. A custom object field the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object field.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object field.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The custom object field.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "field_key": "activation_date", "label": "Activation Date", "data_type": "date", "required": false, "filterable": true, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomObjectField" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "customObjectFields.update", "tags": ["Platform"], "x-xos-table": "app.custom_object_fields", "x-xos-capability": "org.custom_objects.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a custom object field", "description": "A typed field of a custom object type. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object field.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object field.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "label": "Activation Date", "data_type": "date", "required": false, "filterable": true, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomObjectFieldUpdate" } } } }, "responses": { "200": { "description": "The updated custom object field.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "field_key": "activation_date", "label": "Activation Date", "data_type": "date", "required": false, "filterable": true, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomObjectField" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "customObjectFields.delete", "tags": ["Platform"], "x-xos-table": "app.custom_object_fields", "x-xos-capability": "org.custom_objects.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a custom object field", "description": "A typed field of a custom object type. Soft-deletes the custom object field: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object field.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object field.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The custom object field moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/objects/{object_key}": { "get": { "operationId": "objects.list", "tags": ["Platform"], "x-xos-table": "app.custom_object_records", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List custom object record rows", "description": "A record of a custom object. Values are stored one row per field, never as JSON. Returns a cursor page of custom object record rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The `object_key` path segment.", "example": "sponsor_activation" }, "required": true, "description": "The `object_key` path segment.", "name": "object_key", "in": "path" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of custom object record rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Harbor Lounge Activation", "values": { "activation_date": "2026-10-08" }, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CustomObjectRecordPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "objects.create", "tags": ["Platform"], "x-xos-table": "app.custom_object_records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a custom object record", "description": "A record of a custom object. Values are stored one row per field, never as JSON. Creates a custom object record. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The `object_key` path segment.", "example": "sponsor_activation" }, "required": true, "description": "The `object_key` path segment.", "name": "object_key", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Harbor Lounge Activation", "values": { "activation_date": "2026-10-08" } }, "schema": { "$ref": "#/components/schemas/CustomObjectRecordCreate" } } } }, "responses": { "201": { "description": "The created custom object record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Harbor Lounge Activation", "values": { "activation_date": "2026-10-08" }, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomObjectRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/objects/{object_key}/{id}": { "get": { "operationId": "objects.get", "tags": ["Platform"], "x-xos-table": "app.custom_object_records", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a custom object record", "description": "A record of a custom object. Values are stored one row per field, never as JSON. Returns one custom object record with its `ETag`. A custom object record the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The `object_key` path segment.", "example": "sponsor_activation" }, "required": true, "description": "The `object_key` path segment.", "name": "object_key", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object record.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The custom object record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Harbor Lounge Activation", "values": { "activation_date": "2026-10-08" }, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomObjectRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "objects.update", "tags": ["Platform"], "x-xos-table": "app.custom_object_records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a custom object record", "description": "A record of a custom object. Values are stored one row per field, never as JSON. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The `object_key` path segment.", "example": "sponsor_activation" }, "required": true, "description": "The `object_key` path segment.", "name": "object_key", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object record.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Harbor Lounge Activation", "values": { "activation_date": "2026-10-08" } }, "schema": { "$ref": "#/components/schemas/CustomObjectRecordUpdate" } } } }, "responses": { "200": { "description": "The updated custom object record.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Harbor Lounge Activation", "values": { "activation_date": "2026-10-08" }, "custom_object_type_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomObjectRecord" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "objects.delete", "tags": ["Platform"], "x-xos-table": "app.custom_object_records", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a custom object record", "description": "A record of a custom object. Values are stored one row per field, never as JSON. Soft-deletes the custom object record: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The `object_key` path segment.", "example": "sponsor_activation" }, "required": true, "description": "The `object_key` path segment.", "name": "object_key", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object record.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object record.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The custom object record moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-object-relations": { "get": { "operationId": "customObjectRelations.list", "tags": ["Platform"], "x-xos-table": "app.custom_object_relations", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List custom object relation rows", "description": "A relation from a custom object record to another record. Returns a cursor page of custom object relation rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of custom object relation rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "relation_key": "sponsor", "to_custom_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CustomObjectRelationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "customObjectRelations.create", "tags": ["Platform"], "x-xos-table": "app.custom_object_relations", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a custom object relation", "description": "A relation from a custom object record to another record. Creates a custom object relation. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "from_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "relation_key": "sponsor", "to_custom_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomObjectRelationCreate" } } } }, "responses": { "201": { "description": "The created custom object relation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "relation_key": "sponsor", "to_custom_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomObjectRelation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-object-relations/{id}": { "get": { "operationId": "customObjectRelations.get", "tags": ["Platform"], "x-xos-table": "app.custom_object_relations", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a custom object relation", "description": "A relation from a custom object record to another record. Returns one custom object relation with its `ETag`. A custom object relation the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object relation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object relation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The custom object relation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "relation_key": "sponsor", "to_custom_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomObjectRelation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "customObjectRelations.delete", "tags": ["Platform"], "x-xos-table": "app.custom_object_relations", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a custom object relation", "description": "A relation from a custom object record to another record. Soft-deletes the custom object relation: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom object relation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom object relation.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The custom object relation moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-field-definitions": { "get": { "operationId": "customFieldDefinitions.list", "tags": ["Platform"], "x-xos-table": "app.custom_field_definitions", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List custom field definition rows", "description": "A custom field on a built-in resource. Returns a cursor page of custom field definition rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of custom field definition rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_table": "app.vendors", "field_key": "union_signatory", "label": "Union Signatory", "data_type": "boolean", "required": false, "filterable": false, "sort_order": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "customFieldDefinitions.create", "tags": ["Platform"], "x-xos-table": "app.custom_field_definitions", "x-xos-capability": "org.custom_fields.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a custom field definition", "description": "A custom field on a built-in resource. Creates a custom field definition. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "target_table": "app.vendors", "field_key": "union_signatory", "label": "Union Signatory", "data_type": "boolean", "required": false, "filterable": false, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionCreate" } } } }, "responses": { "201": { "description": "The created custom field definition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_table": "app.vendors", "field_key": "union_signatory", "label": "Union Signatory", "data_type": "boolean", "required": false, "filterable": false, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomFieldDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-field-definitions/{id}": { "get": { "operationId": "customFieldDefinitions.get", "tags": ["Platform"], "x-xos-table": "app.custom_field_definitions", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a custom field definition", "description": "A custom field on a built-in resource. Returns one custom field definition with its `ETag`. A custom field definition the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom field definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom field definition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The custom field definition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_table": "app.vendors", "field_key": "union_signatory", "label": "Union Signatory", "data_type": "boolean", "required": false, "filterable": false, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomFieldDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "customFieldDefinitions.update", "tags": ["Platform"], "x-xos-table": "app.custom_field_definitions", "x-xos-capability": "org.custom_fields.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a custom field definition", "description": "A custom field on a built-in resource. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom field definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom field definition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "label": "Union Signatory", "data_type": "boolean", "required": false, "filterable": false, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionUpdate" } } } }, "responses": { "200": { "description": "The updated custom field definition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_table": "app.vendors", "field_key": "union_signatory", "label": "Union Signatory", "data_type": "boolean", "required": false, "filterable": false, "sort_order": 1 }, "schema": { "$ref": "#/components/schemas/CustomFieldDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "customFieldDefinitions.delete", "tags": ["Platform"], "x-xos-table": "app.custom_field_definitions", "x-xos-capability": "org.custom_fields.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a custom field definition", "description": "A custom field on a built-in resource. Soft-deletes the custom field definition: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom field definition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom field definition.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The custom field definition moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-field-values": { "get": { "operationId": "customFieldValues.list", "tags": ["Platform"], "x-xos-table": "app.custom_field_values", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List custom field value rows", "description": "A custom field value for one row. Returns a cursor page of custom field value rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of custom field value rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_field_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_text": true, "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_number": 12.5, "value_money_minor": 250000, "value_currency": "USD", "value_date": "2026-10-08", "value_timestamp": "2026-10-08T14:30:00Z", "value_boolean": true, "value_choice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CustomFieldValuePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "customFieldValues.create", "tags": ["Platform"], "x-xos-table": "app.custom_field_values", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a custom field value", "description": "A custom field value for one row. Creates a custom field value. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "custom_field_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_text": true, "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_number": 12.5, "value_money_minor": 250000, "value_currency": "USD", "value_date": "2026-10-08", "value_timestamp": "2026-10-08T14:30:00Z", "value_boolean": true, "value_choice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomFieldValueCreate" } } } }, "responses": { "201": { "description": "The created custom field value.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_field_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_text": true, "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_number": 12.5, "value_money_minor": 250000, "value_currency": "USD", "value_date": "2026-10-08", "value_timestamp": "2026-10-08T14:30:00Z", "value_boolean": true, "value_choice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomFieldValue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/custom-field-values/{id}": { "get": { "operationId": "customFieldValues.get", "tags": ["Platform"], "x-xos-table": "app.custom_field_values", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a custom field value", "description": "A custom field value for one row. Returns one custom field value with its `ETag`. A custom field value the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom field value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom field value.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The custom field value.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_field_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_text": true, "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_number": 12.5, "value_money_minor": 250000, "value_currency": "USD", "value_date": "2026-10-08", "value_timestamp": "2026-10-08T14:30:00Z", "value_boolean": true, "value_choice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomFieldValue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "customFieldValues.update", "tags": ["Platform"], "x-xos-table": "app.custom_field_values", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a custom field value", "description": "A custom field value for one row. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom field value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom field value.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "value_text": true, "value_number": 12.5, "value_money_minor": 250000, "value_currency": "USD", "value_date": "2026-10-08", "value_timestamp": "2026-10-08T14:30:00Z", "value_boolean": true, "value_choice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomFieldValueUpdate" } } } }, "responses": { "200": { "description": "The updated custom field value.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "custom_field_definition_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_text": true, "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_number": 12.5, "value_money_minor": 250000, "value_currency": "USD", "value_date": "2026-10-08", "value_timestamp": "2026-10-08T14:30:00Z", "value_boolean": true, "value_choice_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "value_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CustomFieldValue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "customFieldValues.delete", "tags": ["Platform"], "x-xos-table": "app.custom_field_values", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a custom field value", "description": "A custom field value for one row. Soft-deletes the custom field value: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the custom field value.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the custom field value.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The custom field value moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-state-labels": { "get": { "operationId": "orgStateLabels.list", "tags": ["Platform"], "x-xos-table": "app.org_state_labels", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List org state label rows", "description": "An org's display relabel of a record state. It never mints a new lifecycle. Returns a cursor page of org state label rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of org state label rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_state": "In Review", "label": "With Client" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrgStateLabelPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "orgStateLabels.create", "tags": ["Platform"], "x-xos-table": "app.org_state_labels", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an org state label", "description": "An org's display relabel of a record state. It never mints a new lifecycle. Creates an org state label. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "record_state": "In Review", "label": "With Client" }, "schema": { "$ref": "#/components/schemas/OrgStateLabelCreate" } } } }, "responses": { "201": { "description": "The created org state label.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_state": "In Review", "label": "With Client" }, "schema": { "$ref": "#/components/schemas/OrgStateLabel" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-state-labels/{id}": { "get": { "operationId": "orgStateLabels.get", "tags": ["Platform"], "x-xos-table": "app.org_state_labels", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an org state label", "description": "An org's display relabel of a record state. It never mints a new lifecycle. Returns one org state label with its `ETag`. A org state label the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org state label.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org state label.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The org state label.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_state": "In Review", "label": "With Client" }, "schema": { "$ref": "#/components/schemas/OrgStateLabel" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "orgStateLabels.update", "tags": ["Platform"], "x-xos-table": "app.org_state_labels", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an org state label", "description": "An org's display relabel of a record state. It never mints a new lifecycle. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org state label.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org state label.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "label": "With Client" }, "schema": { "$ref": "#/components/schemas/OrgStateLabelUpdate" } } } }, "responses": { "200": { "description": "The updated org state label.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_state": "In Review", "label": "With Client" }, "schema": { "$ref": "#/components/schemas/OrgStateLabel" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "orgStateLabels.delete", "tags": ["Platform"], "x-xos-table": "app.org_state_labels", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an org state label", "description": "An org's display relabel of a record state. It never mints a new lifecycle. Soft-deletes the org state label: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org state label.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org state label.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The org state label moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-jobs": { "get": { "operationId": "importJobs.list", "tags": ["Platform"], "x-xos-table": "app.import_jobs", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List import job rows", "description": "A spreadsheet import through detect, map, validate, deduplicate, dry run and commit. Returns a cursor page of import job rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of import job rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_mapping_profile_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_code": "vendors", "source": "CSV", "original_filename": "vendors-2026.xlsx", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/imports/vendors-2026.xlsx", "import_status": "Uploaded", "mapping_confirmed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ImportJobPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "importJobs.create", "tags": ["Platform"], "x-xos-table": "app.import_jobs", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Create an import job", "description": "A spreadsheet import through detect, map, validate, deduplicate, dry run and commit. Creates an import job. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "import_mapping_profile_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_code": "vendors", "source": "CSV", "original_filename": "vendors-2026.xlsx", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/imports/vendors-2026.xlsx" }, "schema": { "$ref": "#/components/schemas/ImportJobCreate" } } } }, "responses": { "201": { "description": "The created import job.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_mapping_profile_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_code": "vendors", "source": "CSV", "original_filename": "vendors-2026.xlsx", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/imports/vendors-2026.xlsx", "import_status": "Uploaded", "mapping_confirmed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-jobs/{id}": { "get": { "operationId": "importJobs.get", "tags": ["Platform"], "x-xos-table": "app.import_jobs", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an import job", "description": "A spreadsheet import through detect, map, validate, deduplicate, dry run and commit. Returns one import job with its `ETag`. A import job the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import job.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The import job.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_mapping_profile_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_code": "vendors", "source": "CSV", "original_filename": "vendors-2026.xlsx", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/imports/vendors-2026.xlsx", "import_status": "Uploaded", "mapping_confirmed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-jobs/{id}/dry-run": { "post": { "operationId": "importJobs.dryRun", "tags": ["Platform"], "x-xos-table": "app.import_jobs", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-rpc": "import_dry_run", "summary": "Dry-run an import", "description": "Counts what committing a validated import would write (app.import_dry_run): creates, strong key updates, merges a person chose, refusals and possible duplicates still pending. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import job.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "creates": 12, "updates": 3, "merges": 1, "refusals": 2, "skipped": 0, "pending_reviews": 0 }, "schema": { "$ref": "#/components/schemas/ImportDryRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-jobs/{id}/commit": { "post": { "operationId": "importJobs.commit", "tags": ["Platform"], "x-xos-table": "app.import_jobs", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Commit an import", "description": "Writes the validated rows in one import batch. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import job.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_mapping_profile_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "target_code": "vendors", "source": "CSV", "original_filename": "vendors-2026.xlsx", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/imports/vendors-2026.xlsx", "import_status": "Uploaded", "mapping_confirmed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-batches": { "get": { "operationId": "importBatches.list", "tags": ["Platform"], "x-xos-table": "app.import_batches", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List import batch rows", "description": "A committed import batch. It can be undone within 7 days unless later edits depend on it. Returns a cursor page of import batch rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of import batch rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_job_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "committed_at": "2026-10-08T14:30:00Z", "undone_at": "2026-10-08T14:30:00Z", "undo_reason": "Wrong sheet imported." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ImportBatchPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-batches/{id}": { "get": { "operationId": "importBatches.get", "tags": ["Platform"], "x-xos-table": "app.import_batches", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an import batch", "description": "A committed import batch. It can be undone within 7 days unless later edits depend on it. Returns one import batch with its `ETag`. A import batch the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import batch.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import batch.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The import batch.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_job_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "committed_at": "2026-10-08T14:30:00Z", "undone_at": "2026-10-08T14:30:00Z", "undo_reason": "Wrong sheet imported." }, "schema": { "$ref": "#/components/schemas/ImportBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-batches/{id}/undo": { "post": { "operationId": "importBatches.undo", "tags": ["Platform"], "x-xos-table": "app.import_batches", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Undo an import batch", "description": "Rolls back the batch within 7 days. Rows a later edit depends on are listed in a refusal instead of deleted. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import batch.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import batch.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_job_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "committed_at": "2026-10-08T14:30:00Z", "undone_at": "2026-10-08T14:30:00Z", "undo_reason": "Wrong sheet imported." }, "schema": { "$ref": "#/components/schemas/ImportBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-row-results": { "get": { "operationId": "importRowResults.list", "tags": ["Platform"], "x-xos-table": "app.import_row_results", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["id"], "numeric": false }, "summary": "List import row result rows", "description": "The validation result of one imported row, with a reason per cell. Returns a cursor page of import row result rows the caller may see. The default order is `id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of import row result rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_job_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "row_state": "Valid", "reason": "Unknown counterparty type.", "import_batch_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sheet_name": "Vendors", "row_number": 2, "target_table": "records", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "write_action": "Created", "before_image": { "type": "doc" }, "undo_outcome": "Reverted", "undo_reason": "Edited after the import." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ImportRowResultPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-row-results/{id}": { "get": { "operationId": "importRowResults.get", "tags": ["Platform"], "x-xos-table": "app.import_row_results", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an import row result", "description": "The validation result of one imported row, with a reason per cell. Returns one import row result with its `ETag`. A import row result the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import row result.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import row result.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The import row result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "import_job_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "row_state": "Valid", "reason": "Unknown counterparty type.", "import_batch_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "sheet_name": "Vendors", "row_number": 2, "target_table": "records", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "write_action": "Created", "before_image": { "type": "doc" }, "undo_outcome": "Reverted", "undo_reason": "Edited after the import." }, "schema": { "$ref": "#/components/schemas/ImportRowResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-mapping-profiles": { "get": { "operationId": "importMappingProfiles.list", "tags": ["Platform"], "x-xos-table": "app.import_mapping_profiles", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List import mapping profile rows", "description": "A saved column-to-field mapping for one-click repeat imports. Returns a cursor page of import mapping profile rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of import mapping profile rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Vendor List From Accounting", "target_code": "vendors" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ImportMappingProfilePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "importMappingProfiles.create", "tags": ["Platform"], "x-xos-table": "app.import_mapping_profiles", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Create an import mapping profile", "description": "A saved column-to-field mapping for one-click repeat imports. Creates an import mapping profile. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Vendor List From Accounting", "target_code": "vendors" }, "schema": { "$ref": "#/components/schemas/ImportMappingProfileCreate" } } } }, "responses": { "201": { "description": "The created import mapping profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Vendor List From Accounting", "target_code": "vendors" }, "schema": { "$ref": "#/components/schemas/ImportMappingProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/import-mapping-profiles/{id}": { "get": { "operationId": "importMappingProfiles.get", "tags": ["Platform"], "x-xos-table": "app.import_mapping_profiles", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an import mapping profile", "description": "A saved column-to-field mapping for one-click repeat imports. Returns one import mapping profile with its `ETag`. A import mapping profile the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import mapping profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import mapping profile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The import mapping profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Vendor List From Accounting", "target_code": "vendors" }, "schema": { "$ref": "#/components/schemas/ImportMappingProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "importMappingProfiles.update", "tags": ["Platform"], "x-xos-table": "app.import_mapping_profiles", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Update an import mapping profile", "description": "A saved column-to-field mapping for one-click repeat imports. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import mapping profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import mapping profile.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Vendor List From Accounting", "target_code": "vendors" }, "schema": { "$ref": "#/components/schemas/ImportMappingProfileUpdate" } } } }, "responses": { "200": { "description": "The updated import mapping profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Vendor List From Accounting", "target_code": "vendors" }, "schema": { "$ref": "#/components/schemas/ImportMappingProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "importMappingProfiles.delete", "tags": ["Platform"], "x-xos-table": "app.import_mapping_profiles", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Delete an import mapping profile", "description": "A saved column-to-field mapping for one-click repeat imports. Soft-deletes the import mapping profile: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the import mapping profile.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the import mapping profile.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The import mapping profile moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/merge-reviews": { "get": { "operationId": "mergeReviews.list", "tags": ["Platform"], "x-xos-table": "app.merge_reviews", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List merge review rows", "description": "A fuzzy duplicate awaiting review. Fuzzy matches never merge automatically. Returns a cursor page of merge review rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of merge review rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "similarity": 0.91, "decision": "Merge", "import_row_result_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "candidate_table": "records", "candidate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MergeReviewPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/merge-reviews/{id}": { "get": { "operationId": "mergeReviews.get", "tags": ["Platform"], "x-xos-table": "app.merge_reviews", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a merge review", "description": "A fuzzy duplicate awaiting review. Fuzzy matches never merge automatically. Returns one merge review with its `ETag`. A merge review the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the merge review.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the merge review.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The merge review.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "similarity": 0.91, "decision": "Merge", "import_row_result_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "candidate_table": "records", "candidate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/MergeReview" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "mergeReviews.update", "tags": ["Platform"], "x-xos-table": "app.merge_reviews", "x-xos-capability": "data.classification.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Update a merge review", "description": "A fuzzy duplicate awaiting review. Fuzzy matches never merge automatically. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the merge review.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the merge review.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "decision": "Merge" }, "schema": { "$ref": "#/components/schemas/MergeReviewUpdate" } } } }, "responses": { "200": { "description": "The updated merge review.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "similarity": 0.91, "decision": "Merge", "import_row_result_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "candidate_table": "records", "candidate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/MergeReview" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/export-jobs": { "get": { "operationId": "exportJobs.list", "tags": ["Platform"], "x-xos-table": "app.export_jobs", "x-xos-capability": "data.export.run", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List export job rows", "description": "An export of a list or report, subject to data loss prevention rules. Returns a cursor page of export job rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of export job rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_label": "urn:xpms:saved_view:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV", "classification": "Restricted", "watermark": false, "export_status": "Queued", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/exports/vendors.csv", "row_count": 120, "expires_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ExportJobPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "exportJobs.create", "tags": ["Platform"], "x-xos-table": "app.export_jobs", "x-xos-capability": "data.export.run", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Create an export job", "description": "An export of a list or report, subject to data loss prevention rules. Creates an export job. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "source_label": "urn:xpms:saved_view:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV", "columns": ["app.vendors.name"] }, "schema": { "$ref": "#/components/schemas/ExportJobCreate" } } } }, "responses": { "201": { "description": "The created export job.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_label": "urn:xpms:saved_view:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV", "classification": "Restricted", "watermark": false, "export_status": "Queued", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/exports/vendors.csv", "row_count": 120, "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ExportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/export-jobs/{id}": { "get": { "operationId": "exportJobs.get", "tags": ["Platform"], "x-xos-table": "app.export_jobs", "x-xos-capability": "data.export.run", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get an export job", "description": "An export of a list or report, subject to data loss prevention rules. Returns one export job with its `ETag`. A export job the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the export job.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the export job.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The export job.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source_label": "urn:xpms:saved_view:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "export_format": "CSV", "classification": "Restricted", "watermark": false, "export_status": "Queued", "storage_object_path": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/exports/vendors.csv", "row_count": 120, "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ExportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-views": { "get": { "operationId": "savedViews.list", "tags": ["Platform"], "x-xos-table": "app.saved_views", "x-xos-capability": "my_work.items.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["my_work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List saved view rows", "description": "A saved view of a collection: filters, sort, grouping and view type. Returns a cursor page of saved view rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of saved view rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Blocked Permits This Month", "view_type": "table", "shared": false, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "records", "group_by_field": "record_state" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SavedViewPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "savedViews.create", "tags": ["Platform"], "x-xos-table": "app.saved_views", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a saved view", "description": "A saved view of a collection: filters, sort, grouping and view type. Creates a saved view. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Blocked Permits This Month", "view_type": "table", "shared": false, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "records", "group_by_field": "record_state" }, "schema": { "$ref": "#/components/schemas/SavedViewCreate" } } } }, "responses": { "201": { "description": "The created saved view.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Blocked Permits This Month", "view_type": "table", "shared": false, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "records", "group_by_field": "record_state" }, "schema": { "$ref": "#/components/schemas/SavedView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-views/{id}": { "get": { "operationId": "savedViews.get", "tags": ["Platform"], "x-xos-table": "app.saved_views", "x-xos-capability": "my_work.items.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["my_work"] }], "summary": "Get a saved view", "description": "A saved view of a collection: filters, sort, grouping and view type. Returns one saved view with its `ETag`. A saved view the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved view.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The saved view.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Blocked Permits This Month", "view_type": "table", "shared": false, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "records", "group_by_field": "record_state" }, "schema": { "$ref": "#/components/schemas/SavedView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "savedViews.update", "tags": ["Platform"], "x-xos-table": "app.saved_views", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a saved view", "description": "A saved view of a collection: filters, sort, grouping and view type. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved view.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Blocked Permits This Month", "view_type": "table", "shared": false, "group_by_field": "record_state" }, "schema": { "$ref": "#/components/schemas/SavedViewUpdate" } } } }, "responses": { "200": { "description": "The updated saved view.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Blocked Permits This Month", "view_type": "table", "shared": false, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "records", "group_by_field": "record_state" }, "schema": { "$ref": "#/components/schemas/SavedView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "savedViews.delete", "tags": ["Platform"], "x-xos-table": "app.saved_views", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a saved view", "description": "A saved view of a collection: filters, sort, grouping and view type. Soft-deletes the saved view: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved view.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved view.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The saved view moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-policies": { "get": { "operationId": "approvalPolicies.list", "tags": ["Platform"], "x-xos-table": "app.approval_policies", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List approval policy rows", "description": "An approval policy with ordered steps. Returns a cursor page of approval policy rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of approval policy rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "PO Over Limit", "document_type": "Purchase Order", "description": "Every purchase order goes to finance.", "currency_code": "USD", "applies_above_minor": 1000000, "policy_state": "Active" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ApprovalPolicyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "approvalPolicies.create", "tags": ["Platform"], "x-xos-table": "app.approval_policies", "x-xos-capability": "org.approval_policies.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an approval policy", "description": "An approval policy with ordered steps. Creates an approval policy. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "PO Over Limit", "document_type": "Purchase Order", "description": "Every purchase order goes to finance.", "currency_code": "USD", "applies_above_minor": 1000000 }, "schema": { "$ref": "#/components/schemas/ApprovalPolicyCreate" } } } }, "responses": { "201": { "description": "The created approval policy.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "PO Over Limit", "document_type": "Purchase Order", "description": "Every purchase order goes to finance.", "currency_code": "USD", "applies_above_minor": 1000000, "policy_state": "Active" }, "schema": { "$ref": "#/components/schemas/ApprovalPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-policies/{id}": { "get": { "operationId": "approvalPolicies.get", "tags": ["Platform"], "x-xos-table": "app.approval_policies", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an approval policy", "description": "An approval policy with ordered steps. Returns one approval policy with its `ETag`. A approval policy the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval policy.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The approval policy.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "PO Over Limit", "document_type": "Purchase Order", "description": "Every purchase order goes to finance.", "currency_code": "USD", "applies_above_minor": 1000000, "policy_state": "Active" }, "schema": { "$ref": "#/components/schemas/ApprovalPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "approvalPolicies.update", "tags": ["Platform"], "x-xos-table": "app.approval_policies", "x-xos-capability": "org.approval_policies.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an approval policy", "description": "An approval policy with ordered steps. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval policy.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "PO Over Limit", "description": "Every purchase order goes to finance.", "currency_code": "USD", "applies_above_minor": 1000000 }, "schema": { "$ref": "#/components/schemas/ApprovalPolicyUpdate" } } } }, "responses": { "200": { "description": "The updated approval policy.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "PO Over Limit", "document_type": "Purchase Order", "description": "Every purchase order goes to finance.", "currency_code": "USD", "applies_above_minor": 1000000, "policy_state": "Active" }, "schema": { "$ref": "#/components/schemas/ApprovalPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "approvalPolicies.delete", "tags": ["Platform"], "x-xos-table": "app.approval_policies", "x-xos-capability": "org.approval_policies.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an approval policy", "description": "An approval policy with ordered steps. Soft-deletes the approval policy: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval policy.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The approval policy moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-policies/{id}/transitions": { "post": { "operationId": "approvalPolicies.transition", "tags": ["Platform"], "x-xos-table": "app.approval_policies", "x-xos-capability": "org.approval_policies.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "transition_approval_policy", "summary": "Activate or retire an approval policy", "description": "Moves a policy Draft to Active, Draft to Retired or Active to Retired with compare-and-set (app.transition_approval_policy). Activation needs a step (approval_policy_no_steps) and no other Active policy of the document type (approval_policy_active_exists). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval policy.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval policy.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Draft", "to_state": "Active", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/ApprovalPolicyTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "PO Over Limit", "document_type": "Purchase Order", "description": "Every purchase order goes to finance.", "currency_code": "USD", "applies_above_minor": 1000000, "policy_state": "Active" }, "schema": { "$ref": "#/components/schemas/ApprovalPolicy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-instances": { "get": { "operationId": "approvalInstances.list", "tags": ["Platform"], "x-xos-table": "app.approval_instances", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List approval instance rows", "description": "An approval in flight for one subject. Returns a cursor page of approval instance rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of approval instance rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_state": "In Review", "document_type": "Purchase Order", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "purchase_orders", "subject_reference": "17", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 4000000, "currency_code": "USD", "current_step": 1, "decided_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ApprovalInstancePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "approvalInstances.create", "tags": ["Platform"], "x-xos-table": "app.approval_instances", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Create an approval instance", "description": "An approval in flight for one subject. Creates an approval instance. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "document_type": "Purchase Order", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApprovalInstanceCreate" } } } }, "responses": { "201": { "description": "The created approval instance.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_state": "In Review", "document_type": "Purchase Order", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "purchase_orders", "subject_reference": "17", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 4000000, "currency_code": "USD", "current_step": 1, "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ApprovalInstance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-instances/{id}": { "get": { "operationId": "approvalInstances.get", "tags": ["Platform"], "x-xos-table": "app.approval_instances", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get an approval instance", "description": "An approval in flight for one subject. Returns one approval instance with its `ETag`. A approval instance the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval instance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval instance.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The approval instance.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_state": "In Review", "document_type": "Purchase Order", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "purchase_orders", "subject_reference": "17", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 4000000, "currency_code": "USD", "current_step": 1, "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ApprovalInstance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-instances/{id}/cancel": { "post": { "operationId": "approvalInstances.cancel", "tags": ["Platform"], "x-xos-table": "app.approval_instances", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "cancel_approval", "summary": "Withdraw an approval", "description": "Withdraws an approval in review, or an Approved one the document has not used (app.cancel_approval): the requester, when approvals.requester_may_cancel allows it (approval_requester_cancel_off: 422), or a holder of org.approval_policies.write. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval instance.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval instance.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Submitted against the wrong order." }, "schema": { "$ref": "#/components/schemas/ApprovalCancelRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_state": "In Review", "document_type": "Purchase Order", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "purchase_orders", "subject_reference": "17", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "amount_minor": 4000000, "currency_code": "USD", "current_step": 1, "decided_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ApprovalInstance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-decisions": { "get": { "operationId": "approvalDecisions.list", "tags": ["Platform"], "x-xos-table": "app.approval_decisions", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List approval decision rows", "description": "A decision by an eligible approver, never the requester. Returns a cursor page of approval decision rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of approval decision rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_instance_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved": true, "comment": "Within budget.", "approver_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "step_order": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ApprovalDecisionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "approvalDecisions.create", "tags": ["Platform"], "x-xos-table": "app.approval_decisions", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Create an approval decision", "description": "A decision by an eligible approver, never the requester. Creates an approval decision. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "approval_instance_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved": true, "comment": "Within budget." }, "schema": { "$ref": "#/components/schemas/ApprovalDecisionCreate" } } } }, "responses": { "201": { "description": "The created approval decision.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_instance_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved": true, "comment": "Within budget.", "approver_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "step_order": 1 }, "schema": { "$ref": "#/components/schemas/ApprovalDecision" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-decisions/{id}": { "get": { "operationId": "approvalDecisions.get", "tags": ["Platform"], "x-xos-table": "app.approval_decisions", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get an approval decision", "description": "A decision by an eligible approver, never the requester. Returns one approval decision with its `ETag`. A approval decision the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval decision.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval decision.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The approval decision.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_instance_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approved": true, "comment": "Within budget.", "approver_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "step_order": 1 }, "schema": { "$ref": "#/components/schemas/ApprovalDecision" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/comment-threads": { "get": { "operationId": "commentThreads.list", "tags": ["Platform"], "x-xos-table": "app.comment_threads", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List comment thread rows", "description": "A comment thread on any record. Returns a cursor page of comment thread rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of comment thread rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "anchor": "line:12", "resolved_at": "2026-10-08T14:30:00Z", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CommentThreadPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "commentThreads.create", "tags": ["Platform"], "x-xos-table": "app.comment_threads", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a comment thread", "description": "A comment thread on any record. Creates a comment thread. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "anchor": "line:12" }, "schema": { "$ref": "#/components/schemas/CommentThreadCreate" } } } }, "responses": { "201": { "description": "The created comment thread.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "anchor": "line:12", "resolved_at": "2026-10-08T14:30:00Z", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CommentThread" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/comment-threads/{id}": { "get": { "operationId": "commentThreads.get", "tags": ["Platform"], "x-xos-table": "app.comment_threads", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a comment thread", "description": "A comment thread on any record. Returns one comment thread with its `ETag`. A comment thread the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the comment thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the comment thread.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The comment thread.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "anchor": "line:12", "resolved_at": "2026-10-08T14:30:00Z", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CommentThread" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "commentThreads.update", "tags": ["Platform"], "x-xos-table": "app.comment_threads", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a comment thread", "description": "A comment thread on any record. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the comment thread.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the comment thread.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "anchor": "line:12", "resolved_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/CommentThreadUpdate" } } } }, "responses": { "200": { "description": "The updated comment thread.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "anchor": "line:12", "resolved_at": "2026-10-08T14:30:00Z", "resolved_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CommentThread" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/comments": { "get": { "operationId": "comments.list", "tags": ["Platform"], "x-xos-table": "app.comments", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List comment rows", "description": "A comment in a thread. Returns a cursor page of comment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of comment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "comment_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Load-in moved to 07:00.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "App", "edited_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CommentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "comments.create", "tags": ["Platform"], "x-xos-table": "app.comments", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Create a comment", "description": "A comment in a thread. Creates a comment. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "comment_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Load-in moved to 07:00.", "source": "App" }, "schema": { "$ref": "#/components/schemas/CommentCreate" } } } }, "responses": { "201": { "description": "The created comment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "comment_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Load-in moved to 07:00.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "App", "edited_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/comments/{id}": { "get": { "operationId": "comments.get", "tags": ["Platform"], "x-xos-table": "app.comments", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Get a comment", "description": "A comment in a thread. Returns one comment with its `ETag`. A comment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the comment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the comment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The comment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "comment_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Load-in moved to 07:00.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "App", "edited_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "comments.update", "tags": ["Platform"], "x-xos-table": "app.comments", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Update a comment", "description": "A comment in a thread. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the comment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the comment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "body": "Load-in moved to 07:00.", "source": "App" }, "schema": { "$ref": "#/components/schemas/CommentUpdate" } } } }, "responses": { "200": { "description": "The updated comment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "comment_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Load-in moved to 07:00.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "App", "edited_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "comments.delete", "tags": ["Platform"], "x-xos-table": "app.comments", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "summary": "Delete a comment", "description": "A comment in a thread. Soft-deletes the comment: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the comment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the comment.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The comment moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/comments/on-subject": { "post": { "operationId": "comments.postOnSubject", "tags": ["Platform"], "x-xos-table": "app.comments", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-rpc": "post_comment", "summary": "Comment on a subject", "description": "Posts a comment on any row of app.comment_subjects by its table and id, as the caller, in the subject's main thread or the thread of an anchor, opening the thread on first use (`app.post_comment`). The subject's own read policy decides (404 when it is not visible). The add_comment action of automations calls it as the automation's owner. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Picked up, thanks.", "anchor": "line:12" }, "schema": { "$ref": "#/components/schemas/SubjectCommentRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "comment_thread_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Load-in moved to 07:00.", "author_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "source": "App", "edited_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notifications": { "get": { "operationId": "notifications.list", "tags": ["Platform"], "x-xos-table": "app.notifications", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List notification rows", "description": "A notification for the caller. Returns a cursor page of notification rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of notification rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "kind": "timesheet.approved", "recipient_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "read_at": "2026-10-08T14:30:00Z", "actor_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_args": { "type": "doc" }, "archived_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/NotificationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notifications/{id}": { "get": { "operationId": "notifications.get", "tags": ["Platform"], "x-xos-table": "app.notifications", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a notification", "description": "A notification for the caller. Returns one notification with its `ETag`. A notification the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the notification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the notification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The notification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "kind": "timesheet.approved", "recipient_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "read_at": "2026-10-08T14:30:00Z", "actor_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_args": { "type": "doc" }, "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "notifications.update", "tags": ["Platform"], "x-xos-table": "app.notifications", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Update a notification", "description": "A notification for the caller. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the notification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the notification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "read_at": "2026-10-08T14:30:00Z", "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/NotificationUpdate" } } } }, "responses": { "200": { "description": "The updated notification.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "kind": "timesheet.approved", "recipient_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "read_at": "2026-10-08T14:30:00Z", "actor_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_args": { "type": "doc" }, "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notifications/mark-all-read": { "post": { "operationId": "notifications.markAllRead", "tags": ["Platform"], "x-xos-table": "app.notifications", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Mark all notifications read", "description": "Marks every unread notification of the caller as read. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "updated_count": 12 }, "schema": { "$ref": "#/components/schemas/MarkAllReadResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notifications/{id}/act": { "post": { "operationId": "notifications.act", "tags": ["Platform"], "x-xos-table": "app.notifications", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "act_on_notification", "summary": "Act on a notification", "description": "Acts where the notification arrived, without opening its record (app.act_on_notification): approve or reject the approval an approval request asks for (app.decide_approval decides every rule; a rejection needs a comment), or mark it Done. Only the recipient acts. Push notification action buttons call this operation. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the notification.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the notification.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "action": "approve", "comment": "Over the stage budget." }, "schema": { "$ref": "#/components/schemas/NotificationActRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "kind": "timesheet.approved", "recipient_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "read_at": "2026-10-08T14:30:00Z", "actor_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "records", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_args": { "type": "doc" }, "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notification-preferences": { "get": { "operationId": "notificationPreferences.list", "tags": ["Platform"], "x-xos-table": "app.notification_preferences", "x-xos-capability": "me.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List notification preference rows", "description": "A per-kind, per-channel notification preference. Returns a cursor page of notification preference rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of notification preference rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "channel": "In App", "enabled": true, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category_code": "approvals" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/NotificationPreferencePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "notificationPreferences.create", "tags": ["Platform"], "x-xos-table": "app.notification_preferences", "x-xos-capability": "me.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a notification preference", "description": "A per-kind, per-channel notification preference. Creates a notification preference. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "channel": "In App", "enabled": true, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category_code": "approvals" }, "schema": { "$ref": "#/components/schemas/NotificationPreferenceCreate" } } } }, "responses": { "201": { "description": "The created notification preference.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "channel": "In App", "enabled": true, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category_code": "approvals" }, "schema": { "$ref": "#/components/schemas/NotificationPreference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notification-preferences/{id}": { "get": { "operationId": "notificationPreferences.get", "tags": ["Platform"], "x-xos-table": "app.notification_preferences", "x-xos-capability": "me.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a notification preference", "description": "A per-kind, per-channel notification preference. Returns one notification preference with its `ETag`. A notification preference the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the notification preference.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the notification preference.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The notification preference.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "channel": "In App", "enabled": true, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category_code": "approvals" }, "schema": { "$ref": "#/components/schemas/NotificationPreference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "notificationPreferences.update", "tags": ["Platform"], "x-xos-table": "app.notification_preferences", "x-xos-capability": "me.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a notification preference", "description": "A per-kind, per-channel notification preference. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the notification preference.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the notification preference.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "enabled": true }, "schema": { "$ref": "#/components/schemas/NotificationPreferenceUpdate" } } } }, "responses": { "200": { "description": "The updated notification preference.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "channel": "In App", "enabled": true, "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category_code": "approvals" }, "schema": { "$ref": "#/components/schemas/NotificationPreference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calendar-feeds": { "get": { "operationId": "calendarFeeds.list", "tags": ["Platform"], "x-xos-table": "app.calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List calendar feed rows", "description": "An iCalendar feed. The token is shown once, stored hashed and revocable. Returns a cursor page of calendar feed rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of calendar feed rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "revoked_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "last_accessed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CalendarFeedPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "calendarFeeds.create", "tags": ["Platform"], "x-xos-table": "app.calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.create_calendar_feed", "summary": "Create a calendar feed", "description": "Creates an iCalendar feed of the caller's schedule, optionally for one project, through `app.create_calendar_feed`. The token of the subscription URL is returned once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/CalendarFeedCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "calendar_feed_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feed_token": "cal_9fQ2mX4vT7kL1pR8" }, "schema": { "$ref": "#/components/schemas/CalendarFeedToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calendar-feeds/{id}": { "get": { "operationId": "calendarFeeds.get", "tags": ["Platform"], "x-xos-table": "app.calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a calendar feed", "description": "An iCalendar feed. The token is shown once, stored hashed and revocable. Returns one calendar feed with its `ETag`. A calendar feed the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the calendar feed.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The calendar feed.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "revoked_at": "2026-10-08T14:30:00Z", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "last_accessed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/CalendarFeed" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "calendarFeeds.delete", "tags": ["Platform"], "x-xos-table": "app.calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a calendar feed", "description": "An iCalendar feed. The token is shown once, stored hashed and revocable. Soft-deletes the calendar feed: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the calendar feed.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The calendar feed moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calendar-feeds/{id}/rotate": { "post": { "operationId": "calendarFeeds.rotate", "tags": ["Platform"], "x-xos-table": "app.calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.rotate_calendar_feed", "summary": "Get a new link for a calendar feed", "description": "Replaces the token of one of the caller's feeds (app.rotate_calendar_feed) and returns the new one once. The old subscription URL answers 404 at once; a revoked feed is not found. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the calendar feed.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "calendar_feed_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feed_token": "cal_9fQ2mX4vT7kL1pR8" }, "schema": { "$ref": "#/components/schemas/CalendarFeedToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/trash": { "get": { "operationId": "trashItems.list", "tags": ["Platform"], "x-xos-table": "app.trash_items", "x-xos-capability": "work.record.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-order": { "by": ["deleted_at"], "numeric": false }, "summary": "List trash item rows", "description": "A soft-deleted row, restorable for its table's retention period. A view, not a copy. Returns a cursor page of trash item rows the caller may see. The default order is `deleted_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of trash item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "subject_urn": "urn:xpms:record:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "deleted_at": "2026-10-08T14:30:00Z", "purge_after": "2026-10-08T14:30:00Z", "subject_table": "budgets", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Summer Series Budget", "deleted_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TrashItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/trash/restore": { "post": { "operationId": "trashItems.restore", "tags": ["Platform"], "x-xos-table": "app.trash_items", "x-xos-capability": "work.record.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["work"] }], "x-xos-rpc": "restore_trash_item", "summary": "Restore a deleted item", "description": "Restores a soft-deleted row within its retention period, as the caller (app.restore_trash_item): the table's own update rules decide. Rows that reference it and were deleted with it come back too. A row past retention answers 422 (trash_restore_expired), a live row 422 (trash_not_deleted). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "subject_urn": "urn:xpms:record:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/RestoreRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "subject_urn": "urn:xpms:budgets:0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject_table": "budgets", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "rows_restored": 2 }, "schema": { "$ref": "#/components/schemas/TrashRestoreResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates": { "get": { "operationId": "templates.list", "tags": ["Platform"], "x-xos-table": "app.templates", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List template rows", "description": "A project or record template, including the XOS 4.0 Production Template copy. Returns a cursor page of template rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of template rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Three-Day Festival", "current_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Outdoor weekend shows.", "template_kind": "Project" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TemplatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "templates.create", "tags": ["Platform"], "x-xos-table": "app.templates", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a template", "description": "A project or record template, including the XOS 4.0 Production Template copy. Creates a template. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Three-Day Festival", "description": "Outdoor weekend shows.", "template_kind": "Project" }, "schema": { "$ref": "#/components/schemas/TemplateCreate" } } } }, "responses": { "201": { "description": "The created template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Three-Day Festival", "current_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Outdoor weekend shows.", "template_kind": "Project" }, "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/{id}": { "get": { "operationId": "templates.get", "tags": ["Platform"], "x-xos-table": "app.templates", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a template", "description": "A project or record template, including the XOS 4.0 Production Template copy. Returns one template with its `ETag`. A template the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Three-Day Festival", "current_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Outdoor weekend shows.", "template_kind": "Project" }, "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "templates.update", "tags": ["Platform"], "x-xos-table": "app.templates", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a template", "description": "A project or record template, including the XOS 4.0 Production Template copy. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Three-Day Festival", "description": "Outdoor weekend shows.", "template_kind": "Project" }, "schema": { "$ref": "#/components/schemas/TemplateUpdate" } } } }, "responses": { "200": { "description": "The updated template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Three-Day Festival", "current_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Outdoor weekend shows.", "template_kind": "Project" }, "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "templates.delete", "tags": ["Platform"], "x-xos-table": "app.templates", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a template", "description": "A project or record template, including the XOS 4.0 Production Template copy. Soft-deletes the template: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The template moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/from-project": { "post": { "operationId": "templates.createFromProject", "tags": ["Platform"], "x-xos-table": "app.templates", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-rpc": "create_template_from_project", "summary": "Save a project as a template", "description": "Creates a template from a project as the caller (app.create_template_from_project): its defaults, show and standing venue scope nodes and open records become a published first version. Needs projects.template.write. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Three-Day Festival", "description": "Outdoor weekend shows." }, "schema": { "$ref": "#/components/schemas/TemplateFromProjectRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Three-Day Festival", "current_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Outdoor weekend shows.", "template_kind": "Project" }, "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/template-applications": { "get": { "operationId": "templateApplications.list", "tags": ["Platform"], "x-xos-table": "app.template_applications", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List template application rows", "description": "A template applied to create a project and its records. Returns a cursor page of template application rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of template application rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_nodes_created": 1, "records_created": 4 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TemplateApplicationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "templateApplications.create", "tags": ["Platform"], "x-xos-table": "app.template_applications", "x-xos-capability": "projects.project.create", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a template application", "description": "A template applied to create a project and its records. Creates a template application. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_key": "NWT", "name": "Tidewater Weekend", "time_zone": "America/New_York", "starts_on": "2026-10-08", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TemplateApplicationCreate" } } } }, "responses": { "201": { "description": "The created template application.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_nodes_created": 1, "records_created": 4 }, "schema": { "$ref": "#/components/schemas/TemplateApplication" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/template-applications/{id}": { "get": { "operationId": "templateApplications.get", "tags": ["Platform"], "x-xos-table": "app.template_applications", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a template application", "description": "A template applied to create a project and its records. Returns one template application with its `ETag`. A template application the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template application.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template application.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The template application.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_nodes_created": 1, "records_created": 4 }, "schema": { "$ref": "#/components/schemas/TemplateApplication" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-authorities": { "get": { "operationId": "projectAuthorities.list", "tags": ["Projects"], "x-xos-table": "app.project_authority", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["project_id", "service", "agency"], "numeric": false }, "summary": "List project authority rows", "description": "An authority having jurisdiction over a project: a responder agency of the jurisdiction of the project's venue (xpms.jurisdiction_agency), one row per service and agency. A project without a venue has none. Returns a cursor page of project authority rows the caller may see. The default order is `project_id`, then `service`, then `agency` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project authority rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "service": "fire", "agency": "Miami-Dade Fire Rescue", "contact": "911" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectAuthorityPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/measurement-metrics": { "get": { "operationId": "measurementMetrics.list", "tags": ["Projects"], "x-xos-table": "app.measurement_metrics", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["ordinal"], "numeric": false }, "summary": "List measurement metric rows", "description": "A figure a project measures against its gate 1 objectives (Section 4.10): sustainability, audience, earned media or sentiment. Canon's metric table holds reference values, so each metric names the canon metric that benchmarks it where canon states one. Returns a cursor page of measurement metric rows the caller may see. The default order is `ordinal` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of measurement metric rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "metric_code": "waste_generated", "family": "Sustainability", "dimension": "Mass", "base_unit_code": "kg", "aggregation": "Sum", "is_derived": false, "lower_bound": 0, "upper_bound": 100, "canon_domain": "site_services", "canon_item": "Waste lbs per guest per day", "canon_value_numeric": 2.4, "canon_value_text": "1.9 kW continuous", "canon_qualifier": "MODELED event avg", "ordinal": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MeasurementMetricPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/measurement-units": { "get": { "operationId": "measurementUnits.list", "tags": ["Projects"], "x-xos-table": "app.measurement_units", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["ordinal"], "numeric": false }, "summary": "List measurement unit rows", "description": "A unit a figure or objective is entered in, with its exact factor to the base unit of its dimension and whether reports show the dimension in it for metric or imperial readers. Returns a cursor page of measurement unit rows the caller may see. The default order is `ordinal` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of measurement unit rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "unit_code": "kg", "dimension": "Mass", "factor_to_base": 0.45359237, "unit_system": "Imperial", "is_display": true, "ordinal": 3 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MeasurementUnitPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/measurement-metric-tags": { "get": { "operationId": "measurementMetricTags.list", "tags": ["Projects"], "x-xos-table": "app.measurement_metric_tags", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["metric_code", "tag_id"], "numeric": false }, "summary": "List measurement metric tag rows", "description": "A Bible sustainability tag (Bible tab 09) a sustainability figure is reported against (Section 4.10). Returns a cursor page of measurement metric tag rows the caller may see. The default order is `metric_code`, then `tag_id` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of measurement metric tag rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "metric_code": "waste_generated", "tag_id": "TAG-005", "tag": "REUSABLE" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/MeasurementMetricTagPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-objectives": { "get": { "operationId": "projectObjectives.list", "tags": ["Projects"], "x-xos-table": "app.project_objectives", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project objective rows", "description": "A measurable objective recorded at gate 1 (canon criterion G1.OBJECTIVES_STATED): one target per metric and project, which gate 8 measures against. Once gate 1 is passed only a gate approver (projects.gate.transition) sets, changes or withdraws one; every change is in the audit ledger. Returns a cursor page of project objective rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project objective rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "direction": "At Most", "target_value": 2, "unit_code": "kg", "note": "Two roll-off containers." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectObjectivePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "projectObjectives.create", "tags": ["Projects"], "x-xos-table": "app.project_objectives", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a project objective", "description": "A measurable objective recorded at gate 1 (canon criterion G1.OBJECTIVES_STATED): one target per metric and project, which gate 8 measures against. Once gate 1 is passed only a gate approver (projects.gate.transition) sets, changes or withdraws one; every change is in the audit ledger. Creates a project objective. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "direction": "At Most", "target_value": 2, "unit_code": "kg", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectObjectiveCreate" } } } }, "responses": { "201": { "description": "The created project objective.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "direction": "At Most", "target_value": 2, "unit_code": "kg", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectObjective" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-objectives/{id}": { "get": { "operationId": "projectObjectives.get", "tags": ["Projects"], "x-xos-table": "app.project_objectives", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project objective", "description": "A measurable objective recorded at gate 1 (canon criterion G1.OBJECTIVES_STATED): one target per metric and project, which gate 8 measures against. Once gate 1 is passed only a gate approver (projects.gate.transition) sets, changes or withdraws one; every change is in the audit ledger. Returns one project objective with its `ETag`. A project objective the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project objective.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project objective.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project objective.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "direction": "At Most", "target_value": 2, "unit_code": "kg", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectObjective" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "projectObjectives.update", "tags": ["Projects"], "x-xos-table": "app.project_objectives", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a project objective", "description": "A measurable objective recorded at gate 1 (canon criterion G1.OBJECTIVES_STATED): one target per metric and project, which gate 8 measures against. Once gate 1 is passed only a gate approver (projects.gate.transition) sets, changes or withdraws one; every change is in the audit ledger. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project objective.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project objective.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "direction": "At Most", "target_value": 2, "unit_code": "kg", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectObjectiveUpdate" } } } }, "responses": { "200": { "description": "The updated project objective.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "direction": "At Most", "target_value": 2, "unit_code": "kg", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectObjective" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "projectObjectives.delete", "tags": ["Projects"], "x-xos-table": "app.project_objectives", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a project objective", "description": "A measurable objective recorded at gate 1 (canon criterion G1.OBJECTIVES_STATED): one target per metric and project, which gate 8 measures against. Once gate 1 is passed only a gate approver (projects.gate.transition) sets, changes or withdraws one; every change is in the audit ledger. Soft-deletes the project objective: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project objective.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project objective.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The project objective moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-measurements": { "get": { "operationId": "projectMeasurements.list", "tags": ["Projects"], "x-xos-table": "app.project_measurements", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project measurement rows", "description": "A figure measured on a project (Section 4.10) for one metric, day and source. A null value records that the figure was not measured (Unmeasured), never zero. Correcting the value, unit or day needs correction_reason and writes the change to the correction ledger. Who recorded it and when are created_by and created_at. Returns a cursor page of project measurement rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project measurement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "measured_on": "2026-10-08", "value": 1200, "unit_code": "kg", "source": "Import", "source_reference": "Hauler invoice 4471", "source_uri": "https://hauler.example/invoices/4471", "note": "Two roll-off containers." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectMeasurementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "projectMeasurements.create", "tags": ["Projects"], "x-xos-table": "app.project_measurements", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a project measurement", "description": "A figure measured on a project (Section 4.10) for one metric, day and source. A null value records that the figure was not measured (Unmeasured), never zero. Correcting the value, unit or day needs correction_reason and writes the change to the correction ledger. Who recorded it and when are created_by and created_at. Creates a project measurement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "measured_on": "2026-10-08", "value": 1200, "unit_code": "kg", "source": "Import", "source_reference": "Hauler invoice 4471", "source_uri": "https://hauler.example/invoices/4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectMeasurementCreate" } } } }, "responses": { "201": { "description": "The created project measurement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "measured_on": "2026-10-08", "value": 1200, "unit_code": "kg", "source": "Import", "source_reference": "Hauler invoice 4471", "source_uri": "https://hauler.example/invoices/4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectMeasurement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-measurements/{id}": { "get": { "operationId": "projectMeasurements.get", "tags": ["Projects"], "x-xos-table": "app.project_measurements", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project measurement", "description": "A figure measured on a project (Section 4.10) for one metric, day and source. A null value records that the figure was not measured (Unmeasured), never zero. Correcting the value, unit or day needs correction_reason and writes the change to the correction ledger. Who recorded it and when are created_by and created_at. Returns one project measurement with its `ETag`. A project measurement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project measurement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project measurement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project measurement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "measured_on": "2026-10-08", "value": 1200, "unit_code": "kg", "source": "Import", "source_reference": "Hauler invoice 4471", "source_uri": "https://hauler.example/invoices/4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectMeasurement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "projectMeasurements.update", "tags": ["Projects"], "x-xos-table": "app.project_measurements", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a project measurement", "description": "A figure measured on a project (Section 4.10) for one metric, day and source. A null value records that the figure was not measured (Unmeasured), never zero. Correcting the value, unit or day needs correction_reason and writes the change to the correction ledger. Who recorded it and when are created_by and created_at. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project measurement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project measurement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "measured_on": "2026-10-08", "value": 1200, "unit_code": "kg", "source_reference": "Hauler invoice 4471", "source_uri": "https://hauler.example/invoices/4471", "note": "Two roll-off containers.", "correction_reason": "Weighbridge ticket supersedes the estimate." }, "schema": { "$ref": "#/components/schemas/ProjectMeasurementUpdate" } } } }, "responses": { "200": { "description": "The updated project measurement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "measured_on": "2026-10-08", "value": 1200, "unit_code": "kg", "source": "Import", "source_reference": "Hauler invoice 4471", "source_uri": "https://hauler.example/invoices/4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/ProjectMeasurement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "projectMeasurements.delete", "tags": ["Projects"], "x-xos-table": "app.project_measurements", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a project measurement", "description": "A figure measured on a project (Section 4.10) for one metric, day and source. A null value records that the figure was not measured (Unmeasured), never zero. Correcting the value, unit or day needs correction_reason and writes the change to the correction ledger. Who recorded it and when are created_by and created_at. Soft-deletes the project measurement: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project measurement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project measurement.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The project measurement moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-measurement-corrections": { "get": { "operationId": "projectMeasurementCorrections.list", "tags": ["Projects"], "x-xos-table": "app.project_measurement_corrections", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project measurement correction rows", "description": "An entry of the append-only correction ledger: a figure corrected, withdrawn or restored, with the figure before and after and the reason. Who changed it and when are created_by and created_at. Returns a cursor page of project measurement correction rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project measurement correction rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_measurement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "correction_kind": "Corrected", "previous_value": 1200, "previous_unit_code": "kg", "previous_measured_on": "2026-10-08", "value": 1.25, "unit_code": "kg", "measured_on": "2026-10-08", "reason": "Weighbridge ticket supersedes the estimate." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectMeasurementCorrectionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-measurement-corrections/{id}": { "get": { "operationId": "projectMeasurementCorrections.get", "tags": ["Projects"], "x-xos-table": "app.project_measurement_corrections", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project measurement correction", "description": "An entry of the append-only correction ledger: a figure corrected, withdrawn or restored, with the figure before and after and the reason. Who changed it and when are created_by and created_at. Returns one project measurement correction with its `ETag`. A project measurement correction the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project measurement correction.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project measurement correction.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project measurement correction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_measurement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "correction_kind": "Corrected", "previous_value": 1200, "previous_unit_code": "kg", "previous_measured_on": "2026-10-08", "value": 1.25, "unit_code": "kg", "measured_on": "2026-10-08", "reason": "Weighbridge ticket supersedes the estimate." }, "schema": { "$ref": "#/components/schemas/ProjectMeasurementCorrection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/earned-media-items": { "get": { "operationId": "earnedMediaItems.list", "tags": ["Projects"], "x-xos-table": "app.earned_media_items", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List earned media item rows", "description": "A piece of earned media coverage of a project (gate 8, G8.MEASUREMENT_REPORTED), sourced, dated and linked. The earned media figures of the measurement summary are computed from these rows. A reach the source does not report is null (Unmeasured); a tone is null until rated. Returns a cursor page of earned media item rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of earned media item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Summer Series opens on the pier", "outlet": "WLRN", "medium": "Broadcast", "published_on": "2026-10-08", "url": "https://northwindlive.example/files/site-plan.pdf", "reach": 120000, "tone": "Positive", "source": "Import", "source_reference": "Hauler invoice 4471", "note": "Two roll-off containers." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EarnedMediaItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "earnedMediaItems.create", "tags": ["Projects"], "x-xos-table": "app.earned_media_items", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create an earned media item", "description": "A piece of earned media coverage of a project (gate 8, G8.MEASUREMENT_REPORTED), sourced, dated and linked. The earned media figures of the measurement summary are computed from these rows. A reach the source does not report is null (Unmeasured); a tone is null until rated. Creates an earned media item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Summer Series opens on the pier", "outlet": "WLRN", "medium": "Broadcast", "published_on": "2026-10-08", "url": "https://northwindlive.example/files/site-plan.pdf", "reach": 120000, "tone": "Positive", "source": "Import", "source_reference": "Hauler invoice 4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/EarnedMediaItemCreate" } } } }, "responses": { "201": { "description": "The created earned media item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Summer Series opens on the pier", "outlet": "WLRN", "medium": "Broadcast", "published_on": "2026-10-08", "url": "https://northwindlive.example/files/site-plan.pdf", "reach": 120000, "tone": "Positive", "source": "Import", "source_reference": "Hauler invoice 4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/EarnedMediaItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/earned-media-items/{id}": { "get": { "operationId": "earnedMediaItems.get", "tags": ["Projects"], "x-xos-table": "app.earned_media_items", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get an earned media item", "description": "A piece of earned media coverage of a project (gate 8, G8.MEASUREMENT_REPORTED), sourced, dated and linked. The earned media figures of the measurement summary are computed from these rows. A reach the source does not report is null (Unmeasured); a tone is null until rated. Returns one earned media item with its `ETag`. A earned media item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the earned media item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the earned media item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The earned media item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Summer Series opens on the pier", "outlet": "WLRN", "medium": "Broadcast", "published_on": "2026-10-08", "url": "https://northwindlive.example/files/site-plan.pdf", "reach": 120000, "tone": "Positive", "source": "Import", "source_reference": "Hauler invoice 4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/EarnedMediaItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "earnedMediaItems.update", "tags": ["Projects"], "x-xos-table": "app.earned_media_items", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update an earned media item", "description": "A piece of earned media coverage of a project (gate 8, G8.MEASUREMENT_REPORTED), sourced, dated and linked. The earned media figures of the measurement summary are computed from these rows. A reach the source does not report is null (Unmeasured); a tone is null until rated. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the earned media item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the earned media item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Summer Series opens on the pier", "outlet": "WLRN", "medium": "Broadcast", "published_on": "2026-10-08", "url": "https://northwindlive.example/files/site-plan.pdf", "reach": 120000, "tone": "Positive", "source": "Import", "source_reference": "Hauler invoice 4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/EarnedMediaItemUpdate" } } } }, "responses": { "200": { "description": "The updated earned media item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Summer Series opens on the pier", "outlet": "WLRN", "medium": "Broadcast", "published_on": "2026-10-08", "url": "https://northwindlive.example/files/site-plan.pdf", "reach": 120000, "tone": "Positive", "source": "Import", "source_reference": "Hauler invoice 4471", "note": "Two roll-off containers." }, "schema": { "$ref": "#/components/schemas/EarnedMediaItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "earnedMediaItems.delete", "tags": ["Projects"], "x-xos-table": "app.earned_media_items", "x-xos-capability": "projects.gate.evidence.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete an earned media item", "description": "A piece of earned media coverage of a project (gate 8, G8.MEASUREMENT_REPORTED), sourced, dated and linked. The earned media figures of the measurement summary are computed from these rows. A reach the source does not report is null (Unmeasured); a tone is null until rated. Soft-deletes the earned media item: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the earned media item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the earned media item.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The earned media item moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-measurement-summary": { "get": { "operationId": "projectMeasurementSummary.list", "tags": ["Projects"], "x-xos-table": "app.project_measurement_summary", "x-xos-capability": "projects.gate.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["project_id", "metric_code"], "numeric": false }, "summary": "List project measurement summary row rows", "description": "Gate 8 measurement against the gate 1 objectives, per project and metric, in the metric's base unit. Totals cover measured figures only, with the unmeasured count beside them; with nothing measured the figure is null (Unmeasured), never zero. Returns a cursor page of project measurement summary row rows the caller may see. The default order is `project_id`, then `metric_code` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project measurement summary row rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "family": "Sustainability", "dimension": "Mass", "base_unit_code": "kg", "aggregation": "Sum", "objective_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direction": "At Most", "target_value": 2, "target_unit_code": "kg", "target_base": 2000, "measured_count": 2, "unmeasured_count": 1, "measured_base": 1953.59237, "last_measured_on": "2026-10-08", "outcome": "Met" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectMeasurementSummaryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/cue-calls": { "get": { "operationId": "cueCalls.list", "tags": ["Show"], "x-xos-table": "app.cue_calls", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List cue call rows", "description": "A department's call on a cue (1180): the audio, lighting, video, special effects or stage instruction given when the cue fires. The Run of Show sheet holds one column per department. Returns a cursor page of cue call rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of cue call rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "call_kind": "Lighting", "instruction": "LX 14 GO, house to half." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CueCallPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "cueCalls.create", "tags": ["Show"], "x-xos-table": "app.cue_calls", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Create a cue call", "description": "A department's call on a cue (1180): the audio, lighting, video, special effects or stage instruction given when the cue fires. The Run of Show sheet holds one column per department. Creates a cue call. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "cue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "call_kind": "Lighting", "instruction": "LX 14 GO, house to half." }, "schema": { "$ref": "#/components/schemas/CueCallCreate" } } } }, "responses": { "201": { "description": "The created cue call.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "call_kind": "Lighting", "instruction": "LX 14 GO, house to half." }, "schema": { "$ref": "#/components/schemas/CueCall" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/cue-calls/{id}": { "get": { "operationId": "cueCalls.get", "tags": ["Show"], "x-xos-table": "app.cue_calls", "x-xos-capability": "show.run_of_show.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Get a cue call", "description": "A department's call on a cue (1180): the audio, lighting, video, special effects or stage instruction given when the cue fires. The Run of Show sheet holds one column per department. Returns one cue call with its `ETag`. A cue call the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cue call.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cue call.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The cue call.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "call_kind": "Lighting", "instruction": "LX 14 GO, house to half." }, "schema": { "$ref": "#/components/schemas/CueCall" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "cueCalls.update", "tags": ["Show"], "x-xos-table": "app.cue_calls", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Update a cue call", "description": "A department's call on a cue (1180): the audio, lighting, video, special effects or stage instruction given when the cue fires. The Run of Show sheet holds one column per department. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cue call.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cue call.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "call_kind": "Lighting", "instruction": "LX 14 GO, house to half." }, "schema": { "$ref": "#/components/schemas/CueCallUpdate" } } } }, "responses": { "200": { "description": "The updated cue call.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "call_kind": "Lighting", "instruction": "LX 14 GO, house to half." }, "schema": { "$ref": "#/components/schemas/CueCall" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "cueCalls.delete", "tags": ["Show"], "x-xos-table": "app.cue_calls", "x-xos-capability": "show.run_of_show.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["show"] }], "summary": "Delete a cue call", "description": "A department's call on a cue (1180): the audio, lighting, video, special effects or stage instruction given when the cue fires. The Run of Show sheet holds one column per department. Soft-deletes the cue call: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the cue call.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the cue call.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The cue call moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/guest-list-entries": { "get": { "operationId": "guestListEntries.list", "tags": ["Advancing"], "x-xos-table": "app.guest_list_entries", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List guest list entry rows", "description": "A guest on a project's guest list with plus-ones. Requested guests are approved or declined by someone with review authority who did not request them, then checked in at the door. Returns a cursor page of guest list entry rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of guest list entry rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage.", "entry_state": "Requested", "decided_at": "2026-10-08T14:30:00Z", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_at": "2026-10-08T14:30:00Z", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/GuestListEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "guestListEntries.create", "tags": ["Advancing"], "x-xos-table": "app.guest_list_entries", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Create a guest list entry", "description": "A guest on a project's guest list with plus-ones. Requested guests are approved or declined by someone with review authority who did not request them, then checked in at the door. Creates a guest list entry. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage." }, "schema": { "$ref": "#/components/schemas/GuestListEntryCreate" } } } }, "responses": { "201": { "description": "The created guest list entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage.", "entry_state": "Requested", "decided_at": "2026-10-08T14:30:00Z", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_at": "2026-10-08T14:30:00Z", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/GuestListEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/guest-list-entries/{id}": { "get": { "operationId": "guestListEntries.get", "tags": ["Advancing"], "x-xos-table": "app.guest_list_entries", "x-xos-capability": "advancing.packet.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Get a guest list entry", "description": "A guest on a project's guest list with plus-ones. Requested guests are approved or declined by someone with review authority who did not request them, then checked in at the door. Returns one guest list entry with its `ETag`. A guest list entry the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the guest list entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The guest list entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage.", "entry_state": "Requested", "decided_at": "2026-10-08T14:30:00Z", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_at": "2026-10-08T14:30:00Z", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/GuestListEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "guestListEntries.update", "tags": ["Advancing"], "x-xos-table": "app.guest_list_entries", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Update a guest list entry", "description": "A guest on a project's guest list with plus-ones. Requested guests are approved or declined by someone with review authority who did not request them, then checked in at the door. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the guest list entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage." }, "schema": { "$ref": "#/components/schemas/GuestListEntryUpdate" } } } }, "responses": { "200": { "description": "The updated guest list entry.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage.", "entry_state": "Requested", "decided_at": "2026-10-08T14:30:00Z", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_at": "2026-10-08T14:30:00Z", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/GuestListEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "guestListEntries.delete", "tags": ["Advancing"], "x-xos-table": "app.guest_list_entries", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Delete a guest list entry", "description": "A guest on a project's guest list with plus-ones. Requested guests are approved or declined by someone with review authority who did not request them, then checked in at the door. Soft-deletes the guest list entry: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the guest list entry.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The guest list entry moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/guest-list-entries/{id}/decide": { "post": { "operationId": "guestListEntries.decide", "tags": ["Advancing"], "x-xos-table": "app.guest_list_entries", "x-xos-capability": "advancing.submission.review", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Approve or decline a guest", "description": "Moves a Requested guest to Approved or Declined. Needs review authority on the project and refuses the person who requested the guest (sod_guest_requester, 422); the database stamps who decided and when. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the guest list entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "outcome": "Approved" }, "schema": { "$ref": "#/components/schemas/GuestDecisionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage.", "entry_state": "Requested", "decided_at": "2026-10-08T14:30:00Z", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_at": "2026-10-08T14:30:00Z", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/GuestListEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/guest-list-entries/{id}/check-in": { "post": { "operationId": "guestListEntries.checkIn", "tags": ["Advancing"], "x-xos-table": "app.guest_list_entries", "x-xos-capability": "advancing.rider.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["advancing"] }], "summary": "Check a guest in", "description": "Moves an Approved guest to Checked In at the door; the database stamps who checked them in and when. Any other state is refused (422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the guest list entry.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the guest list entry.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scope_node_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Pike", "plus_ones": 1, "note": "Side stage.", "entry_state": "Requested", "decided_at": "2026-10-08T14:30:00Z", "decided_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "checked_in_at": "2026-10-08T14:30:00Z", "checked_in_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/GuestListEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-1099-nec/rows": { "get": { "operationId": "form1099Nec.rows", "tags": ["Finance"], "x-xos-table": "app.form_1099_nec_rows", "x-xos-capability": "finance.payment.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["finance"] }], "summary": "1099-NEC payees of a tax year", "description": "Payees paid $600 or more in approved USD payments in the calendar year as independent contractors (individuals and accounts), with whether a W-9 and its address are on file. Full TINs are a Restricted export with step-up, in Atlas only. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "integer", "minimum": 2020, "description": "Tax year.", "example": 2025 }, "required": true, "description": "Tax year.", "name": "year", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "payee_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_organization_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "payee_name": "Ivy Marchetti", "w9_on_file": true, "tin_type": 2, "tin_last4": "6789", "address_complete": true, "amount_minor": 75000, "payment_count": 2 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/Form1099NecRowPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/insurance-certificate-insureds": { "get": { "operationId": "insuranceCertificateInsureds.list", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificate_insureds", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List insurance certificate insured rows", "description": "A party a certificate of insurance names, with the endorsement it grants (1130). A name appears once per endorsement on a certificate, ignoring case and spacing (409). Returns a cursor page of insurance certificate insured rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of insurance certificate insured rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certificate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateInsuredPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "insuranceCertificateInsureds.create", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificate_insureds", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create an insurance certificate insured", "description": "A party a certificate of insurance names, with the endorsement it grants (1130). A name appears once per endorsement on a certificate, ignoring case and spacing (409). Creates an insurance certificate insured. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "certificate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateInsuredCreate" } } } }, "responses": { "201": { "description": "The created insurance certificate insured.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certificate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateInsured" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/insurance-certificate-insureds/{id}": { "get": { "operationId": "insuranceCertificateInsureds.get", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificate_insureds", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get an insurance certificate insured", "description": "A party a certificate of insurance names, with the endorsement it grants (1130). A name appears once per endorsement on a certificate, ignoring case and spacing (409). Returns one insurance certificate insured with its `ETag`. A insurance certificate insured the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the insurance certificate insured.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The insurance certificate insured.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certificate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateInsured" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "insuranceCertificateInsureds.update", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificate_insureds", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update an insurance certificate insured", "description": "A party a certificate of insurance names, with the endorsement it grants (1130). A name appears once per endorsement on a certificate, ignoring case and spacing (409). Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the insurance certificate insured.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateInsuredUpdate" } } } }, "responses": { "200": { "description": "The updated insurance certificate insured.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "certificate_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/InsuranceCertificateInsured" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "insuranceCertificateInsureds.delete", "tags": ["Vendors"], "x-xos-table": "app.insurance_certificate_insureds", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete an insurance certificate insured", "description": "A party a certificate of insurance names, with the endorsement it grants (1130). A name appears once per endorsement on a certificate, ignoring case and spacing (409). Soft-deletes the insurance certificate insured: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the insurance certificate insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the insurance certificate insured.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The insurance certificate insured moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/required-additional-insureds": { "get": { "operationId": "requiredAdditionalInsureds.list", "tags": ["Vendors"], "x-xos-table": "app.required_additional_insureds", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List required additional insured rows", "description": "A party the org requires its vendors' certificates to name (1130): org-wide when project_id is null, or for vendors engaged on one project as well. app.verify_onboarding_insureds checks an engagement against them. Returns a cursor page of required additional insured rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of required additional insured rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RequiredAdditionalInsuredPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "requiredAdditionalInsureds.create", "tags": ["Vendors"], "x-xos-table": "app.required_additional_insureds", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Create a required additional insured", "description": "A party the org requires its vendors' certificates to name (1130): org-wide when project_id is null, or for vendors engaged on one project as well. app.verify_onboarding_insureds checks an engagement against them. Creates a required additional insured. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/RequiredAdditionalInsuredCreate" } } } }, "responses": { "201": { "description": "The created required additional insured.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/RequiredAdditionalInsured" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/required-additional-insureds/{id}": { "get": { "operationId": "requiredAdditionalInsureds.get", "tags": ["Vendors"], "x-xos-table": "app.required_additional_insureds", "x-xos-capability": "vendors.vendor.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Get a required additional insured", "description": "A party the org requires its vendors' certificates to name (1130): org-wide when project_id is null, or for vendors engaged on one project as well. app.verify_onboarding_insureds checks an engagement against them. Returns one required additional insured with its `ETag`. A required additional insured the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the required additional insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the required additional insured.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The required additional insured.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/RequiredAdditionalInsured" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "requiredAdditionalInsureds.update", "tags": ["Vendors"], "x-xos-table": "app.required_additional_insureds", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Update a required additional insured", "description": "A party the org requires its vendors' certificates to name (1130): org-wide when project_id is null, or for vendors engaged on one project as well. app.verify_onboarding_insureds checks an engagement against them. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the required additional insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the required additional insured.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/RequiredAdditionalInsuredUpdate" } } } }, "responses": { "200": { "description": "The updated required additional insured.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "insured_name": "Example Venue Owner LLC", "endorsement_kind": "Additional Insured" }, "schema": { "$ref": "#/components/schemas/RequiredAdditionalInsured" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "requiredAdditionalInsureds.delete", "tags": ["Vendors"], "x-xos-table": "app.required_additional_insureds", "x-xos-capability": "vendors.coi.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["vendors"] }], "summary": "Delete a required additional insured", "description": "A party the org requires its vendors' certificates to name (1130): org-wide when project_id is null, or for vendors engaged on one project as well. app.verify_onboarding_insureds checks an engagement against them. Soft-deletes the required additional insured: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the required additional insured.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the required additional insured.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The required additional insured moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/emergency-protocols": { "get": { "operationId": "canonStdEmergencyProtocols.list", "tags": ["Canon"], "x-xos-table": "xpms.emergency_protocol", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "x-xos-order": { "by": ["record_key"], "numeric": false }, "summary": "List emergency protocol rows", "description": "An emergency protocol of the Standard Library (Emergency Codes sheet): what one operational domain does when a radio code is called, in numbered steps. Returns a cursor page of emergency protocol rows the caller may see. The default order is `record_key` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of emergency protocol rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "record_key": "EMG-001", "code": "CODE_RED", "domain": "Site Operations", "department": "Security & Safety", "category": "Emergency Protocols", "sub_category": "Incident Response", "steps": [{ "step_no": 1, "body": "Contact {fire}." }] } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/CanonStdEmergencyProtocolPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/canon/std/emergency-protocols/{record_key}": { "get": { "operationId": "canonStdEmergencyProtocols.get", "tags": ["Canon"], "x-xos-table": "xpms.emergency_protocol", "x-xos-capability": "canon.taxonomy.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["canon"] }], "summary": "Get an emergency protocol", "description": "An emergency protocol of the Standard Library (Emergency Codes sheet): what one operational domain does when a radio code is called, in numbered steps. Returns one emergency protocol with its `ETag`. A emergency protocol the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", "description": "Record identifier of the protocol.", "example": "EMG-001" }, "required": true, "description": "Record identifier of the protocol.", "name": "record_key", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The emergency protocol.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "record_key": "EMG-001", "code": "CODE_RED", "domain": "Site Operations", "department": "Security & Safety", "category": "Emergency Protocols", "sub_category": "Incident Response", "steps": [{ "step_no": 1, "body": "Contact {fire}." }] }, "schema": { "$ref": "#/components/schemas/CanonStdEmergencyProtocol" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-schedule-recipients": { "get": { "operationId": "reportScheduleRecipients.list", "tags": ["Reports"], "x-xos-table": "app.report_schedule_recipients", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List report schedule recipient rows", "description": "A member of the org a scheduled report is emailed to; each receives it run with their own access, so a report never leaves the org (Section 4.6.4). Returns a cursor page of report schedule recipient rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of report schedule recipient rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_schedule_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportScheduleRecipientPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "reportScheduleRecipients.create", "tags": ["Reports"], "x-xos-table": "app.report_schedule_recipients", "x-xos-capability": "reports.schedule.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Create a report schedule recipient", "description": "A member of the org a scheduled report is emailed to; each receives it run with their own access, so a report never leaves the org (Section 4.6.4). Creates a report schedule recipient. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "report_schedule_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportScheduleRecipientCreate" } } } }, "responses": { "201": { "description": "The created report schedule recipient.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_schedule_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportScheduleRecipient" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-schedule-recipients/{id}": { "get": { "operationId": "reportScheduleRecipients.get", "tags": ["Reports"], "x-xos-table": "app.report_schedule_recipients", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Get a report schedule recipient", "description": "A member of the org a scheduled report is emailed to; each receives it run with their own access, so a report never leaves the org (Section 4.6.4). Returns one report schedule recipient with its `ETag`. A report schedule recipient the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report schedule recipient.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The report schedule recipient.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_schedule_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ReportScheduleRecipient" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "reportScheduleRecipients.delete", "tags": ["Reports"], "x-xos-table": "app.report_schedule_recipients", "x-xos-capability": "reports.schedule.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Delete a report schedule recipient", "description": "A member of the org a scheduled report is emailed to; each receives it run with their own access, so a report never leaves the org (Section 4.6.4). Soft-deletes the report schedule recipient: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report schedule recipient.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report schedule recipient.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The report schedule recipient moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-deliveries": { "get": { "operationId": "reportDeliveries.list", "tags": ["Reports"], "x-xos-table": "app.report_deliveries", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List report delivery rows", "description": "One email of a scheduled report to one recipient: the run made as that member for the slot, and whether the email went out. Written only by the scheduler and the delivery worker. Returns a cursor page of report delivery rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of report delivery rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_schedule_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scheduled_for": "2026-10-08T14:30:00Z", "delivery_status": "Queued", "sent_at": "2026-10-08T14:30:00Z", "last_error": "The report run failed." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ReportDeliveryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/report-deliveries/{id}": { "get": { "operationId": "reportDeliveries.get", "tags": ["Reports"], "x-xos-table": "app.report_deliveries", "x-xos-capability": "reports.report.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["reports"] }], "summary": "Get a report delivery", "description": "One email of a scheduled report to one recipient: the run made as that member for the slot, and whether the email went out. Written only by the scheduler and the delivery worker. Returns one report delivery with its `ETag`. A report delivery the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the report delivery.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the report delivery.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The report delivery.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_schedule_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "report_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scheduled_for": "2026-10-08T14:30:00Z", "delivery_status": "Queued", "sent_at": "2026-10-08T14:30:00Z", "last_error": "The report run failed." }, "schema": { "$ref": "#/components/schemas/ReportDelivery" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/status": { "get": { "operationId": "aurora.status", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Read what Aurora can do now", "description": "Features the caller may use (turned on by an Admin and included in the plan) and this month's use of the org's allowance. A rule that refuses the request returns 422 with `refusal` and `reason`.", "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "enabled_features": ["assistant", "extraction"], "used": 12, "allowance": 500, "plan_includes_aurora": true }, "schema": { "$ref": "#/components/schemas/AuroraStatus" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/ask": { "post": { "operationId": "aurora.ask", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Ask the assistant", "description": "Answers a question from records the caller can read through this API, citing them. Returns no_answer with what is missing when the records do not support an answer. Changes it proposes are stored as suggestions for confirmation; nothing is written. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "question": "Which permits are blocked?", "history": [ { "question": "Which permits are blocked?", "answer": "One: Fire Marshal Permit." } ] }, "schema": { "$ref": "#/components/schemas/AuroraAskRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "answer", "ai_generated": true, "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "model": "claude-sonnet-5-5", "missing": "No budget lines exist yet.", "failure_code": "model_error", "answer": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] }, "suggestions": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] }, "schema": { "$ref": "#/components/schemas/AuroraResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/filter": { "post": { "operationId": "aurora.filter", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Turn a sentence into a filter", "description": "Builds a filter on one collection from a sentence, shows it as an ADR 0003 query string and proposes a saved view (`savedViews.create`) for confirmation. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "sentence": "blocked permits for Miami shows this month", "collections": ["permits"], "time_zone": "America/New_York", "fields": [{ "name": "overdue", "type": "boolean", "ops": ["eq"] }] }, "schema": { "$ref": "#/components/schemas/AuroraFilterRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "answer", "ai_generated": true, "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "model": "claude-sonnet-5-5", "missing": "No budget lines exist yet.", "failure_code": "model_error", "answer": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] }, "suggestions": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] }, "schema": { "$ref": "#/components/schemas/AuroraResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/extract": { "post": { "operationId": "aurora.extract", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Extract a document", "description": "Reads a rider, insurance certificate, invoice, receipt or quote into proposed fields with a confidence each and provenance agent. A price, date or quantity the document does not show is NO_ANSWER. Nothing is written until the caller confirms. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "insurance_certificate", "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "media_type": "application/pdf", "content_base64": "JVBERi0xLjcK", "file_name": "coi-atlantic.pdf" }, "schema": { "$ref": "#/components/schemas/AuroraExtractRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "answer", "ai_generated": true, "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "model": "claude-sonnet-5-5", "missing": "No budget lines exist yet.", "failure_code": "model_error", "answer": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] }, "suggestions": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] }, "schema": { "$ref": "#/components/schemas/AuroraResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/draft": { "post": { "operationId": "aurora.draft", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Draft text", "description": "Drafts an SOP, advance packet, email, day sheet or change order description in the org's verbiage library. Facts the context lacks are marked as gaps, never invented. The draft is returned, not saved or sent. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "sop", "instructions": "Write the load-in SOP for the main stage.", "context": [ { "collection": "venues", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "verbiage": [{ "term": "loading dock", "preferred": "Dock" }] }, "schema": { "$ref": "#/components/schemas/AuroraDraftRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "answer", "ai_generated": true, "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "model": "claude-sonnet-5-5", "missing": "No budget lines exist yet.", "failure_code": "model_error", "answer": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] }, "suggestions": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] }, "schema": { "$ref": "#/components/schemas/AuroraResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/summarize": { "post": { "operationId": "aurora.summarize", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Summarize activity", "description": "Summarizes a record's activity, a project's week or gate readiness, citing the items each point comes from. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "project_week", "subject_collection": "projects", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "items": [ { "collection": "activity-events", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ] }, "schema": { "$ref": "#/components/schemas/AuroraSummarizeRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "answer", "ai_generated": true, "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "model": "claude-sonnet-5-5", "missing": "No budget lines exist yet.", "failure_code": "model_error", "answer": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] }, "suggestions": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] }, "schema": { "$ref": "#/components/schemas/AuroraResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/map-columns": { "post": { "operationId": "aurora.mapColumns", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Suggest import column mappings", "description": "Suggests a target field for each import column. The import wizard shows the suggestions for the caller to accept or change. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "collection": "people", "columns": [{ "header": "E-mail", "samples": ["crew@example.com"] }], "fields": [{ "name": "email", "description": "Email address." }] }, "schema": { "$ref": "#/components/schemas/AuroraMapColumnsRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "answer", "ai_generated": true, "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "model": "claude-sonnet-5-5", "missing": "No budget lines exist yet.", "failure_code": "model_error", "answer": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] }, "suggestions": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] }, "schema": { "$ref": "#/components/schemas/AuroraResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/bind-code": { "post": { "operationId": "aurora.bindCode", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Suggest a catalog binding", "description": "Suggests the catalog element an unknown scanned code identifies, only from the candidates given, and proposes `catalogBindings.create` for confirmation. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "0012345678905", "description": "LED PANEL 500MM", "candidates": [ { "element_id": "9000.02.03-NWL-0001", "name": "LED Wall Panel", "urid": "9000.02.03" } ] }, "schema": { "$ref": "#/components/schemas/AuroraBindCodeRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "outcome": "answer", "ai_generated": true, "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "model": "claude-sonnet-5-5", "missing": "No budget lines exist yet.", "failure_code": "model_error", "answer": { "text": "One permit is blocked: Fire Marshal Permit.", "citations": [] }, "suggestions": [ { "suggestion_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "savedViews.create", "summary": "Save the view Blocked Miami Permits." } ] }, "schema": { "$ref": "#/components/schemas/AuroraResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/aurora/preview": { "post": { "operationId": "aurora.preview", "tags": ["Settings"], "x-xos-table": "app.ai_settings", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Preview what a request would send", "description": "Reads the records a drafting or summary request names, as the request would (the caller's permissions, Restricted columns, masked values and excluded tables removed), and returns what would be sent. A gate readiness summary adds the project's gate criteria. No model is called and nothing is metered (A95). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "feature": "drafting", "kind": "gate_readiness", "subject_collection": "projects", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "items": [{ "collection": "sops", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }] }, "schema": { "$ref": "#/components/schemas/AuroraPreviewRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "records": [], "vocabulary_terms": 12 }, "schema": { "$ref": "#/components/schemas/AuroraPreview" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-suggestions": { "get": { "operationId": "aiSuggestions.list", "tags": ["Settings"], "x-xos-table": "app.ai_suggestions", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List AI suggestion rows", "description": "A change an Aurora feature proposes, waiting for the confirmation of the person who asked. The summary says exactly what will change; nothing is written until they confirm. Returns a cursor page of AI suggestion rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of AI suggestion rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "insuranceCertificates.create", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "summary": "Add the Atlantic Mutual general liability certificate.", "suggestion_state": "Proposed", "expires_at": "2026-10-08T14:30:00Z", "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_fields": [ { "field_path": "expires_on", "proposed_value": "2027-03-31", "confidence": 0.91, "refusal": null, "missing": null, "source_excerpt": "Policy expiration 03/31/2027", "provenance": "agent" } ] } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AiSuggestionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-suggestions/{id}": { "get": { "operationId": "aiSuggestions.get", "tags": ["Settings"], "x-xos-table": "app.ai_suggestions", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Get an AI suggestion", "description": "A change an Aurora feature proposes, waiting for the confirmation of the person who asked. The summary says exactly what will change; nothing is written until they confirm. Returns one AI suggestion with its `ETag`. A AI suggestion the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai suggestion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai suggestion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The AI suggestion.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "insuranceCertificates.create", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "summary": "Add the Atlantic Mutual general liability certificate.", "suggestion_state": "Proposed", "expires_at": "2026-10-08T14:30:00Z", "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_fields": [ { "field_path": "expires_on", "proposed_value": "2027-03-31", "confidence": 0.91, "refusal": null, "missing": null, "source_excerpt": "Policy expiration 03/31/2027", "provenance": "agent" } ] }, "schema": { "$ref": "#/components/schemas/AiSuggestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-suggestions/{id}/confirm": { "post": { "operationId": "aiSuggestions.confirm", "tags": ["Settings"], "x-xos-table": "app.ai_suggestions", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Confirm an AI suggestion", "description": "Records the confirmation of the person who asked, then performs the named public operation as the caller with the proposed values and any `values` the caller changed or added. On success the suggestion is Applied with the record written. When the operation refuses, the suggestion returns to Proposed and the answer is that 422 refusal. Refused after expiry. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai suggestion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai suggestion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Checked against the certificate.", "values": { "document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } }, "schema": { "$ref": "#/components/schemas/AiSuggestionConfirmRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "insuranceCertificates.create", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "summary": "Add the Atlantic Mutual general liability certificate.", "suggestion_state": "Proposed", "expires_at": "2026-10-08T14:30:00Z", "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_fields": [ { "field_path": "expires_on", "proposed_value": "2027-03-31", "confidence": 0.91, "refusal": null, "missing": null, "source_excerpt": "Policy expiration 03/31/2027", "provenance": "agent" } ] }, "schema": { "$ref": "#/components/schemas/AiSuggestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-suggestions/{id}/reject": { "post": { "operationId": "aiSuggestions.reject", "tags": ["Settings"], "x-xos-table": "app.ai_suggestions", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Reject an AI suggestion", "description": "Rejects a Proposed suggestion; nothing is written. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai suggestion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai suggestion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Checked against the certificate." }, "schema": { "$ref": "#/components/schemas/AiSuggestionRejectRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "insuranceCertificates.create", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "summary": "Add the Atlantic Mutual general liability certificate.", "suggestion_state": "Proposed", "expires_at": "2026-10-08T14:30:00Z", "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_fields": [ { "field_path": "expires_on", "proposed_value": "2027-03-31", "confidence": 0.91, "refusal": null, "missing": null, "source_excerpt": "Policy expiration 03/31/2027", "provenance": "agent" } ] }, "schema": { "$ref": "#/components/schemas/AiSuggestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-suggestions/{id}/apply": { "post": { "operationId": "aiSuggestions.apply", "tags": ["Settings"], "x-xos-table": "app.ai_suggestions", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Record the write of a confirmed suggestion", "description": "Marks a Confirmed suggestion Applied with the record the public API wrote. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai suggestion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai suggestion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Written by insuranceCertificates.create." }, "schema": { "$ref": "#/components/schemas/AiSuggestionApplyRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "insuranceCertificates.create", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "summary": "Add the Atlantic Mutual general liability certificate.", "suggestion_state": "Proposed", "expires_at": "2026-10-08T14:30:00Z", "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_fields": [ { "field_path": "expires_on", "proposed_value": "2027-03-31", "confidence": 0.91, "refusal": null, "missing": null, "source_excerpt": "Policy expiration 03/31/2027", "provenance": "agent" } ] }, "schema": { "$ref": "#/components/schemas/AiSuggestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-suggestions/{id}/reopen": { "post": { "operationId": "aiSuggestions.reopen", "tags": ["Settings"], "x-xos-table": "app.ai_suggestions", "x-xos-capability": "home.dashboard.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["home"] }], "summary": "Return a confirmed suggestion to Proposed", "description": "Returns a Confirmed suggestion to Proposed when the public API refused the write, naming the refusal. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai suggestion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai suggestion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Checked against the certificate." }, "schema": { "$ref": "#/components/schemas/AiSuggestionReopenRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "operation_id": "insuranceCertificates.create", "target_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "summary": "Add the Atlantic Mutual general liability certificate.", "suggestion_state": "Proposed", "expires_at": "2026-10-08T14:30:00Z", "applied_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "proposed_fields": [ { "field_path": "expires_on", "proposed_value": "2027-03-31", "confidence": 0.91, "refusal": null, "missing": null, "source_excerpt": "Policy expiration 03/31/2027", "provenance": "agent" } ] }, "schema": { "$ref": "#/components/schemas/AiSuggestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-requests": { "get": { "operationId": "aiRequests.list", "tags": ["Settings"], "x-xos-table": "app.ai_requests", "x-xos-capability": "audit.log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["audit"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List AI request rows", "description": "One Aurora model call: who asked, for which feature, with which configured model, and the prompt and output with personal data redacted. Restricted fields and medical records are never in it. Returns a cursor page of AI request rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of AI request rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feature": "assistant", "model": "claude-sonnet-5-5", "subject_table": "app.documents", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "outcome": "Answered", "prompt_redacted": "Who is the vendor contact?", "output_redacted": "Ivy Chen, [phone].", "failure_code": "model_error", "completed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AiRequestPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-requests/{id}": { "get": { "operationId": "aiRequests.get", "tags": ["Settings"], "x-xos-table": "app.ai_requests", "x-xos-capability": "audit.log.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["audit"] }], "summary": "Get an AI request", "description": "One Aurora model call: who asked, for which feature, with which configured model, and the prompt and output with personal data redacted. Restricted fields and medical records are never in it. Returns one AI request with its `ETag`. A AI request the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ai request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ai request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The AI request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feature": "assistant", "model": "claude-sonnet-5-5", "subject_table": "app.documents", "subject_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "outcome": "Answered", "prompt_redacted": "Who is the vendor contact?", "output_redacted": "Ivy Chen, [phone].", "failure_code": "model_error", "completed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/AiRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ai-usage": { "get": { "operationId": "aiUsage.list", "tags": ["Settings"], "x-xos-table": "app.ai_usage", "x-xos-capability": "org.usage.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["metered_at"], "numeric": false }, "summary": "List AI usage rows", "description": "Aurora metering (ADR 0020): one row per authorized request. The monthly allowance aurora_requests_per_month counts these rows by UTC month. Returns a cursor page of AI usage rows the caller may see. The default order is `metered_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of AI usage rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "request_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metered_at": "2026-10-08T14:30:00Z", "input_tokens": 812, "output_tokens": 96 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AiUsagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-details": { "get": { "operationId": "workDetails.list", "tags": ["Identity"], "x-xos-table": "app.person_work_details", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List work details rows", "description": "The caller's own work details (Section 4.5.6 item 10): uniform sizes, dietary and accessibility needs and the travel profile. Read and written only by the person; an engaging org sees a category only while the person shares it with that engagement. The passport number is Restricted and encrypted: it is written here, always read masked, and shown only through the logged revealPassport action. One live row per person (409 on a second). Returns a cursor page of work details rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of work details rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shirt_size": "XXS", "jacket_size": "XXS", "pants_size": "32x32", "shoe_size": "US 10.5", "glove_size": "XXS", "hat_size": "7 1/4", "uniform_notes": "Prefers a relaxed cut.", "dietary_needs": ["Vegan"], "allergies": "Peanuts, severe", "dietary_notes": "No pork.", "accessibility_needs": ["Seating"], "accessibility_notes": "Needs a seat near the stage door.", "seat_preference": "Window", "meal_preference": "Vegetarian (VGML)", "home_airport": "MIA", "passport_number": "YA0000TEST", "passport_number_last4": "TEST", "passport_issuing_country": "US", "passport_expires_on": "2026-10-08", "passport_name": "IVY MARCHETTI" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkDetailsPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workDetails.create", "tags": ["Identity"], "x-xos-table": "app.person_work_details", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a work details", "description": "The caller's own work details (Section 4.5.6 item 10): uniform sizes, dietary and accessibility needs and the travel profile. Read and written only by the person; an engaging org sees a category only while the person shares it with that engagement. The passport number is Restricted and encrypted: it is written here, always read masked, and shown only through the logged revealPassport action. One live row per person (409 on a second). Creates a work details. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "shirt_size": "XXS", "jacket_size": "XXS", "pants_size": "32x32", "shoe_size": "US 10.5", "glove_size": "XXS", "hat_size": "7 1/4", "uniform_notes": "Prefers a relaxed cut.", "dietary_needs": ["Vegan"], "allergies": "Peanuts, severe", "dietary_notes": "No pork.", "accessibility_needs": ["Seating"], "accessibility_notes": "Needs a seat near the stage door.", "seat_preference": "Window", "meal_preference": "Vegetarian (VGML)", "home_airport": "MIA", "passport_number": "YA0000TEST", "passport_issuing_country": "US", "passport_expires_on": "2026-10-08", "passport_name": "IVY MARCHETTI" }, "schema": { "$ref": "#/components/schemas/WorkDetailsCreate" } } } }, "responses": { "201": { "description": "The created work details.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shirt_size": "XXS", "jacket_size": "XXS", "pants_size": "32x32", "shoe_size": "US 10.5", "glove_size": "XXS", "hat_size": "7 1/4", "uniform_notes": "Prefers a relaxed cut.", "dietary_needs": ["Vegan"], "allergies": "Peanuts, severe", "dietary_notes": "No pork.", "accessibility_needs": ["Seating"], "accessibility_notes": "Needs a seat near the stage door.", "seat_preference": "Window", "meal_preference": "Vegetarian (VGML)", "home_airport": "MIA", "passport_number": "YA0000TEST", "passport_number_last4": "TEST", "passport_issuing_country": "US", "passport_expires_on": "2026-10-08", "passport_name": "IVY MARCHETTI" }, "schema": { "$ref": "#/components/schemas/WorkDetails" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-details/{id}": { "get": { "operationId": "workDetails.get", "tags": ["Identity"], "x-xos-table": "app.person_work_details", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a work details", "description": "The caller's own work details (Section 4.5.6 item 10): uniform sizes, dietary and accessibility needs and the travel profile. Read and written only by the person; an engaging org sees a category only while the person shares it with that engagement. The passport number is Restricted and encrypted: it is written here, always read masked, and shown only through the logged revealPassport action. One live row per person (409 on a second). Returns one work details with its `ETag`. A work details the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work details.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work details.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The work details.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shirt_size": "XXS", "jacket_size": "XXS", "pants_size": "32x32", "shoe_size": "US 10.5", "glove_size": "XXS", "hat_size": "7 1/4", "uniform_notes": "Prefers a relaxed cut.", "dietary_needs": ["Vegan"], "allergies": "Peanuts, severe", "dietary_notes": "No pork.", "accessibility_needs": ["Seating"], "accessibility_notes": "Needs a seat near the stage door.", "seat_preference": "Window", "meal_preference": "Vegetarian (VGML)", "home_airport": "MIA", "passport_number": "YA0000TEST", "passport_number_last4": "TEST", "passport_issuing_country": "US", "passport_expires_on": "2026-10-08", "passport_name": "IVY MARCHETTI" }, "schema": { "$ref": "#/components/schemas/WorkDetails" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "workDetails.update", "tags": ["Identity"], "x-xos-table": "app.person_work_details", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a work details", "description": "The caller's own work details (Section 4.5.6 item 10): uniform sizes, dietary and accessibility needs and the travel profile. Read and written only by the person; an engaging org sees a category only while the person shares it with that engagement. The passport number is Restricted and encrypted: it is written here, always read masked, and shown only through the logged revealPassport action. One live row per person (409 on a second). Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work details.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work details.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "shirt_size": "XXS", "jacket_size": "XXS", "pants_size": "32x32", "shoe_size": "US 10.5", "glove_size": "XXS", "hat_size": "7 1/4", "uniform_notes": "Prefers a relaxed cut.", "dietary_needs": ["Vegan"], "allergies": "Peanuts, severe", "dietary_notes": "No pork.", "accessibility_needs": ["Seating"], "accessibility_notes": "Needs a seat near the stage door.", "seat_preference": "Window", "meal_preference": "Vegetarian (VGML)", "home_airport": "MIA", "passport_number": "YA0000TEST", "passport_issuing_country": "US", "passport_expires_on": "2026-10-08", "passport_name": "IVY MARCHETTI" }, "schema": { "$ref": "#/components/schemas/WorkDetailsUpdate" } } } }, "responses": { "200": { "description": "The updated work details.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shirt_size": "XXS", "jacket_size": "XXS", "pants_size": "32x32", "shoe_size": "US 10.5", "glove_size": "XXS", "hat_size": "7 1/4", "uniform_notes": "Prefers a relaxed cut.", "dietary_needs": ["Vegan"], "allergies": "Peanuts, severe", "dietary_notes": "No pork.", "accessibility_needs": ["Seating"], "accessibility_notes": "Needs a seat near the stage door.", "seat_preference": "Window", "meal_preference": "Vegetarian (VGML)", "home_airport": "MIA", "passport_number": "YA0000TEST", "passport_number_last4": "TEST", "passport_issuing_country": "US", "passport_expires_on": "2026-10-08", "passport_name": "IVY MARCHETTI" }, "schema": { "$ref": "#/components/schemas/WorkDetails" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "workDetails.delete", "tags": ["Identity"], "x-xos-table": "app.person_work_details", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a work details", "description": "The caller's own work details (Section 4.5.6 item 10): uniform sizes, dietary and accessibility needs and the travel profile. Read and written only by the person; an engaging org sees a category only while the person shares it with that engagement. The passport number is Restricted and encrypted: it is written here, always read masked, and shown only through the logged revealPassport action. One live row per person (409 on a second). Soft-deletes the work details: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work details.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work details.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The work details moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-details/{id}/reveal-passport": { "post": { "operationId": "workDetails.revealPassport", "tags": ["Identity"], "x-xos-table": "app.person_work_details", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.reveal_my_passport_number", "summary": "Reveal the caller's passport number", "description": "Returns the caller's own passport number in plain text through `app.reveal_my_passport_number`. Every reveal is written to the person's access log. 422 passport_number_missing when none is recorded. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work details.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work details.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "passport_number": "YA0000TEST" }, "schema": { "$ref": "#/components/schemas/PassportReveal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/emergency-contacts": { "get": { "operationId": "emergencyContacts.list", "tags": ["Identity"], "x-xos-table": "app.person_emergency_contacts", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["sort_order", "created_at"], "numeric": false }, "summary": "List emergency contact rows", "description": "One of the caller's emergency contacts (Section 4.5.6 item 10), in calling order, at most five (422 emergency_contact_limit). Phones are E.164 (Section 15). Shared with an engagement under the Emergency Contacts category. Returns a cursor page of emergency contact rows the caller may see. The default order is `sort_order`, then `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of emergency contact rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "full_name": "Marco Marchetti", "relationship": "Brother", "phone_e164": "+13055550142", "alternate_phone_e164": "+13055550142", "email": "alex.rivera@northwindlive.example", "sort_order": 0 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EmergencyContactPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "emergencyContacts.create", "tags": ["Identity"], "x-xos-table": "app.person_emergency_contacts", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create an emergency contact", "description": "One of the caller's emergency contacts (Section 4.5.6 item 10), in calling order, at most five (422 emergency_contact_limit). Phones are E.164 (Section 15). Shared with an engagement under the Emergency Contacts category. Creates an emergency contact. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "full_name": "Marco Marchetti", "relationship": "Brother", "phone_e164": "+13055550142", "alternate_phone_e164": "+13055550142", "email": "alex.rivera@northwindlive.example", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/EmergencyContactCreate" } } } }, "responses": { "201": { "description": "The created emergency contact.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "full_name": "Marco Marchetti", "relationship": "Brother", "phone_e164": "+13055550142", "alternate_phone_e164": "+13055550142", "email": "alex.rivera@northwindlive.example", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/EmergencyContact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/emergency-contacts/{id}": { "get": { "operationId": "emergencyContacts.get", "tags": ["Identity"], "x-xos-table": "app.person_emergency_contacts", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get an emergency contact", "description": "One of the caller's emergency contacts (Section 4.5.6 item 10), in calling order, at most five (422 emergency_contact_limit). Phones are E.164 (Section 15). Shared with an engagement under the Emergency Contacts category. Returns one emergency contact with its `ETag`. A emergency contact the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the emergency contact.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the emergency contact.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The emergency contact.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "full_name": "Marco Marchetti", "relationship": "Brother", "phone_e164": "+13055550142", "alternate_phone_e164": "+13055550142", "email": "alex.rivera@northwindlive.example", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/EmergencyContact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "emergencyContacts.update", "tags": ["Identity"], "x-xos-table": "app.person_emergency_contacts", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update an emergency contact", "description": "One of the caller's emergency contacts (Section 4.5.6 item 10), in calling order, at most five (422 emergency_contact_limit). Phones are E.164 (Section 15). Shared with an engagement under the Emergency Contacts category. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the emergency contact.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the emergency contact.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "full_name": "Marco Marchetti", "relationship": "Brother", "phone_e164": "+13055550142", "alternate_phone_e164": "+13055550142", "email": "alex.rivera@northwindlive.example", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/EmergencyContactUpdate" } } } }, "responses": { "200": { "description": "The updated emergency contact.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "full_name": "Marco Marchetti", "relationship": "Brother", "phone_e164": "+13055550142", "alternate_phone_e164": "+13055550142", "email": "alex.rivera@northwindlive.example", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/EmergencyContact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "emergencyContacts.delete", "tags": ["Identity"], "x-xos-table": "app.person_emergency_contacts", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete an emergency contact", "description": "One of the caller's emergency contacts (Section 4.5.6 item 10), in calling order, at most five (422 emergency_contact_limit). Phones are E.164 (Section 15). Shared with an engagement under the Emergency Contacts category. Soft-deletes the emergency contact: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the emergency contact.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the emergency contact.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The emergency contact moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/loyalty-programs": { "get": { "operationId": "loyaltyPrograms.list", "tags": ["Identity"], "x-xos-table": "app.person_loyalty_programs", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["sort_order", "created_at"], "numeric": false }, "summary": "List loyalty program rows", "description": "A travel loyalty program the caller belongs to, at most twenty (422 loyalty_program_limit). A program name appears once per kind (409). Shared with an engagement under the Travel Profile category. Returns a cursor page of loyalty program rows the caller may see. The default order is `sort_order`, then `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of loyalty program rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "program_kind": "Airline", "program_name": "SkyMiles", "member_number": "SM-0000-TEST", "sort_order": 0 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/LoyaltyProgramPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "loyaltyPrograms.create", "tags": ["Identity"], "x-xos-table": "app.person_loyalty_programs", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a loyalty program", "description": "A travel loyalty program the caller belongs to, at most twenty (422 loyalty_program_limit). A program name appears once per kind (409). Shared with an engagement under the Travel Profile category. Creates a loyalty program. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "program_kind": "Airline", "program_name": "SkyMiles", "member_number": "SM-0000-TEST", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/LoyaltyProgramCreate" } } } }, "responses": { "201": { "description": "The created loyalty program.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "program_kind": "Airline", "program_name": "SkyMiles", "member_number": "SM-0000-TEST", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/LoyaltyProgram" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/loyalty-programs/{id}": { "get": { "operationId": "loyaltyPrograms.get", "tags": ["Identity"], "x-xos-table": "app.person_loyalty_programs", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a loyalty program", "description": "A travel loyalty program the caller belongs to, at most twenty (422 loyalty_program_limit). A program name appears once per kind (409). Shared with an engagement under the Travel Profile category. Returns one loyalty program with its `ETag`. A loyalty program the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the loyalty program.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the loyalty program.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The loyalty program.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "program_kind": "Airline", "program_name": "SkyMiles", "member_number": "SM-0000-TEST", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/LoyaltyProgram" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "loyaltyPrograms.update", "tags": ["Identity"], "x-xos-table": "app.person_loyalty_programs", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a loyalty program", "description": "A travel loyalty program the caller belongs to, at most twenty (422 loyalty_program_limit). A program name appears once per kind (409). Shared with an engagement under the Travel Profile category. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the loyalty program.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the loyalty program.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "program_kind": "Airline", "program_name": "SkyMiles", "member_number": "SM-0000-TEST", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/LoyaltyProgramUpdate" } } } }, "responses": { "200": { "description": "The updated loyalty program.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "program_kind": "Airline", "program_name": "SkyMiles", "member_number": "SM-0000-TEST", "sort_order": 0 }, "schema": { "$ref": "#/components/schemas/LoyaltyProgram" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "loyaltyPrograms.delete", "tags": ["Identity"], "x-xos-table": "app.person_loyalty_programs", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a loyalty program", "description": "A travel loyalty program the caller belongs to, at most twenty (422 loyalty_program_limit). A program name appears once per kind (409). Shared with an engagement under the Travel Profile category. Soft-deletes the loyalty program: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the loyalty program.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the loyalty program.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The loyalty program moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-detail-shares": { "get": { "operationId": "workDetailShares.list", "tags": ["Identity"], "x-xos-table": "app.work_detail_shares", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List work detail share rows", "description": "The caller's consent to share chosen categories of their work details with the org that engages them, for one engagement, under a work_details_sharing consent record (Section 14.3). Creating a share for an engagement that already has one replaces its categories; fewer categories is a partial revocation. Revoke ends it at once and withdraws the org's consent with its last share. Shares cannot be made once the engagement is Complete or Canceled (422 work_detail_share_closed). The person and the engaging org read shares; only the person writes them. Returns a cursor page of work detail share rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of work detail share rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "consent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "categories": ["Dietary Needs", "Emergency Contacts"], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkDetailSharePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workDetailShares.create", "tags": ["Identity"], "x-xos-table": "app.work_detail_shares", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a work detail share", "description": "The caller's consent to share chosen categories of their work details with the org that engages them, for one engagement, under a work_details_sharing consent record (Section 14.3). Creating a share for an engagement that already has one replaces its categories; fewer categories is a partial revocation. Revoke ends it at once and withdraws the org's consent with its last share. Shares cannot be made once the engagement is Complete or Canceled (422 work_detail_share_closed). The person and the engaging org read shares; only the person writes them. Creates a work detail share. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "categories": ["Dietary Needs", "Emergency Contacts"] }, "schema": { "$ref": "#/components/schemas/WorkDetailShareCreate" } } } }, "responses": { "201": { "description": "The created work detail share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "consent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "categories": ["Dietary Needs", "Emergency Contacts"], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkDetailShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-detail-shares/{id}": { "get": { "operationId": "workDetailShares.get", "tags": ["Identity"], "x-xos-table": "app.work_detail_shares", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "summary": "Get a work detail share", "description": "The caller's consent to share chosen categories of their work details with the org that engages them, for one engagement, under a work_details_sharing consent record (Section 14.3). Creating a share for an engagement that already has one replaces its categories; fewer categories is a partial revocation. Revoke ends it at once and withdraws the org's consent with its last share. Shares cannot be made once the engagement is Complete or Canceled (422 work_detail_share_closed). The person and the engaging org read shares; only the person writes them. Returns one work detail share with its `ETag`. A work detail share the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work detail share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work detail share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The work detail share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "consent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "categories": ["Dietary Needs", "Emergency Contacts"], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkDetailShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "workDetailShares.update", "tags": ["Identity"], "x-xos-table": "app.work_detail_shares", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a work detail share", "description": "The caller's consent to share chosen categories of their work details with the org that engages them, for one engagement, under a work_details_sharing consent record (Section 14.3). Creating a share for an engagement that already has one replaces its categories; fewer categories is a partial revocation. Revoke ends it at once and withdraws the org's consent with its last share. Shares cannot be made once the engagement is Complete or Canceled (422 work_detail_share_closed). The person and the engaging org read shares; only the person writes them. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work detail share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work detail share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "categories": ["Dietary Needs", "Emergency Contacts"] }, "schema": { "$ref": "#/components/schemas/WorkDetailShareUpdate" } } } }, "responses": { "200": { "description": "The updated work detail share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "consent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "categories": ["Dietary Needs", "Emergency Contacts"], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkDetailShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-detail-shares/{id}/revoke": { "post": { "operationId": "workDetailShares.revoke", "tags": ["Identity"], "x-xos-table": "app.work_detail_shares", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.revoke_work_detail_share", "summary": "Revoke a work details share", "description": "Ends the share at once through `app.revoke_work_detail_share`; the org reads nothing more, and its work_details_sharing consent is withdrawn when this was its last live share. Only the person who gave it revokes it (422 work_detail_share_not_yours). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work detail share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work detail share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "consent_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "categories": ["Dietary Needs", "Emergency Contacts"], "shared_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkDetailShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-detail-shares/{id}/details": { "get": { "operationId": "workDetailShares.details", "tags": ["Identity"], "x-xos-table": "app.work_detail_shares", "x-xos-capability": "opportunities.engagement.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["opportunities"] }], "x-xos-rpc": "app.shared_work_details", "summary": "Read what the share's person shared", "description": "For a member of the engaging org: the shared categories the caller's project capabilities cover (safety readers and engagement editors for emergency contacts, engagement readers and shift editors for uniform sizes, hospitality readers for the rest), through `app.shared_work_details`. Nothing is returned once the share is revoked or the engagement is Complete or Canceled. The passport number is always masked. Each read is logged in the person's access log and the org's audit ledger. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work detail share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work detail share.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "work_detail_share_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shared_at": "2026-10-08T14:30:00Z", "sharing_open": true, "categories": ["Dietary Needs"], "readable": ["Dietary Needs"], "emergency_contacts": [ { "full_name": "Marco Marchetti", "relationship": "Brother", "phone_e164": "+13055550142", "alternate_phone_e164": "+13055550142", "email": "marco@example.com", "sort_order": 0 } ], "uniform": { "shirt_size": "XXS", "jacket_size": "XXS", "pants_size": "32x32", "shoe_size": "US 10.5", "glove_size": "XXS", "hat_size": "7 1/4", "uniform_notes": "Prefers a relaxed cut." }, "dietary": { "dietary_needs": ["Vegetarian"], "allergies": "Peanuts, severe", "dietary_notes": "No pork." }, "accessibility": { "accessibility_needs": ["Step-Free Access"], "accessibility_notes": "Needs a seat near the stage door." }, "travel": { "seat_preference": "Window", "meal_preference": "Vegetarian (VGML)", "home_airport": "MIA", "loyalty_programs": [ { "program_kind": "Airline", "program_name": "SkyMiles", "member_number": "SM-0000-TEST" } ] }, "passport": { "passport_number": null, "passport_number_last4": "TEST", "passport_number_masked": true, "passport_issuing_country": "US", "passport_expires_on": "2026-10-08", "passport_name": "IVY MARCHETTI" } }, "schema": { "$ref": "#/components/schemas/SharedWorkDetails" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-detail-shares/{id}/reveal-passport": { "post": { "operationId": "workDetailShares.revealPassport", "tags": ["Identity"], "x-xos-table": "app.work_detail_shares", "x-xos-capability": "data.restricted.read.government_id", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-rpc": "app.reveal_shared_passport_number", "summary": "Reveal a shared passport number", "description": "For a member of the engaging org: returns the passport number through `app.reveal_shared_passport_number`. Needs a live share naming Passport on an open engagement, hospitality.fulfillment.read on the project, data.restricted.read.government_id in the org, step-up authentication (422 step_up_required) and a reason (422 passport_reveal_reason). Logged with the reason, never the value. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the work detail share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the work detail share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Booking the June flights." }, "schema": { "$ref": "#/components/schemas/PassportRevealRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "passport_number": "YA0000TEST" }, "schema": { "$ref": "#/components/schemas/PassportReveal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/work-detail-events": { "get": { "operationId": "workDetailEvents.list", "tags": ["Identity"], "x-xos-table": "app.work_detail_events", "x-xos-capability": "me.work_details.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false, "descending": true }, "summary": "List work detail event rows", "description": "One entry of a person's work details access log (Section 8.4): a change they made, a share or revocation, or a read or reveal by an engaging org, with the categories and changed column names but never a value. The person reads all of theirs; an org's audit readers read the entries naming their org. Returns a cursor page of work detail event rows the caller may see. The default order is `created_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of work detail event rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "actor_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "engagement_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "action": "work_details.viewed", "categories": ["Dietary Needs"], "changed_columns": ["allergies"], "reason": "Booking the June flights.", "created_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkDetailEventPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-view-shares": { "get": { "operationId": "savedViewShares.list", "tags": ["Platform"], "x-xos-table": "app.saved_view_shares", "x-xos-capability": "my_work.items.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["my_work"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List saved view share rows", "description": "A saved view shared with one team of its org (0641). Only the view's owner shares or unshares it; team members open it and see only the rows their own access allows. Returns a cursor page of saved view share rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of saved view share rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SavedViewSharePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "savedViewShares.create", "tags": ["Platform"], "x-xos-table": "app.saved_view_shares", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a saved view share", "description": "A saved view shared with one team of its org (0641). Only the view's owner shares or unshares it; team members open it and see only the rows their own access allows. Creates a saved view share. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SavedViewShareCreate" } } } }, "responses": { "201": { "description": "The created saved view share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SavedViewShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-view-shares/{id}": { "get": { "operationId": "savedViewShares.get", "tags": ["Platform"], "x-xos-table": "app.saved_view_shares", "x-xos-capability": "my_work.items.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["my_work"] }], "summary": "Get a saved view share", "description": "A saved view shared with one team of its org (0641). Only the view's owner shares or unshares it; team members open it and see only the rows their own access allows. Returns one saved view share with its `ETag`. A saved view share the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved view share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved view share.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The saved view share.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SavedViewShare" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "savedViewShares.delete", "tags": ["Platform"], "x-xos-table": "app.saved_view_shares", "x-xos-capability": "org.views.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a saved view share", "description": "A saved view shared with one team of its org (0641). Only the view's owner shares or unshares it; team members open it and see only the rows their own access allows. Soft-deletes the saved view share: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved view share.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved view share.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The saved view share moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-view-defaults": { "get": { "operationId": "savedViewDefaults.list", "tags": ["Platform"], "x-xos-table": "app.saved_view_defaults", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List saved view default rows", "description": "The saved view the caller opens by default on a page (0641): one per member and collection. Creating one replaces the earlier default of the page (app.set_saved_view_default). Returns a cursor page of saved view default rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of saved view default rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "logistics/shipments", "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SavedViewDefaultPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "savedViewDefaults.create", "tags": ["Platform"], "x-xos-table": "app.saved_view_defaults", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a saved view default", "description": "The saved view the caller opens by default on a page (0641): one per member and collection. Creating one replaces the earlier default of the page (app.set_saved_view_default). Creates a saved view default. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SavedViewDefaultCreate" } } } }, "responses": { "201": { "description": "The created saved view default.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "logistics/shipments", "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SavedViewDefault" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/saved-view-defaults/{id}": { "get": { "operationId": "savedViewDefaults.get", "tags": ["Platform"], "x-xos-table": "app.saved_view_defaults", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a saved view default", "description": "The saved view the caller opens by default on a page (0641): one per member and collection. Creating one replaces the earlier default of the page (app.set_saved_view_default). Returns one saved view default with its `ETag`. A saved view default the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved view default.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved view default.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The saved view default.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "collection_key": "logistics/shipments", "saved_view_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SavedViewDefault" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "savedViewDefaults.delete", "tags": ["Platform"], "x-xos-table": "app.saved_view_defaults", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a saved view default", "description": "The saved view the caller opens by default on a page (0641): one per member and collection. Creating one replaces the earlier default of the page (app.set_saved_view_default). Soft-deletes the saved view default: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the saved view default.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the saved view default.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The saved view default moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tour-progress": { "get": { "operationId": "tourProgress.list", "tags": ["Platform"], "x-xos-table": "app.tour_progress", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List tour progress rows", "description": "The caller's progress through one guided tour (0642). A tour is offered once (the row exists from then on), can be replayed by moving it to Started at step 0, and is never offered again. Returns a cursor page of tour progress rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of tour progress rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tour_key": "atlas.getting-started", "tour_state": "Started", "step": 2 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TourProgressPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "tourProgress.create", "tags": ["Platform"], "x-xos-table": "app.tour_progress", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a tour progress", "description": "The caller's progress through one guided tour (0642). A tour is offered once (the row exists from then on), can be replayed by moving it to Started at step 0, and is never offered again. Creates a tour progress. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "tour_key": "atlas.getting-started", "tour_state": "Started", "step": 2 }, "schema": { "$ref": "#/components/schemas/TourProgressCreate" } } } }, "responses": { "201": { "description": "The created tour progress.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tour_key": "atlas.getting-started", "tour_state": "Started", "step": 2 }, "schema": { "$ref": "#/components/schemas/TourProgress" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tour-progress/{id}": { "get": { "operationId": "tourProgress.get", "tags": ["Platform"], "x-xos-table": "app.tour_progress", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a tour progress", "description": "The caller's progress through one guided tour (0642). A tour is offered once (the row exists from then on), can be replayed by moving it to Started at step 0, and is never offered again. Returns one tour progress with its `ETag`. A tour progress the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tour progress.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tour progress.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The tour progress.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tour_key": "atlas.getting-started", "tour_state": "Started", "step": 2 }, "schema": { "$ref": "#/components/schemas/TourProgress" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "tourProgress.update", "tags": ["Platform"], "x-xos-table": "app.tour_progress", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Update a tour progress", "description": "The caller's progress through one guided tour (0642). A tour is offered once (the row exists from then on), can be replayed by moving it to Started at step 0, and is never offered again. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tour progress.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tour progress.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "tour_state": "Started", "step": 2 }, "schema": { "$ref": "#/components/schemas/TourProgressUpdate" } } } }, "responses": { "200": { "description": "The updated tour progress.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tour_key": "atlas.getting-started", "tour_state": "Started", "step": 2 }, "schema": { "$ref": "#/components/schemas/TourProgress" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tip-dismissals": { "get": { "operationId": "tipDismissals.list", "tags": ["Platform"], "x-xos-table": "app.tip_dismissals", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List tip dismissal rows", "description": "A contextual tip the caller dismissed (0642). Deleting it shows the tip again; a reset dismissal is never revived. Returns a cursor page of tip dismissal rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of tip dismissal rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tip_key": "gates" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TipDismissalPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "tipDismissals.create", "tags": ["Platform"], "x-xos-table": "app.tip_dismissals", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Create a tip dismissal", "description": "A contextual tip the caller dismissed (0642). Deleting it shows the tip again; a reset dismissal is never revived. Creates a tip dismissal. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "tip_key": "gates" }, "schema": { "$ref": "#/components/schemas/TipDismissalCreate" } } } }, "responses": { "201": { "description": "The created tip dismissal.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tip_key": "gates" }, "schema": { "$ref": "#/components/schemas/TipDismissal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tip-dismissals/{id}": { "get": { "operationId": "tipDismissals.get", "tags": ["Platform"], "x-xos-table": "app.tip_dismissals", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a tip dismissal", "description": "A contextual tip the caller dismissed (0642). Deleting it shows the tip again; a reset dismissal is never revived. Returns one tip dismissal with its `ETag`. A tip dismissal the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tip dismissal.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tip dismissal.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The tip dismissal.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "tip_key": "gates" }, "schema": { "$ref": "#/components/schemas/TipDismissal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "tipDismissals.delete", "tags": ["Platform"], "x-xos-table": "app.tip_dismissals", "x-xos-capability": "me.preferences.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a tip dismissal", "description": "A contextual tip the caller dismissed (0642). Deleting it shows the tip again; a reset dismissal is never revived. Soft-deletes the tip dismissal: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the tip dismissal.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the tip dismissal.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The tip dismissal moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-tickets": { "get": { "operationId": "supportTickets.list", "tags": ["Platform"], "x-xos-table": "app.support_tickets", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List support ticket rows", "description": "A request for help (0643): to the org's own admins (Organization queue) or, from holders of org.help.write, to the platform team (Platform queue), whose channel and first response deadline follow the plan. Readable by the requester and by those who answer support for the org. Returns a cursor page of support ticket rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of support ticket rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "queue": "Organization", "category": "Access", "severity": "Severity 3", "subject": "Scanner shows an unknown zone", "body": "At the north gate the scanner says the zone is unknown.", "ticket_state": "Open", "channel": "In App", "first_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SupportTicketPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "supportTickets.open", "tags": ["Platform"], "x-xos-table": "app.support_tickets", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "open_support_ticket", "summary": "Open a support request", "description": "Opens a request as the caller (app.open_support_ticket). The Platform queue needs org.help.write and a plan with a platform channel (support_platform_admins_only, support_plan_no_channel: 422); diagnostics need consent (support_diagnostics_consent). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "queue": "Organization", "category": "Access", "severity": "Severity 3", "subject": "Scanner shows an unknown zone", "body": "Zone B denies Crew.", "diagnostics": { "consent": true, "route": "/demo/credentials/scans", "app_version": "4.0.0 (812)", "device": "Safari 19 on iOS 26", "recent_errors": "TypeError" } }, "schema": { "$ref": "#/components/schemas/SupportTicketOpenRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "queue": "Organization", "category": "Access", "severity": "Severity 3", "subject": "Scanner shows an unknown zone", "body": "At the north gate the scanner says the zone is unknown.", "ticket_state": "Open", "channel": "In App", "first_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SupportTicket" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-tickets/{id}": { "get": { "operationId": "supportTickets.get", "tags": ["Platform"], "x-xos-table": "app.support_tickets", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a support ticket", "description": "A request for help (0643): to the org's own admins (Organization queue) or, from holders of org.help.write, to the platform team (Platform queue), whose channel and first response deadline follow the plan. Readable by the requester and by those who answer support for the org. Returns one support ticket with its `ETag`. A support ticket the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the support ticket.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The support ticket.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "queue": "Organization", "category": "Access", "severity": "Severity 3", "subject": "Scanner shows an unknown zone", "body": "At the north gate the scanner says the zone is unknown.", "ticket_state": "Open", "channel": "In App", "first_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SupportTicket" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-tickets/{id}/transition": { "post": { "operationId": "supportTickets.transition", "tags": ["Platform"], "x-xos-table": "app.support_tickets", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "transition_support_ticket", "summary": "Move a support request", "description": "Moves a request with a reason (app.transition_support_ticket). Responders make any allowed move; the requester closes, reopens a resolved request or takes back a waiting one (support_ticket_transition_forbidden: 422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the support ticket.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Open", "to_state": "Waiting", "reason": "Client approved the revised scope." }, "schema": { "$ref": "#/components/schemas/SupportTicketTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "queue": "Organization", "category": "Access", "severity": "Severity 3", "subject": "Scanner shows an unknown zone", "body": "At the north gate the scanner says the zone is unknown.", "ticket_state": "Open", "channel": "In App", "first_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/SupportTicket" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-tickets/{id}/reply": { "post": { "operationId": "supportTickets.reply", "tags": ["Platform"], "x-xos-table": "app.support_tickets", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "post_support_message", "summary": "Reply on a support request", "description": "Adds a message as the requester or a responder (app.post_support_message). A closed request takes no messages (support_ticket_closed: 422); a requester's reply reopens a waiting request. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the support ticket.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "body": "Zone B, backstage." }, "schema": { "$ref": "#/components/schemas/SupportTicketReplyRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "support_ticket_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Which zone did you pick?" }, "schema": { "$ref": "#/components/schemas/SupportTicketMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-ticket-messages": { "get": { "operationId": "supportTicketMessages.list", "tags": ["Platform"], "x-xos-table": "app.support_ticket_messages", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List support ticket message rows", "description": "One message on a support request (0643), oldest first. Append-only; posted with the reply action. Returns a cursor page of support ticket message rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of support ticket message rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "support_ticket_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Which zone did you pick?" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SupportTicketMessagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-ticket-messages/{id}": { "get": { "operationId": "supportTicketMessages.get", "tags": ["Platform"], "x-xos-table": "app.support_ticket_messages", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a support ticket message", "description": "One message on a support request (0643), oldest first. Append-only; posted with the reply action. Returns one support ticket message with its `ETag`. A support ticket message the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the support ticket message.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The support ticket message.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "support_ticket_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "body": "Which zone did you pick?" }, "schema": { "$ref": "#/components/schemas/SupportTicketMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-ticket-diagnostics": { "get": { "operationId": "supportTicketDiagnostics.list", "tags": ["Platform"], "x-xos-table": "app.support_ticket_diagnostics", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List support ticket diagnostics rows", "description": "Diagnostics the requester chose to attach to a support request (0643), with the moment they consented. Append-only. Returns a cursor page of support ticket diagnostics rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of support ticket diagnostics rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "support_ticket_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "consented_at": "2026-10-08T14:30:00Z", "route": "/demo/credentials/scans", "app_version": "4.0.0 (812)", "device": "Safari 19 on iOS 26", "recent_errors": "TypeError", "screenshot_path": "org/ticket/shot.png" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SupportTicketDiagnosticsPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-ticket-diagnostics/{id}": { "get": { "operationId": "supportTicketDiagnostics.get", "tags": ["Platform"], "x-xos-table": "app.support_ticket_diagnostics", "x-xos-capability": "me.account.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a support ticket diagnostics", "description": "Diagnostics the requester chose to attach to a support request (0643), with the moment they consented. Append-only. Returns one support ticket diagnostics with its `ETag`. A support ticket diagnostics the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the support ticket diagnostics.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the support ticket diagnostics.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The support ticket diagnostics.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "support_ticket_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "consented_at": "2026-10-08T14:30:00Z", "route": "/demo/credentials/scans", "app_version": "4.0.0 (812)", "device": "Safari 19 on iOS 26", "recent_errors": "TypeError", "screenshot_path": "org/ticket/shot.png" }, "schema": { "$ref": "#/components/schemas/SupportTicketDiagnostics" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-steps": { "get": { "operationId": "approvalSteps.list", "tags": ["Platform"], "x-xos-table": "app.approval_steps", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["approval_policy_id", "step_order"], "numeric": false }, "summary": "List approval step rows", "description": "An ordered step of an approval policy (1030). It names its approvers: everyone holding a role, or one member. Steps change only while the policy is a Draft (approval_step_policy_not_draft: 422). Returns a cursor page of approval step rows the caller may see. The default order is `approval_policy_id`, then `step_order` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of approval step rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "step_order": 1, "name": "Department head", "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approver_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ApprovalStepPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "approvalSteps.create", "tags": ["Platform"], "x-xos-table": "app.approval_steps", "x-xos-capability": "org.approval_policies.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an approval step", "description": "An ordered step of an approval policy (1030). It names its approvers: everyone holding a role, or one member. Steps change only while the policy is a Draft (approval_step_policy_not_draft: 422). Creates an approval step. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "step_order": 1, "name": "Department head", "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approver_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApprovalStepCreate" } } } }, "responses": { "201": { "description": "The created approval step.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "step_order": 1, "name": "Department head", "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approver_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApprovalStep" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/approval-steps/{id}": { "get": { "operationId": "approvalSteps.get", "tags": ["Platform"], "x-xos-table": "app.approval_steps", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an approval step", "description": "An ordered step of an approval policy (1030). It names its approvers: everyone holding a role, or one member. Steps change only while the policy is a Draft (approval_step_policy_not_draft: 422). Returns one approval step with its `ETag`. A approval step the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval step.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The approval step.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "step_order": 1, "name": "Department head", "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approver_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApprovalStep" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "approvalSteps.update", "tags": ["Platform"], "x-xos-table": "app.approval_steps", "x-xos-capability": "org.approval_policies.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an approval step", "description": "An ordered step of an approval policy (1030). It names its approvers: everyone holding a role, or one member. Steps change only while the policy is a Draft (approval_step_policy_not_draft: 422). Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval step.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "step_order": 1, "name": "Department head", "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approver_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApprovalStepUpdate" } } } }, "responses": { "200": { "description": "The updated approval step.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approval_policy_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "step_order": 1, "name": "Department head", "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "approver_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ApprovalStep" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "approvalSteps.delete", "tags": ["Platform"], "x-xos-table": "app.approval_steps", "x-xos-capability": "org.approval_policies.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an approval step", "description": "An ordered step of an approval policy (1030). It names its approvers: everyone holding a role, or one member. Steps change only while the policy is a Draft (approval_step_policy_not_draft: 422). Soft-deletes the approval step: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the approval step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the approval step.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The approval step moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/template-versions": { "get": { "operationId": "templateVersions.list", "tags": ["Platform"], "x-xos-table": "app.template_versions", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["template_id", "version_number"], "numeric": false }, "summary": "List template version rows", "description": "A version of a template (1032): the project defaults and ordered items. Edited while a draft; publishing (templateVersions.publish) freezes it and makes it the template's current version. Returns a cursor page of template version rows the caller may see. The default order is `template_id`, then `version_number` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of template version rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 1, "notes": "Adds the load-out records.", "default_time_zone": "America/New_York", "default_tier_code": "05", "default_region_code": "SE", "default_jurisdiction_id": "US-FL-MIAMI-DADE", "default_currency_code": "USD", "duration_days": 3, "published_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TemplateVersionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "templateVersions.create", "tags": ["Platform"], "x-xos-table": "app.template_versions", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a template version", "description": "A version of a template (1032): the project defaults and ordered items. Edited while a draft; publishing (templateVersions.publish) freezes it and makes it the template's current version. Creates a template version. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "notes": "Adds the load-out records.", "default_time_zone": "America/New_York", "default_tier_code": "05", "default_region_code": "SE", "default_jurisdiction_id": "US-FL-MIAMI-DADE", "default_currency_code": "USD", "duration_days": 3 }, "schema": { "$ref": "#/components/schemas/TemplateVersionCreate" } } } }, "responses": { "201": { "description": "The created template version.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 1, "notes": "Adds the load-out records.", "default_time_zone": "America/New_York", "default_tier_code": "05", "default_region_code": "SE", "default_jurisdiction_id": "US-FL-MIAMI-DADE", "default_currency_code": "USD", "duration_days": 3, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TemplateVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/template-versions/{id}": { "get": { "operationId": "templateVersions.get", "tags": ["Platform"], "x-xos-table": "app.template_versions", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a template version", "description": "A version of a template (1032): the project defaults and ordered items. Edited while a draft; publishing (templateVersions.publish) freezes it and makes it the template's current version. Returns one template version with its `ETag`. A template version the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template version.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The template version.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 1, "notes": "Adds the load-out records.", "default_time_zone": "America/New_York", "default_tier_code": "05", "default_region_code": "SE", "default_jurisdiction_id": "US-FL-MIAMI-DADE", "default_currency_code": "USD", "duration_days": 3, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TemplateVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "templateVersions.update", "tags": ["Platform"], "x-xos-table": "app.template_versions", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a template version", "description": "A version of a template (1032): the project defaults and ordered items. Edited while a draft; publishing (templateVersions.publish) freezes it and makes it the template's current version. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template version.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "notes": "Adds the load-out records.", "default_time_zone": "America/New_York", "default_tier_code": "05", "default_region_code": "SE", "default_jurisdiction_id": "US-FL-MIAMI-DADE", "default_currency_code": "USD", "duration_days": 3 }, "schema": { "$ref": "#/components/schemas/TemplateVersionUpdate" } } } }, "responses": { "200": { "description": "The updated template version.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 1, "notes": "Adds the load-out records.", "default_time_zone": "America/New_York", "default_tier_code": "05", "default_region_code": "SE", "default_jurisdiction_id": "US-FL-MIAMI-DADE", "default_currency_code": "USD", "duration_days": 3, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TemplateVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "templateVersions.delete", "tags": ["Platform"], "x-xos-table": "app.template_versions", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a template version", "description": "A version of a template (1032): the project defaults and ordered items. Edited while a draft; publishing (templateVersions.publish) freezes it and makes it the template's current version. Soft-deletes the template version: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template version.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The template version moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/template-versions/{id}/publish": { "post": { "operationId": "templateVersions.publish", "tags": ["Platform"], "x-xos-table": "app.template_versions", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-rpc": "publish_template_version", "summary": "Publish a template version", "description": "Publishes a draft version (app.publish_template_version, projects.template.write): freezes it and makes it the template's current version. A published version answers 422 (template_version_published). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template version.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template version.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "version_number": 1, "notes": "Adds the load-out records.", "default_time_zone": "America/New_York", "default_tier_code": "05", "default_region_code": "SE", "default_jurisdiction_id": "US-FL-MIAMI-DADE", "default_currency_code": "USD", "duration_days": 3, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/TemplateVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/template-items": { "get": { "operationId": "templateItems.list", "tags": ["Platform"], "x-xos-table": "app.template_items", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["template_version_id", "sort_order"], "numeric": false }, "summary": "List template item rows", "description": "An item of a template version (1032): a scope node created under the new project's engagement root ({KEY}-{suffix}), or a record due a number of days after the project start. Items of a published version are frozen (template_version_published: 422). Returns a cursor page of template item rows the caller may see. The default order is `template_version_id`, then `sort_order` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of template item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_kind": "Scope Node", "sort_order": 1, "name": "Opening Night", "scope_kind": "Show", "scope_code_suffix": "E02", "record_kind": "Inspection", "xyz": "X", "phase_code": "SCP", "due_offset_days": 3 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TemplateItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "templateItems.create", "tags": ["Platform"], "x-xos-table": "app.template_items", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Create a template item", "description": "An item of a template version (1032): a scope node created under the new project's engagement root ({KEY}-{suffix}), or a record due a number of days after the project start. Items of a published version are frozen (template_version_published: 422). Creates a template item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_kind": "Scope Node", "sort_order": 1, "name": "Opening Night", "scope_kind": "Show", "scope_code_suffix": "E02", "record_kind": "Inspection", "xyz": "X", "phase_code": "SCP", "due_offset_days": 3 }, "schema": { "$ref": "#/components/schemas/TemplateItemCreate" } } } }, "responses": { "201": { "description": "The created template item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_kind": "Scope Node", "sort_order": 1, "name": "Opening Night", "scope_kind": "Show", "scope_code_suffix": "E02", "record_kind": "Inspection", "xyz": "X", "phase_code": "SCP", "due_offset_days": 3 }, "schema": { "$ref": "#/components/schemas/TemplateItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/template-items/{id}": { "get": { "operationId": "templateItems.get", "tags": ["Platform"], "x-xos-table": "app.template_items", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a template item", "description": "An item of a template version (1032): a scope node created under the new project's engagement root ({KEY}-{suffix}), or a record due a number of days after the project start. Items of a published version are frozen (template_version_published: 422). Returns one template item with its `ETag`. A template item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The template item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_kind": "Scope Node", "sort_order": 1, "name": "Opening Night", "scope_kind": "Show", "scope_code_suffix": "E02", "record_kind": "Inspection", "xyz": "X", "phase_code": "SCP", "due_offset_days": 3 }, "schema": { "$ref": "#/components/schemas/TemplateItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "templateItems.update", "tags": ["Platform"], "x-xos-table": "app.template_items", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Update a template item", "description": "An item of a template version (1032): a scope node created under the new project's engagement root ({KEY}-{suffix}), or a record due a number of days after the project start. Items of a published version are frozen (template_version_published: 422). Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "sort_order": 1, "name": "Opening Night", "scope_kind": "Show", "scope_code_suffix": "E02", "record_kind": "Inspection", "xyz": "X", "phase_code": "SCP", "due_offset_days": 3 }, "schema": { "$ref": "#/components/schemas/TemplateItemUpdate" } } } }, "responses": { "200": { "description": "The updated template item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_kind": "Scope Node", "sort_order": 1, "name": "Opening Night", "scope_kind": "Show", "scope_code_suffix": "E02", "record_kind": "Inspection", "xyz": "X", "phase_code": "SCP", "due_offset_days": 3 }, "schema": { "$ref": "#/components/schemas/TemplateItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "templateItems.delete", "tags": ["Platform"], "x-xos-table": "app.template_items", "x-xos-capability": "projects.template.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Delete a template item", "description": "An item of a template version (1032): a scope node created under the new project's engagement root ({KEY}-{suffix}), or a record due a number of days after the project start. Items of a published version are frozen (template_version_published: 422). Soft-deletes the template item: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the template item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the template item.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The template item moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-sessions": { "get": { "operationId": "supportSessions.list", "tags": ["Platform"], "x-xos-table": "app.support_sessions", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List support session rows", "description": "A support session (1060): the client org's Owner lets its partner's staff read the client org for 1 to 24 hours. Partner staff read nothing of a client without one; they never write. Created with supportSessions.grant and ended early with supportSessions.end. Returns a cursor page of support session rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of support session rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Help with the venue import.", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SupportSessionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-sessions/{id}": { "get": { "operationId": "supportSessions.get", "tags": ["Platform"], "x-xos-table": "app.support_sessions", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a support session", "description": "A support session (1060): the client org's Owner lets its partner's staff read the client org for 1 to 24 hours. Partner staff read nothing of a client without one; they never write. Created with supportSessions.grant and ended early with supportSessions.end. Returns one support session with its `ETag`. A support session the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the support session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the support session.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The support session.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Help with the venue import.", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SupportSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-sessions/grant": { "post": { "operationId": "supportSessions.grant", "tags": ["Platform"], "x-xos-table": "app.support_sessions", "x-xos-capability": "org.support_session.grant", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "grant_support_session", "summary": "Grant the partner a support session", "description": "The client org's Owner (org.support_session.grant) lets its partner's staff read the client org for 1 to 24 hours with a reason (app.grant_support_session). One open session at a time (support_session_active: 422); an org without a partner refuses (support_session_no_partner: 422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "hours": 4, "reason": "Help with the venue import." }, "schema": { "$ref": "#/components/schemas/SupportSessionGrantRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Help with the venue import.", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SupportSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/support-sessions/{id}/end": { "post": { "operationId": "supportSessions.end", "tags": ["Platform"], "x-xos-table": "app.support_sessions", "x-xos-capability": "org.support_session.grant", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "end_support_session", "summary": "End a support session early", "description": "Ends an open session at once (app.end_support_session): the client's Owner or the partner's staff with org.partner.manage. An ended session answers 422 (support_session_ended). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the support session.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the support session.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "grantee_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "Help with the venue import.", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SupportSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wholesale-statements": { "get": { "operationId": "wholesaleStatements.list", "tags": ["Platform"], "x-xos-table": "app.wholesale_statements", "x-xos-capability": "org.billing.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["period_start"], "numeric": false, "descending": true }, "summary": "List wholesale statement rows", "description": "What the platform bills a partner for one month (1060): each client org at its plan's list price less the wholesale discount. Totals cover priced lines; unpriced lines are counted, never zero. Append-only. Returns a cursor page of wholesale statement rows the caller may see. The default order is `period_start` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of wholesale statement rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "currency_code": "USD", "wholesale_discount_bps": 3000, "client_count": 3, "list_total_minor": 44700, "wholesale_total_minor": 31290, "unpriced_count": 0 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WholesaleStatementPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wholesale-statements/{id}": { "get": { "operationId": "wholesaleStatements.get", "tags": ["Platform"], "x-xos-table": "app.wholesale_statements", "x-xos-capability": "org.billing.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a wholesale statement", "description": "What the platform bills a partner for one month (1060): each client org at its plan's list price less the wholesale discount. Totals cover priced lines; unpriced lines are counted, never zero. Append-only. Returns one wholesale statement with its `ETag`. A wholesale statement the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the wholesale statement.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the wholesale statement.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The wholesale statement.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "currency_code": "USD", "wholesale_discount_bps": 3000, "client_count": 3, "list_total_minor": 44700, "wholesale_total_minor": 31290, "unpriced_count": 0 }, "schema": { "$ref": "#/components/schemas/WholesaleStatement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wholesale-statements/run": { "post": { "operationId": "wholesaleStatements.run", "tags": ["Platform"], "x-xos-table": "app.wholesale_statements", "x-xos-capability": "org.billing.manage", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "run_wholesale_billing", "summary": "Run wholesale billing for a month", "description": "Records the partner's statement for a month (app.run_wholesale_billing, org.billing.manage): every client org at its plan's list price less the agreed discount. A month is billed once (wholesale_statement_exists: 422); a partner without an agreement refuses (partner_agreement_missing: 422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "period_start": "2026-10-08" }, "schema": { "$ref": "#/components/schemas/WholesaleBillingRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "period_start": "2026-10-08", "currency_code": "USD", "wholesale_discount_bps": 3000, "client_count": 3, "list_total_minor": 44700, "wholesale_total_minor": 31290, "unpriced_count": 0 }, "schema": { "$ref": "#/components/schemas/WholesaleStatement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ownership-transfers": { "get": { "operationId": "ownershipTransfers.list", "tags": ["Platform"], "x-xos-table": "app.ownership_transfers", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["offered_at"], "numeric": false, "descending": true }, "summary": "List ownership transfer rows", "description": "An Owner's offer to hand the org to another active member (1352, Section 14.7). The member accepts with step-up (a second factor) within 7 days; the old Owner then becomes an Admin, or leaves, and the org keeps an Owner at every step. Written only by the transfer actions; audited. Returns a cursor page of ownership transfer rows the caller may see. The default order is `offered_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of ownership transfer rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "previous_owner_outcome": "admin", "offered_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "accepted_at": "2026-10-08T14:30:00Z", "declined_at": "2026-10-08T14:30:00Z", "canceled_at": "2026-10-08T14:30:00Z", "canceled_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expired_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OwnershipTransferPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ownership-transfers/{id}": { "get": { "operationId": "ownershipTransfers.get", "tags": ["Platform"], "x-xos-table": "app.ownership_transfers", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an ownership transfer", "description": "An Owner's offer to hand the org to another active member (1352, Section 14.7). The member accepts with step-up (a second factor) within 7 days; the old Owner then becomes an Admin, or leaves, and the org keeps an Owner at every step. Written only by the transfer actions; audited. Returns one ownership transfer with its `ETag`. A ownership transfer the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ownership transfer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ownership transfer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The ownership transfer.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "previous_owner_outcome": "admin", "offered_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "accepted_at": "2026-10-08T14:30:00Z", "declined_at": "2026-10-08T14:30:00Z", "canceled_at": "2026-10-08T14:30:00Z", "canceled_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expired_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OwnershipTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ownership-transfers/offer": { "post": { "operationId": "ownershipTransfers.offer", "tags": ["Platform"], "x-xos-table": "app.ownership_transfers", "x-xos-capability": "org.ownership.transfer", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "offer_ownership_transfer", "summary": "Offer ownership of the organization", "description": "An Owner (org.ownership.transfer) with step-up offers the bound org to another active member who is not an Owner (app.offer_ownership_transfer), choosing whether they become an Admin or leave on acceptance. One open offer per org; it lapses after 7 days. Without a recent second factor the call answers 422 step_up_required; an API key answers step_up_session_only. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "previous_owner_outcome": "admin" }, "schema": { "$ref": "#/components/schemas/OwnershipTransferOfferRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "previous_owner_outcome": "admin", "offered_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "accepted_at": "2026-10-08T14:30:00Z", "declined_at": "2026-10-08T14:30:00Z", "canceled_at": "2026-10-08T14:30:00Z", "canceled_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expired_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OwnershipTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ownership-transfers/{id}/accept": { "post": { "operationId": "ownershipTransfers.accept", "tags": ["Platform"], "x-xos-table": "app.ownership_transfers", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "accept_ownership_transfer", "summary": "Accept ownership", "description": "The member the org was offered to accepts with step-up, so a second factor (app.accept_ownership_transfer): they become an Owner, then the old Owner becomes an Admin (or leaves) and loses the Owner role, so the org keeps an Owner at every step (invariant 4). An answered, withdrawn or lapsed offer answers 422. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ownership transfer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ownership transfer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "previous_owner_outcome": "admin", "offered_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "accepted_at": "2026-10-08T14:30:00Z", "declined_at": "2026-10-08T14:30:00Z", "canceled_at": "2026-10-08T14:30:00Z", "canceled_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expired_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OwnershipTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ownership-transfers/{id}/decline": { "post": { "operationId": "ownershipTransfers.decline", "tags": ["Platform"], "x-xos-table": "app.ownership_transfers", "x-xos-capability": "org.members.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "decline_ownership_transfer", "summary": "Decline ownership", "description": "The member the org was offered to declines (app.decline_ownership_transfer). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ownership transfer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ownership transfer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "previous_owner_outcome": "admin", "offered_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "accepted_at": "2026-10-08T14:30:00Z", "declined_at": "2026-10-08T14:30:00Z", "canceled_at": "2026-10-08T14:30:00Z", "canceled_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expired_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OwnershipTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ownership-transfers/{id}/cancel": { "post": { "operationId": "ownershipTransfers.cancel", "tags": ["Platform"], "x-xos-table": "app.ownership_transfers", "x-xos-capability": "org.ownership.transfer", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "cancel_ownership_transfer", "summary": "Withdraw an ownership offer", "description": "The Owner who offered, or any Owner, withdraws an open offer (app.cancel_ownership_transfer). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the ownership transfer.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the ownership transfer.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "previous_owner_outcome": "admin", "offered_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "accepted_at": "2026-10-08T14:30:00Z", "declined_at": "2026-10-08T14:30:00Z", "canceled_at": "2026-10-08T14:30:00Z", "canceled_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "expired_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OwnershipTransfer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-deletion-requests": { "get": { "operationId": "orgDeletionRequests.list", "tags": ["Platform"], "x-xos-table": "app.org_deletion_requests", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["requested_at"], "numeric": false, "descending": true }, "summary": "List org deletion request rows", "description": "An Owner's request to delete the org (1351, Section 14.7), separate from cancellation: made with step-up and the typed name, it ends the subscription and makes the org read-only at once; an Owner may recover it for 7 days, after which the data is deleted and the Owner receives a deletion certificate. Returns a cursor page of org deletion request rows the caller may see. The default order is `requested_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of org deletion request rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "We are closing down.", "requested_at": "2026-10-08T14:30:00Z", "recover_until": "2026-10-08T14:30:00Z", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "recovered_at": "2026-10-08T14:30:00Z", "recovered_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OrgDeletionRequestPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-deletion-requests/{id}": { "get": { "operationId": "orgDeletionRequests.get", "tags": ["Platform"], "x-xos-table": "app.org_deletion_requests", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an org deletion request", "description": "An Owner's request to delete the org (1351, Section 14.7), separate from cancellation: made with step-up and the typed name, it ends the subscription and makes the org read-only at once; an Owner may recover it for 7 days, after which the data is deleted and the Owner receives a deletion certificate. Returns one org deletion request with its `ETag`. A org deletion request the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org deletion request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org deletion request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The org deletion request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "We are closing down.", "requested_at": "2026-10-08T14:30:00Z", "recover_until": "2026-10-08T14:30:00Z", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "recovered_at": "2026-10-08T14:30:00Z", "recovered_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/OrgDeletionRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-deletion-requests/request": { "post": { "operationId": "orgDeletionRequests.request", "tags": ["Platform"], "x-xos-table": "app.org_deletion_requests", "x-xos-capability": "org.organization.delete", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "request_org_deletion", "summary": "Ask to delete the organization", "description": "The Owner (org.organization.delete) with step-up types the bound org's name and a reason (app.request_org_deletion). The subscription ends, the org is read-only at once, every Owner is told, and the data is deleted after 7 days unless an Owner recovers it. A partner with clients and an org under a legal hold are refused with 422. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "confirm_name": "Harbor Lights Productions", "reason": "We are closing down." }, "schema": { "$ref": "#/components/schemas/OrgDeletionRequestCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "We are closing down.", "requested_at": "2026-10-08T14:30:00Z", "recover_until": "2026-10-08T14:30:00Z", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "recovered_at": "2026-10-08T14:30:00Z", "recovered_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/OrgDeletionRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/org-deletion-requests/{id}/recover": { "post": { "operationId": "orgDeletionRequests.recover", "tags": ["Platform"], "x-xos-table": "app.org_deletion_requests", "x-xos-capability": "org.organization.delete", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "recover_org_deletion", "summary": "Recover the organization", "description": "An Owner recovers the org within the 7-day window (app.recover_org_deletion): writes work again and, unless the org is also canceled, it restarts on the Access plan. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the org deletion request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the org deletion request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "reason": "We are closing down.", "requested_at": "2026-10-08T14:30:00Z", "recover_until": "2026-10-08T14:30:00Z", "requested_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "recovered_at": "2026-10-08T14:30:00Z", "recovered_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/OrgDeletionRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/deletion-certificates": { "get": { "operationId": "deletionCertificates.list", "tags": ["Platform"], "x-xos-table": "app.deletion_certificates", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["due_at"], "numeric": false, "descending": true }, "summary": "List deletion certificate rows", "description": "The record of an org whose data was deleted (1351, Section 14.7), kept after the org is gone. Read only by the former Owner it was issued to. The PDF itself is downloaded from Atlas. Returns a cursor page of deletion certificate rows the caller may see. The default order is `due_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of deletion certificate rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "deleted_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_name": "Harbor Lights Productions", "org_slug": "harbor-lights", "basis": "cancellation", "requested_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "purged_at": "2026-10-08T14:30:00Z", "tables_purged": 41, "rows_purged": 1820, "storage_objects_deleted": 12, "document_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "issued_at": "2026-10-08T14:30:00Z", "delivered_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DeletionCertificatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/deletion-certificates/{id}": { "get": { "operationId": "deletionCertificates.get", "tags": ["Platform"], "x-xos-table": "app.deletion_certificates", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a deletion certificate", "description": "The record of an org whose data was deleted (1351, Section 14.7), kept after the org is gone. Read only by the former Owner it was issued to. The PDF itself is downloaded from Atlas. Returns one deletion certificate with its `ETag`. A deletion certificate the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the deletion certificate.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the deletion certificate.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The deletion certificate.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "deleted_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_name": "Harbor Lights Productions", "org_slug": "harbor-lights", "basis": "cancellation", "requested_at": "2026-10-08T14:30:00Z", "due_at": "2026-10-08T14:30:00Z", "purged_at": "2026-10-08T14:30:00Z", "tables_purged": 41, "rows_purged": 1820, "storage_objects_deleted": 12, "document_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "issued_at": "2026-10-08T14:30:00Z", "delivered_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/DeletionCertificate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/partner-standing-grants": { "get": { "operationId": "partnerStandingGrants.list", "tags": ["Platform"], "x-xos-table": "app.partner_standing_grants", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["valid_from"], "numeric": false, "descending": true }, "summary": "List partner standing grant rows", "description": "A standing grant of the partner and client agreement (1354, Section 4.6.1): the client Owner lets the partner's staff read one area of the client org until an expiry within a year, citing the clause. Each issues an org-level record grant; either side may end it early. Partner staff never write through one. Returns a cursor page of partner standing grant rows the caller may see. The default order is `valid_from` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of partner standing grant rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "org.settings.read", "agreement_reference": "Partner agreement, clause 7.2", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "record_grant_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PartnerStandingGrantPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/partner-standing-grants/{id}": { "get": { "operationId": "partnerStandingGrants.get", "tags": ["Platform"], "x-xos-table": "app.partner_standing_grants", "x-xos-capability": "org.settings.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get a partner standing grant", "description": "A standing grant of the partner and client agreement (1354, Section 4.6.1): the client Owner lets the partner's staff read one area of the client org until an expiry within a year, citing the clause. Each issues an org-level record grant; either side may end it early. Partner staff never write through one. Returns one partner standing grant with its `ETag`. A partner standing grant the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the partner standing grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the partner standing grant.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The partner standing grant.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "org.settings.read", "agreement_reference": "Partner agreement, clause 7.2", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "record_grant_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PartnerStandingGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/partner-standing-grants/record": { "post": { "operationId": "partnerStandingGrants.record", "tags": ["Platform"], "x-xos-table": "app.partner_standing_grants", "x-xos-capability": "org.support_session.grant", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "record_standing_grant", "summary": "Record a standing partner grant", "description": "The client Owner (org.support_session.grant) records a grant the partner and client agreement provides (app.record_standing_grant): one read capability a support session may grant, an expiry within a year and the clause. A scope outside those, an expiry past a year and an org without a partner answer 422. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "capability_code": "org.settings.read", "valid_to": "2026-10-08T14:30:00Z", "agreement_reference": "Partner agreement, clause 7.2" }, "schema": { "$ref": "#/components/schemas/PartnerStandingGrantRecordRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "org.settings.read", "agreement_reference": "Partner agreement, clause 7.2", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "record_grant_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PartnerStandingGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/partner-standing-grants/{id}/end": { "post": { "operationId": "partnerStandingGrants.end", "tags": ["Platform"], "x-xos-table": "app.partner_standing_grants", "x-xos-capability": "org.support_session.grant", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "end_standing_grant", "summary": "End a standing partner grant", "description": "Ends a standing grant early (app.end_standing_grant): the client's Owner or the partner's staff with org.partner.manage. An ended grant answers 422. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the partner standing grant.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the partner standing grant.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "partner_org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "capability_code": "org.settings.read", "agreement_reference": "Partner agreement, clause 7.2", "valid_from": "2026-10-08T14:30:00Z", "valid_to": "2026-10-08T14:30:00Z", "record_grant_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ended_at": "2026-10-08T14:30:00Z", "ended_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/PartnerStandingGrant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/share-links": { "get": { "operationId": "shareLinks.list", "tags": ["Platform"], "x-xos-table": "app.share_links", "x-xos-capability": "data.export.run", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List share link rows", "description": "A link that opens one clean version of a file without an account (Section 8.6). Public files may have a link without an expiry; Internal links need an expiry within 90 days; Confidential links need an expiry within 30 days, an access code and the recipient's email, which the watermark on every downloaded page carries; Restricted files never get a link. The token and the access code are returned once by `shareLinks.create` and stored only as hashes, so they never appear here. Anyone who can read the file reads its links. Returns a cursor page of share link rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of share link rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attachment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attachment_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "classification": "Restricted", "access_code_required": false, "recipient_email": "alex.rivera@northwindlive.example", "note": "Stage plot for the venue", "expires_at": "2026-10-08T14:30:00Z", "failed_attempts": 0, "open_count": 2, "last_opened_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ShareLinkPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "shareLinks.create", "tags": ["Platform"], "x-xos-table": "app.share_links", "x-xos-capability": "data.export.run", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-rpc": "create_share_link", "summary": "Create a share link", "description": "Makes a link to the current clean version of a file the caller can read, through app.create_share_link. The database applies Section 8.6: Public files may omit `expires_at`; Internal files need one within 90 days; Confidential files need `data.export.confidential`, `expires_at` within 30 days and `recipient_email`, and always get an access code; Restricted files are refused (422 `share_link_restricted`). A Confidential PDF, or an image other than PNG or JPEG, cannot carry the viewer watermark and is refused (422 `share_link_watermark_unsupported`). Answers 201 with the token and access code, shown once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "attachment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_code_required": false, "recipient_email": "alex.rivera@northwindlive.example", "note": "Stage plot for the venue", "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ShareLinkCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "share_link_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token": "xshr_0000000000000000000000000000000000000000000000000000000000000000", "access_code": "042424", "classification": "Restricted", "expires_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ShareLinkToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/share-links/{id}": { "get": { "operationId": "shareLinks.get", "tags": ["Platform"], "x-xos-table": "app.share_links", "x-xos-capability": "data.export.run", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "summary": "Get a share link", "description": "A link that opens one clean version of a file without an account (Section 8.6). Public files may have a link without an expiry; Internal links need an expiry within 90 days; Confidential links need an expiry within 30 days, an access code and the recipient's email, which the watermark on every downloaded page carries; Restricted files never get a link. The token and the access code are returned once by `shareLinks.create` and stored only as hashes, so they never appear here. Anyone who can read the file reads its links. Returns one share link with its `ETag`. A share link the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the share link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the share link.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The share link.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attachment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attachment_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "classification": "Restricted", "access_code_required": false, "recipient_email": "alex.rivera@northwindlive.example", "note": "Stage plot for the venue", "expires_at": "2026-10-08T14:30:00Z", "failed_attempts": 0, "open_count": 2, "last_opened_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShareLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/share-links/{id}/revoke": { "post": { "operationId": "shareLinks.revoke", "tags": ["Platform"], "x-xos-table": "app.share_links", "x-xos-capability": "data.export.run", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["data"] }], "x-xos-rpc": "revoke_share_link", "summary": "Revoke a share link", "description": "Revokes the link through app.revoke_share_link so it never opens again. The person who made it may revoke it, and so may anyone holding `data.export.confidential` in the org. Revoking a revoked link answers it unchanged. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the share link.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the share link.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attachment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attachment_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "classification": "Restricted", "access_code_required": false, "recipient_email": "alex.rivera@northwindlive.example", "note": "Stage plot for the venue", "expires_at": "2026-10-08T14:30:00Z", "failed_attempts": 0, "open_count": 2, "last_opened_at": "2026-10-08T14:30:00Z", "revoked_at": "2026-10-08T14:30:00Z", "revoked_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ShareLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/person-calendar-feeds": { "get": { "operationId": "personCalendarFeeds.list", "tags": ["Platform"], "x-xos-table": "app.person_calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List person calendar feed rows", "description": "A person's own iCalendar feed across every org they work with through an engagement (1410): their published shifts and the meetings, milestones and deadlines shared with them. Only a hash of the token is kept; the token is shown once by personCalendarFeeds.create and personCalendarFeeds.rotate, and deleting the feed revokes it for good. Returns a cursor page of person calendar feed rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of person calendar feed rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token_hint": "a1b2", "last_accessed_at": "2026-10-08T14:30:00Z", "rotated_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PersonCalendarFeedPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "personCalendarFeeds.create", "tags": ["Platform"], "x-xos-table": "app.person_calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.create_person_calendar_feed", "summary": "Create a personal calendar feed", "description": "Creates the caller's own feed across every org they work with (app.create_person_calendar_feed) and returns its token once. At most 20 live feeds (calendar_feed_limit: 422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "calendar_feed_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feed_token": "cal_9fQ2mX4vT7kL1pR8" }, "schema": { "$ref": "#/components/schemas/CalendarFeedToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/person-calendar-feeds/{id}": { "get": { "operationId": "personCalendarFeeds.get", "tags": ["Platform"], "x-xos-table": "app.person_calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Get a person calendar feed", "description": "A person's own iCalendar feed across every org they work with through an engagement (1410): their published shifts and the meetings, milestones and deadlines shared with them. Only a hash of the token is kept; the token is shown once by personCalendarFeeds.create and personCalendarFeeds.rotate, and deleting the feed revokes it for good. Returns one person calendar feed with its `ETag`. A person calendar feed the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the person calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the person calendar feed.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The person calendar feed.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "updated_at": "2026-10-08T14:30:00Z", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "token_hint": "a1b2", "last_accessed_at": "2026-10-08T14:30:00Z", "rotated_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/PersonCalendarFeed" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "personCalendarFeeds.delete", "tags": ["Platform"], "x-xos-table": "app.person_calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "summary": "Delete a person calendar feed", "description": "A person's own iCalendar feed across every org they work with through an engagement (1410): their published shifts and the meetings, milestones and deadlines shared with them. Only a hash of the token is kept; the token is shown once by personCalendarFeeds.create and personCalendarFeeds.rotate, and deleting the feed revokes it for good. Soft-deletes the person calendar feed: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the person calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the person calendar feed.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The person calendar feed moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/person-calendar-feeds/{id}/rotate": { "post": { "operationId": "personCalendarFeeds.rotate", "tags": ["Platform"], "x-xos-table": "app.person_calendar_feeds", "x-xos-capability": "me.calendar_feeds.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["me"] }], "x-xos-rpc": "app.rotate_person_calendar_feed", "summary": "Get a new link for a personal calendar feed", "description": "Replaces the feed's token (app.rotate_person_calendar_feed) and returns the new one once. The old subscription URL answers 404 at once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the person calendar feed.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the person calendar feed.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "calendar_feed_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feed_token": "cal_9fQ2mX4vT7kL1pR8" }, "schema": { "$ref": "#/components/schemas/CalendarFeedToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-inboxes": { "get": { "operationId": "projectInboxes.list", "tags": ["Platform"], "x-xos-table": "app.inbound_addresses", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List project inbox rows", "description": "A project inbox address (0550, 1411): mail forwarded to `@` lands as inbound mail of the project for a coordinator to file. One live address per project; it is never edited, only replaced or disabled. Returns a cursor page of project inbox rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of project inbox rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "local_part": "nwl-0a1b2c3d4e", "disabled_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ProjectInboxPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "projectInboxes.create", "tags": ["Platform"], "x-xos-table": "app.inbound_addresses", "x-xos-capability": "projects.settings.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-rpc": "app.create_project_inbox", "summary": "Create a project's inbox address", "description": "Returns the project's live inbox address, creating it when there is none (app.create_project_inbox, projects.settings.write on the project). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/ProjectInboxCreate" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "local_part": "nwl-0a1b2c3d4e", "disabled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ProjectInbox" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-inboxes/{id}": { "get": { "operationId": "projectInboxes.get", "tags": ["Platform"], "x-xos-table": "app.inbound_addresses", "x-xos-capability": "projects.project.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "summary": "Get a project inbox", "description": "A project inbox address (0550, 1411): mail forwarded to `@` lands as inbound mail of the project for a coordinator to file. One live address per project; it is never edited, only replaced or disabled. Returns one project inbox with its `ETag`. A project inbox the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project inbox.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project inbox.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The project inbox.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "local_part": "nwl-0a1b2c3d4e", "disabled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ProjectInbox" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-inboxes/{id}/replace": { "post": { "operationId": "projectInboxes.replace", "tags": ["Platform"], "x-xos-table": "app.inbound_addresses", "x-xos-capability": "projects.settings.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-rpc": "app.replace_project_inbox", "summary": "Replace a project's inbox address", "description": "Disables the address and returns the project's new one (app.replace_project_inbox). Mail to the old address is no longer accepted. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project inbox.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project inbox.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "local_part": "nwl-0a1b2c3d4e", "disabled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ProjectInbox" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/project-inboxes/{id}/disable": { "post": { "operationId": "projectInboxes.disable", "tags": ["Platform"], "x-xos-table": "app.inbound_addresses", "x-xos-capability": "projects.settings.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["projects"] }], "x-xos-rpc": "app.disable_project_inbox", "summary": "Turn off a project's inbox", "description": "Stops the address accepting mail (app.disable_project_inbox). Mail already received stays; a disabled address never comes back. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the project inbox.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the project inbox.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "local_part": "nwl-0a1b2c3d4e", "disabled_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ProjectInbox" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inbound-messages": { "get": { "operationId": "inboundMessages.list", "tags": ["Platform"], "x-xos-table": "app.inbound_messages", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["received_at"], "numeric": false, "descending": true }, "summary": "List inbound message rows", "description": "Mail received (0550, 1411): forwarded to a project inbox, or a reply to a notification email. People who file documents on the project read its inbox mail; a person reads their own replies. Project inbox mail is filed once, as a Document record of the project, or discarded with a reason. Returns a cursor page of inbound message rows the caller may see. The default order is `received_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of inbound message rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose": "Project Inbox", "inbound_address_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_address": "rigging@bayside-audio.test", "subject_line": "Rigging plot v4", "body_text": "Updated plot attached.", "dkim_verified": true, "inbound_status": "Verified", "rejection_reason": "DKIM failed.", "received_at": "2026-10-08T14:30:00Z", "filed_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_at": "2026-10-08T14:30:00Z", "discarded_at": "2026-10-08T14:30:00Z", "discarded_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "discard_reason": "Spam." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/InboundMessagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inbound-messages/{id}": { "get": { "operationId": "inboundMessages.get", "tags": ["Platform"], "x-xos-table": "app.inbound_messages", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get an inbound message", "description": "Mail received (0550, 1411): forwarded to a project inbox, or a reply to a notification email. People who file documents on the project read its inbox mail; a person reads their own replies. Project inbox mail is filed once, as a Document record of the project, or discarded with a reason. Returns one inbound message with its `ETag`. A inbound message the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inbound message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inbound message.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The inbound message.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose": "Project Inbox", "inbound_address_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_address": "rigging@bayside-audio.test", "subject_line": "Rigging plot v4", "body_text": "Updated plot attached.", "dkim_verified": true, "inbound_status": "Verified", "rejection_reason": "DKIM failed.", "received_at": "2026-10-08T14:30:00Z", "filed_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_at": "2026-10-08T14:30:00Z", "discarded_at": "2026-10-08T14:30:00Z", "discarded_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "discard_reason": "Spam." }, "schema": { "$ref": "#/components/schemas/InboundMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inbound-messages/{id}/file": { "post": { "operationId": "inboundMessages.file", "tags": ["Platform"], "x-xos-table": "app.inbound_messages", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.file_inbound_message", "summary": "File inbound mail as a document", "description": "Files verified project inbox mail as a Document record of the project, optionally to a record of the project the caller can open (app.file_inbound_message); the subject, sender and text are posted as a comment on the document and the record. Mail is filed once (inbound_message_triaged: 422); unverified mail is refused (inbound_message_unverified: 422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inbound message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inbound message.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Rigging plot v4", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/InboundMessageFileRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose": "Project Inbox", "inbound_address_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_address": "rigging@bayside-audio.test", "subject_line": "Rigging plot v4", "body_text": "Updated plot attached.", "dkim_verified": true, "inbound_status": "Verified", "rejection_reason": "DKIM failed.", "received_at": "2026-10-08T14:30:00Z", "filed_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_at": "2026-10-08T14:30:00Z", "discarded_at": "2026-10-08T14:30:00Z", "discarded_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "discard_reason": "Spam." }, "schema": { "$ref": "#/components/schemas/InboundMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/inbound-messages/{id}/discard": { "post": { "operationId": "inboundMessages.discard", "tags": ["Platform"], "x-xos-table": "app.inbound_messages", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.discard_inbound_message", "summary": "Discard inbound mail", "description": "Discards project inbox mail with an optional reason (app.discard_inbound_message). The mail is kept and the audit ledger records who discarded it and when. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the inbound message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the inbound message.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Spam." }, "schema": { "$ref": "#/components/schemas/InboundMessageDiscardRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "purpose": "Project Inbox", "inbound_address_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_address": "rigging@bayside-audio.test", "subject_line": "Rigging plot v4", "body_text": "Updated plot attached.", "dkim_verified": true, "inbound_status": "Verified", "rejection_reason": "DKIM failed.", "received_at": "2026-10-08T14:30:00Z", "filed_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "filed_at": "2026-10-08T14:30:00Z", "discarded_at": "2026-10-08T14:30:00Z", "discarded_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "discard_reason": "Spam." }, "schema": { "$ref": "#/components/schemas/InboundMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automations": { "get": { "operationId": "automations.list", "tags": ["Platform"], "x-xos-table": "app.automations", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["name"], "numeric": false }, "summary": "List automation rows", "description": "An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422). Returns a cursor page of automation rows the caller may see. The default order is `name` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of automation rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Pick up new tasks", "description": "Comments on every new task.", "trigger_event_type": "record.created", "condition_match": "all", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "enabled": true, "paused_at": "2026-10-08T14:30:00Z", "pause_reason": "owner_left_org", "conditions": { "all": [{ "field": "data.record_kind", "operator": "eq", "value": "Task" }] }, "actions": [{ "type": "add_comment", "body": "Picked up {{data.title}}." }] } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AutomationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "automations.create", "tags": ["Platform"], "x-xos-table": "app.automations", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create an automation", "description": "An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422). Creates an automation. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Pick up new tasks", "description": "Comments on every new task.", "trigger_event_type": "record.created", "enabled": true, "conditions": { "all": [{ "field": "data.record_kind", "operator": "eq", "value": "Task" }] }, "actions": [{ "type": "add_comment", "body": "Picked up {{data.title}}." }] }, "schema": { "$ref": "#/components/schemas/AutomationCreate" } } } }, "responses": { "201": { "description": "The created automation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Pick up new tasks", "description": "Comments on every new task.", "trigger_event_type": "record.created", "condition_match": "all", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "enabled": true, "paused_at": "2026-10-08T14:30:00Z", "pause_reason": "owner_left_org", "conditions": { "all": [{ "field": "data.record_kind", "operator": "eq", "value": "Task" }] }, "actions": [{ "type": "add_comment", "body": "Picked up {{data.title}}." }] }, "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automations/{id}": { "get": { "operationId": "automations.get", "tags": ["Platform"], "x-xos-table": "app.automations", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an automation", "description": "An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422). Returns one automation with its `ETag`. A automation the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The automation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Pick up new tasks", "description": "Comments on every new task.", "trigger_event_type": "record.created", "condition_match": "all", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "enabled": true, "paused_at": "2026-10-08T14:30:00Z", "pause_reason": "owner_left_org", "conditions": { "all": [{ "field": "data.record_kind", "operator": "eq", "value": "Task" }] }, "actions": [{ "type": "add_comment", "body": "Picked up {{data.title}}." }] }, "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "automations.update", "tags": ["Platform"], "x-xos-table": "app.automations", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update an automation", "description": "An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422). Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Pick up new tasks", "description": "Comments on every new task.", "trigger_event_type": "record.created", "enabled": true, "conditions": { "all": [{ "field": "data.record_kind", "operator": "eq", "value": "Task" }] }, "actions": [{ "type": "add_comment", "body": "Picked up {{data.title}}." }] }, "schema": { "$ref": "#/components/schemas/AutomationUpdate" } } } }, "responses": { "200": { "description": "The updated automation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Pick up new tasks", "description": "Comments on every new task.", "trigger_event_type": "record.created", "condition_match": "all", "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "enabled": true, "paused_at": "2026-10-08T14:30:00Z", "pause_reason": "owner_left_org", "conditions": { "all": [{ "field": "data.record_kind", "operator": "eq", "value": "Task" }] }, "actions": [{ "type": "add_comment", "body": "Picked up {{data.title}}." }] }, "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "automations.delete", "tags": ["Platform"], "x-xos-table": "app.automations", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete an automation", "description": "An automation (Section 7.3, ADR 0047): when a domain event of the trigger type happens in the org and the conditions hold, the actions run in order as the owner through public API operations, so row level security and capabilities decide every write. The owner is whoever last changed what it does or turned it on. Needs the automations plan feature (Pro and above) to create, change or turn on (plan_feature_required: 422); without it an automation can still be turned off and deleted. Saving validates the documents as automation.schema.json does (automation_conditions_invalid, automation_actions_invalid: 422) and checks the actions fit the trigger (automation_action_needs_record, automation_action_needs_commentable_subject, automation_person_not_member, automation_webhook_unknown: 422). Soft-deletes the automation: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The automation moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automations/{id}/test": { "post": { "operationId": "automations.test", "tags": ["Platform"], "x-xos-table": "app.automations", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "test_automation", "summary": "Test an automation against a sample event", "description": "Dry run of the automation's conditions against a sample event body through `app.test_automation`: whether they match and, per condition, the value found. Nothing runs and nothing is written. Needs org.automations.write. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "event": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "type": "record.created", "occurred_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": { "table": "records", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "data": { "record_kind": "Task", "title": "Call the venue" } } }, "schema": { "$ref": "#/components/schemas/AutomationTestRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "matched": true, "conditions": [] }, "schema": { "$ref": "#/components/schemas/AutomationTestResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automation-runs": { "get": { "operationId": "automationRuns.list", "tags": ["Platform"], "x-xos-table": "app.automation_runs", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["created_at"], "numeric": false, "descending": true }, "summary": "List automation run rows", "description": "One run of an automation for one domain event (ADR 0047): an event never runs an automation twice. A run caused by another automation's action is one level deeper; past depth 3 it is Skipped (loop_depth), and past 1,000 runs in an hour in the org new runs are Skipped (rate_limited). A run fails closed when the owner left the org or lost org.automations.write, and the automation pauses with a notice. Returns a cursor page of automation run rows the caller may see. The default order is `created_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of automation run rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "automation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "depth": 0, "run_status": "Queued", "event_payload": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "type": "record.created", "occurred_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": { "table": "records", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "data": { "record_kind": "Task", "title": "Call the venue" } }, "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attempts": 1, "error_code": "owner_left_org", "error_message": "The API answered 503.", "started_at": "2026-10-08T14:30:00Z", "finished_at": "2026-10-08T14:30:00Z", "duration_ms": 840 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AutomationRunPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automation-runs/{id}": { "get": { "operationId": "automationRuns.get", "tags": ["Platform"], "x-xos-table": "app.automation_runs", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an automation run", "description": "One run of an automation for one domain event (ADR 0047): an event never runs an automation twice. A run caused by another automation's action is one level deeper; past depth 3 it is Skipped (loop_depth), and past 1,000 runs in an hour in the org new runs are Skipped (rate_limited). A run fails closed when the owner left the org or lost org.automations.write, and the automation pauses with a notice. Returns one automation run with its `ETag`. A automation run the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The automation run.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "automation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "depth": 0, "run_status": "Queued", "event_payload": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "type": "record.created", "occurred_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": { "table": "records", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "data": { "record_kind": "Task", "title": "Call the venue" } }, "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attempts": 1, "error_code": "owner_left_org", "error_message": "The API answered 503.", "started_at": "2026-10-08T14:30:00Z", "finished_at": "2026-10-08T14:30:00Z", "duration_ms": 840 }, "schema": { "$ref": "#/components/schemas/AutomationRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automation-runs/{id}/notices": { "post": { "operationId": "automationRuns.notify", "tags": ["Platform"], "x-xos-table": "app.automation_runs", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "send_automation_notice", "summary": "Notify a member from a running automation run", "description": "The notify action (ADR 0047): during a run, the automation's owner notifies a member of the org (automation.notice) about the event's subject, through `app.send_automation_notice`. Only a running run of the caller's own automation (404 otherwise); the recipient must be a member (automation_person_not_member: 422). Needs org.automations.write. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "recipient_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "New task: Call the venue", "body": "Call the venue needs a look." }, "schema": { "$ref": "#/components/schemas/AutomationNoticeRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "notification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AutomationNoticeResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automation-runs/{id}/webhook-deliveries": { "post": { "operationId": "automationRuns.deliverWebhook", "tags": ["Platform"], "x-xos-table": "app.automation_runs", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "queue_automation_webhook", "summary": "Send a running run's event to a webhook endpoint", "description": "The call_webhook action (ADR 0047): during a run, its owner queues a delivery of the run's event to one of the org's webhook endpoints through `app.queue_automation_webhook`; the webhook dispatcher signs and retries it like every webhook. Needs org.automations.write, org.webhooks.manage and the webhooks plan feature. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "webhook_endpoint_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AutomationWebhookRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "webhook_delivery_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AutomationWebhookResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automation-runs/{id}/retry": { "post": { "operationId": "automationRuns.retry", "tags": ["Platform"], "x-xos-table": "app.automation_runs", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-rpc": "retry_automation_run", "summary": "Retry a failed automation run", "description": "Queues a failed run again through `app.retry_automation_run`; steps that succeeded are not run again. The automation must be on (automation_off: 422) and the run Failed (automation_run_not_failed: 422). Needs org.automations.write. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation run.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation run.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "automation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "domain_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "parent_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "depth": 0, "run_status": "Queued", "event_payload": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "type": "record.created", "occurred_at": "2026-10-08T14:30:00Z", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "subject": { "table": "records", "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "data": { "record_kind": "Task", "title": "Call the venue" } }, "owner_person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "attempts": 1, "error_code": "owner_left_org", "error_message": "The API answered 503.", "started_at": "2026-10-08T14:30:00Z", "finished_at": "2026-10-08T14:30:00Z", "duration_ms": 840 }, "schema": { "$ref": "#/components/schemas/AutomationRun" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automation-run-steps": { "get": { "operationId": "automationRunSteps.list", "tags": ["Platform"], "x-xos-table": "app.automation_run_steps", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "x-xos-order": { "by": ["automation_run_id", "position"], "numeric": false }, "summary": "List automation run step rows", "description": "One action of an automation run: the public API operation called as the owner, what was sent and answered, and how long it took. A retried run rewrites the step of the action that failed. Returns a cursor page of automation run step rows the caller may see. The default order is `automation_run_id`, then `position` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of automation run step rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "automation_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "automation_action_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "action_type": "create_task", "operation_id": "records.create", "step_status": "Succeeded", "request_body": { "title": "Review Call the venue" }, "response_body": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "http_status": 201, "error_code": "record_title_grammar", "error_message": "A Task title starts with an imperative verb.", "started_at": "2026-10-08T14:30:00Z", "finished_at": "2026-10-08T14:30:00Z", "duration_ms": 120 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/AutomationRunStepPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/automation-run-steps/{id}": { "get": { "operationId": "automationRunSteps.get", "tags": ["Platform"], "x-xos-table": "app.automation_run_steps", "x-xos-capability": "org.automations.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Get an automation run step", "description": "One action of an automation run: the public API operation called as the owner, what was sent and answered, and how long it took. A retried run rewrites the step of the action that failed. Returns one automation run step with its `ETag`. A automation run step the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the automation run step.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the automation run step.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The automation run step.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "automation_run_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "automation_action_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "action_type": "create_task", "operation_id": "records.create", "step_status": "Succeeded", "request_body": { "title": "Review Call the venue" }, "response_body": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "http_status": 201, "error_code": "record_title_grammar", "error_message": "A Task title starts with an imperative verb.", "started_at": "2026-10-08T14:30:00Z", "finished_at": "2026-10-08T14:30:00Z", "duration_ms": 120 }, "schema": { "$ref": "#/components/schemas/AutomationRunStep" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/groups": { "get": { "operationId": "workforceGroups.list", "tags": ["Workforce"], "x-xos-table": "app.groups", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List workforce group rows", "description": "A group space by department, project, crew or custom audience, with its own chat and files. Returns a cursor page of workforce group rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of workforce group rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging Crew", "group_kind": "Department", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Everyone flying points.", "archived_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkforceGroupPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workforceGroups.create", "tags": ["Workforce"], "x-xos-table": "app.groups", "x-xos-capability": "org.communication.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a workforce group", "description": "A group space by department, project, crew or custom audience, with its own chat and files. Creates a workforce group. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Rigging Crew", "group_kind": "Department", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Everyone flying points." }, "schema": { "$ref": "#/components/schemas/WorkforceGroupCreate" } } } }, "responses": { "201": { "description": "The created workforce group.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging Crew", "group_kind": "Department", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Everyone flying points.", "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkforceGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/groups/{id}": { "get": { "operationId": "workforceGroups.get", "tags": ["Workforce"], "x-xos-table": "app.groups", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a workforce group", "description": "A group space by department, project, crew or custom audience, with its own chat and files. Returns one workforce group with its `ETag`. A workforce group the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce group.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The workforce group.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging Crew", "group_kind": "Department", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Everyone flying points.", "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkforceGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "workforceGroups.update", "tags": ["Workforce"], "x-xos-table": "app.groups", "x-xos-capability": "org.communication.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a workforce group", "description": "A group space by department, project, crew or custom audience, with its own chat and files. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce group.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Rigging Crew", "description": "Everyone flying points." }, "schema": { "$ref": "#/components/schemas/WorkforceGroupUpdate" } } } }, "responses": { "200": { "description": "The updated workforce group.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging Crew", "group_kind": "Department", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Everyone flying points.", "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkforceGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/groups/{id}/archive": { "post": { "operationId": "workforceGroups.archive", "tags": ["Workforce"], "x-xos-table": "app.groups", "x-xos-capability": "org.communication.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Archive a group", "description": "Archives the group; it keeps its history and takes no new messages. Archiving is final. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce group.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce group.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging Crew", "group_kind": "Department", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "description": "Everyone flying points.", "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WorkforceGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/group-members": { "get": { "operationId": "workforceGroupMembers.list", "tags": ["Workforce"], "x-xos-table": "app.group_members", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List workforce group member rows", "description": "A member of a group space. Deleting removes the member, who also leaves the group conversation. Returns a cursor page of workforce group member rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of workforce group member rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_role": "Member" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkforceGroupMemberPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workforceGroupMembers.create", "tags": ["Workforce"], "x-xos-table": "app.group_members", "x-xos-capability": "org.communication.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a workforce group member", "description": "A member of a group space. Deleting removes the member, who also leaves the group conversation. Creates a workforce group member. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_role": "Member" }, "schema": { "$ref": "#/components/schemas/WorkforceGroupMemberCreate" } } } }, "responses": { "201": { "description": "The created workforce group member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_role": "Member" }, "schema": { "$ref": "#/components/schemas/WorkforceGroupMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/group-members/{id}": { "get": { "operationId": "workforceGroupMembers.get", "tags": ["Workforce"], "x-xos-table": "app.group_members", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a workforce group member", "description": "A member of a group space. Deleting removes the member, who also leaves the group conversation. Returns one workforce group member with its `ETag`. A workforce group member the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce group member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce group member.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The workforce group member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_role": "Member" }, "schema": { "$ref": "#/components/schemas/WorkforceGroupMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "workforceGroupMembers.delete", "tags": ["Workforce"], "x-xos-table": "app.group_members", "x-xos-capability": "org.communication.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a workforce group member", "description": "A member of a group space. Deleting removes the member, who also leaves the group conversation. Soft-deletes the workforce group member: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce group member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce group member.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The workforce group member moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations": { "get": { "operationId": "conversations.list", "tags": ["Workforce"], "x-xos-table": "app.conversations", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List conversation rows", "description": "A chat conversation: one-to-one between two members, or the conversation of a group. Returns a cursor page of conversation rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of conversation rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_kind": "Direct", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direct_key": "a:b", "last_message_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ConversationPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{id}": { "get": { "operationId": "conversations.get", "tags": ["Workforce"], "x-xos-table": "app.conversations", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a conversation", "description": "A chat conversation: one-to-one between two members, or the conversation of a group. Returns one conversation with its `ETag`. A conversation the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the conversation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the conversation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The conversation.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_kind": "Direct", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direct_key": "a:b", "last_message_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/start-direct": { "post": { "operationId": "conversations.startDirect", "tags": ["Workforce"], "x-xos-table": "app.conversations", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "app.start_direct_conversation", "summary": "Start a direct conversation", "description": "Opens, or returns, the one-to-one conversation with another active member of the org. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "other_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/DirectConversationRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_kind": "Direct", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direct_key": "a:b", "last_message_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{id}/mark-read": { "post": { "operationId": "conversations.markRead", "tags": ["Workforce"], "x-xos-table": "app.conversations", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "app.mark_conversation_read", "summary": "Mark a conversation read", "description": "Marks the conversation read up to now for the caller and optionally mutes or unmutes it. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the conversation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the conversation.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "muted": false }, "schema": { "$ref": "#/components/schemas/MarkConversationReadRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_kind": "Direct", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "direct_key": "a:b", "last_message_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{id}/read-receipts": { "get": { "operationId": "conversations.readReceipts", "tags": ["Workforce"], "x-xos-table": "app.conversations", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "app.conversation_read_receipts", "summary": "Read receipts", "description": "When the other members last read the conversation; empty while the org has read receipts off. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the conversation.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the conversation.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "full_name": "Carol Nguyen", "last_read_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ConversationReadReceiptPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/chat-messages": { "get": { "operationId": "chatMessages.list", "tags": ["Workforce"], "x-xos-table": "app.chat_messages", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List chat message rows", "description": "A chat message. Photos, files and voice notes are attachments on the message. Returns a cursor page of chat message rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of chat message rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_kind": "Text", "body": "Points are up on stage left.", "language": "en-US", "edited_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/ChatMessagePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "chatMessages.create", "tags": ["Workforce"], "x-xos-table": "app.chat_messages", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Create a chat message", "description": "A chat message. Photos, files and voice notes are attachments on the message. Creates a chat message. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "conversation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_kind": "Text", "body": "Points are up on stage left.", "language": "en-US" }, "schema": { "$ref": "#/components/schemas/ChatMessageCreate" } } } }, "responses": { "201": { "description": "The created chat message.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_kind": "Text", "body": "Points are up on stage left.", "language": "en-US", "edited_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ChatMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/chat-messages/{id}": { "get": { "operationId": "chatMessages.get", "tags": ["Workforce"], "x-xos-table": "app.chat_messages", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a chat message", "description": "A chat message. Photos, files and voice notes are attachments on the message. Returns one chat message with its `ETag`. A chat message the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the chat message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the chat message.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The chat message.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_kind": "Text", "body": "Points are up on stage left.", "language": "en-US", "edited_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ChatMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "chatMessages.update", "tags": ["Workforce"], "x-xos-table": "app.chat_messages", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Update a chat message", "description": "A chat message. Photos, files and voice notes are attachments on the message. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the chat message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the chat message.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "body": "Points are up on stage left." }, "schema": { "$ref": "#/components/schemas/ChatMessageUpdate" } } } }, "responses": { "200": { "description": "The updated chat message.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "conversation_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message_kind": "Text", "body": "Points are up on stage left.", "language": "en-US", "edited_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/ChatMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "chatMessages.delete", "tags": ["Workforce"], "x-xos-table": "app.chat_messages", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Delete a chat message", "description": "A chat message. Photos, files and voice notes are attachments on the message. Soft-deletes the chat message: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the chat message.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the chat message.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The chat message moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/directory-entries/search": { "get": { "operationId": "directoryEntries.search", "tags": ["Workforce"], "x-xos-table": "app.workforce_directory", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "app.workforce_directory", "summary": "Search the directory", "description": "The org directory, on-site members first, filtered by name or headline and optionally to those on site now. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "maxLength": 200, "description": "Name or headline contains this.", "example": "frank" }, "required": false, "description": "Name or headline contains this.", "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": ["true", "false"], "description": "Only members on site now.", "example": "true" }, "required": false, "description": "Only members on site now.", "name": "on_site", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "full_name": "Frank Adeyemi", "preferred_name": "Frankie", "headline": "Head rigger", "photo_path": "profiles/p1.jpg", "role_names": ["Field"], "on_site_now": true, "on_site_project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "on_site_since": "2026-10-08T14:30:00Z", "work_phone": "+1 305 555 0199", "recognition_count": 3 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DirectoryEntryPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts": { "get": { "operationId": "feedPosts.list", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["publish_at"], "numeric": false, "descending": true }, "summary": "List feed post rows", "description": "A feed post for an audience: an announcement, update, poll or recognition, with pinning, required acknowledgment, reaction and comment switches and a publish time. Returns a cursor page of feed post rows the caller may see. The default order is `publish_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of feed post rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/FeedPostPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "feedPosts.create", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a feed post", "description": "A feed post for an audience: an announcement, update, poll or recognition, with pinning, required acknowledgment, reaction and comment switches and a publish time. Creates a feed post. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/FeedPostCreate" } } } }, "responses": { "201": { "description": "The created feed post.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts/{id}": { "get": { "operationId": "feedPosts.get", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a feed post", "description": "A feed post for an audience: an announcement, update, poll or recognition, with pinning, required acknowledgment, reaction and comment switches and a publish time. Returns one feed post with its `ETag`. A feed post the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the feed post.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The feed post.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "feedPosts.update", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a feed post", "description": "A feed post for an audience: an announcement, update, poll or recognition, with pinning, required acknowledgment, reaction and comment switches and a publish time. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the feed post.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/FeedPostUpdate" } } } }, "responses": { "200": { "description": "The updated feed post.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts/create-poll": { "post": { "operationId": "feedPosts.createPoll", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.create_feed_post", "summary": "Post a poll", "description": "Posts a quick poll to the feed with 2 to 10 options. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "body": "Pick the crew meal.", "title": "Crew meal", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "question": "Which crew meal on Saturday?", "options": ["Tacos", "Pasta"], "allows_multiple": false, "closes_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/PollPostRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts/{id}/pin": { "post": { "operationId": "feedPosts.pin", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.update_feed_post", "summary": "Pin or unpin a post", "description": "Pins the post to the top of the feed, or unpins it. Needs knowledge.sop.publish or org.communication.write. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the feed post.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "pinned": true }, "schema": { "$ref": "#/components/schemas/PinFeedPostRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts/{id}/hide": { "post": { "operationId": "feedPosts.hide", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.document.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.hide_feed_post", "summary": "Hide a post", "description": "Hides the post with a reason; it leaves everyone else's feed. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the feed post.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/HideFeedPostRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts/{id}/acknowledge": { "post": { "operationId": "feedPosts.acknowledge", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.acknowledge_feed_post", "summary": "Acknowledge a post", "description": "Records that the caller acknowledged a post that requires it. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the feed post.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts/{id}/react": { "post": { "operationId": "feedPosts.react", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.react_to_feed_post", "summary": "React to a post", "description": "Adds or removes the caller's reaction from the curated set. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the feed post.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reaction_code": "heart", "on": true }, "schema": { "$ref": "#/components/schemas/FeedReactionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "post_kind": "Announcement", "title": "Wristband change", "body": "Wristbands change color on Friday.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "department_code": "5000", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "pinned_at": "2026-10-08T14:30:00Z", "requires_acknowledgment": false, "reactions_enabled": true, "comments_enabled": true, "publish_at": "2026-10-08T14:30:00Z", "notified_at": "2026-10-08T14:30:00Z", "hidden_at": "2026-10-08T14:30:00Z", "hidden_reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/FeedPost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/feed-posts/{id}/acknowledgments": { "get": { "operationId": "feedPosts.acknowledgments", "tags": ["Workforce"], "x-xos-table": "app.feed_posts", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.feed_acknowledgment_status", "summary": "Acknowledgment status", "description": "Each member of the audience and when they acknowledged the post, outstanding first. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the feed post.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the feed post.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "full_name": "Frank Adeyemi", "acknowledged_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/FeedAcknowledgmentStatusPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/polls": { "get": { "operationId": "polls.list", "tags": ["Workforce"], "x-xos-table": "app.polls", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List poll rows", "description": "A quick poll in the feed, attached to a post of kind Poll. Returns a cursor page of poll rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of poll rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feed_post_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "question": "Which crew meal on Saturday?", "allows_multiple": false, "closes_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PollPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/polls/{id}": { "get": { "operationId": "polls.get", "tags": ["Workforce"], "x-xos-table": "app.polls", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a poll", "description": "A quick poll in the feed, attached to a post of kind Poll. Returns one poll with its `ETag`. A poll the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the poll.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the poll.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The poll.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feed_post_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "question": "Which crew meal on Saturday?", "allows_multiple": false, "closes_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Poll" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/polls/{id}/vote": { "post": { "operationId": "polls.vote", "tags": ["Workforce"], "x-xos-table": "app.polls", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.vote_in_poll", "summary": "Vote in a poll", "description": "Votes once: one option, or several when the poll allows it. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the poll.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the poll.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "option_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"] }, "schema": { "$ref": "#/components/schemas/PollVoteRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "feed_post_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "question": "Which crew meal on Saturday?", "allows_multiple": false, "closes_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Poll" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/polls/{id}/results": { "get": { "operationId": "polls.results", "tags": ["Workforce"], "x-xos-table": "app.polls", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.poll_results", "summary": "Poll results", "description": "Votes per option. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the poll.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the poll.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "poll_option_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "option_position": 1, "label": "Tacos", "votes": 12, "voters": 20 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/PollResultPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/surveys": { "get": { "operationId": "surveys.list", "tags": ["Workforce"], "x-xos-table": "app.surveys", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List survey rows", "description": "A pulse survey for an audience, anonymous by default, with results only once the minimum number of responses is met. Returns a cursor page of survey rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of survey rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Load-in pulse", "description": "Tell us how the load-in felt.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "is_anonymous": true, "min_responses": 5, "survey_state": "Draft", "closes_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SurveyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/surveys/{id}": { "get": { "operationId": "surveys.get", "tags": ["Workforce"], "x-xos-table": "app.surveys", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a survey", "description": "A pulse survey for an audience, anonymous by default, with results only once the minimum number of responses is met. Returns one survey with its `ETag`. A survey the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the survey.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The survey.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Load-in pulse", "description": "Tell us how the load-in felt.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "is_anonymous": true, "min_responses": 5, "survey_state": "Draft", "closes_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Survey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/surveys/draft": { "post": { "operationId": "surveys.draft", "tags": ["Workforce"], "x-xos-table": "app.surveys", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.create_survey", "summary": "Draft a survey", "description": "Drafts a pulse survey with its questions. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Load-in pulse", "description": "How did it go?", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "is_anonymous": true, "min_responses": 5, "closes_at": "2026-10-08T14:30:00Z", "questions": [{ "prompt": "How safe did it feel?", "kind": "Scale" }] }, "schema": { "$ref": "#/components/schemas/SurveyDraftRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Load-in pulse", "description": "Tell us how the load-in felt.", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "author_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "is_anonymous": true, "min_responses": 5, "survey_state": "Draft", "closes_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/Survey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/surveys/{id}/transition": { "post": { "operationId": "surveys.transition", "tags": ["Workforce"], "x-xos-table": "app.surveys", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.transition_survey", "summary": "Open or close a survey", "description": "Opens a draft survey (notifying its audience) or closes an open one. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the survey.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Draft", "to_state": "Open", "reason": "Ready to go." }, "schema": { "$ref": "#/components/schemas/SurveyTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "ledger_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WorkforceLedgerEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/surveys/{id}/respond": { "post": { "operationId": "surveys.respond", "tags": ["Workforce"], "x-xos-table": "app.surveys", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.respond_to_survey", "summary": "Respond to a survey", "description": "Responds once with answers keyed by question id. Anonymous answers carry no respondent. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the survey.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "answers": { "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f": 4 } }, "schema": { "$ref": "#/components/schemas/SurveyResponseRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "response_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/SurveyResponseResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/surveys/{id}/results": { "get": { "operationId": "surveys.results", "tags": ["Workforce"], "x-xos-table": "app.surveys", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.survey_results", "summary": "Survey results", "description": "Results, shown only once the minimum number of responses is met. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the survey.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the survey.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "survey_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "responses": 12, "min_responses": 5, "threshold_met": true, "audience": 40, "questions": [] }, "schema": { "$ref": "#/components/schemas/SurveyResults" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/survey-questions": { "get": { "operationId": "surveyQuestions.list", "tags": ["Workforce"], "x-xos-table": "app.survey_questions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List survey question rows", "description": "A question of a pulse survey, in order. Returns a cursor page of survey question rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of survey question rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "survey_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "How safe did the load-in feel?", "question_kind": "Scale", "choices": ["Morning", "Night"], "scale_max": 5, "is_required": true } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/SurveyQuestionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/survey-questions/{id}": { "get": { "operationId": "surveyQuestions.get", "tags": ["Workforce"], "x-xos-table": "app.survey_questions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a survey question", "description": "A question of a pulse survey, in order. Returns one survey question with its `ETag`. A survey question the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the survey question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the survey question.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The survey question.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "survey_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "How safe did the load-in feel?", "question_kind": "Scale", "choices": ["Morning", "Night"], "scale_max": 5, "is_required": true }, "schema": { "$ref": "#/components/schemas/SurveyQuestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/recognitions": { "get": { "operationId": "recognitions.list", "tags": ["Workforce"], "x-xos-table": "app.recognitions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List recognition rows", "description": "A shout-out from one member to another, tied to a project or shift and posted to the feed. No points currency. Returns a cursor page of recognition rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of recognition rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Re-rigged the truss in record time.", "feed_post_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/RecognitionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "recognitions.create", "tags": ["Workforce"], "x-xos-table": "app.recognitions", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a recognition", "description": "A shout-out from one member to another, tied to a project or shift and posted to the feed. No points currency. Creates a recognition. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "to_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Re-rigged the truss in record time." }, "schema": { "$ref": "#/components/schemas/RecognitionCreate" } } } }, "responses": { "201": { "description": "The created recognition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Re-rigged the truss in record time.", "feed_post_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Recognition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/recognitions/{id}": { "get": { "operationId": "recognitions.get", "tags": ["Workforce"], "x-xos-table": "app.recognitions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a recognition", "description": "A shout-out from one member to another, tied to a project or shift and posted to the feed. No points currency. Returns one recognition with its `ETag`. A recognition the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the recognition.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the recognition.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The recognition.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "from_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "to_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "shift_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "message": "Re-rigged the truss in record time.", "feed_post_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/Recognition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workforce-events": { "get": { "operationId": "workforceEvents.list", "tags": ["Workforce"], "x-xos-table": "app.workforce_events", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List workforce event rows", "description": "A briefing, crew call or meeting for an audience, with RSVP, location, agenda and check-in. Returns a cursor page of workforce event rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of workforce event rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_kind": "Briefing", "title": "Load-in crew call", "agenda": "1. Safety brief. 2. Assignments.", "location": "Dock door 3", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organizer_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "rsvp_required": true, "canceled_at": "2026-10-08T14:30:00Z", "cancel_reason": "Dock closed for repairs." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WorkforceEventPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "workforceEvents.create", "tags": ["Workforce"], "x-xos-table": "app.workforce_events", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Create a workforce event", "description": "A briefing, crew call or meeting for an audience, with RSVP, location, agenda and check-in. Creates a workforce event. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "event_kind": "Briefing", "title": "Load-in crew call", "agenda": "1. Safety brief. 2. Assignments.", "location": "Dock door 3", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "rsvp_required": true }, "schema": { "$ref": "#/components/schemas/WorkforceEventCreate" } } } }, "responses": { "201": { "description": "The created workforce event.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_kind": "Briefing", "title": "Load-in crew call", "agenda": "1. Safety brief. 2. Assignments.", "location": "Dock door 3", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organizer_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "rsvp_required": true, "canceled_at": "2026-10-08T14:30:00Z", "cancel_reason": "Dock closed for repairs." }, "schema": { "$ref": "#/components/schemas/WorkforceEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workforce-events/{id}": { "get": { "operationId": "workforceEvents.get", "tags": ["Workforce"], "x-xos-table": "app.workforce_events", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Get a workforce event", "description": "A briefing, crew call or meeting for an audience, with RSVP, location, agenda and check-in. Returns one workforce event with its `ETag`. A workforce event the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce event.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The workforce event.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_kind": "Briefing", "title": "Load-in crew call", "agenda": "1. Safety brief. 2. Assignments.", "location": "Dock door 3", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organizer_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "rsvp_required": true, "canceled_at": "2026-10-08T14:30:00Z", "cancel_reason": "Dock closed for repairs." }, "schema": { "$ref": "#/components/schemas/WorkforceEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "workforceEvents.update", "tags": ["Workforce"], "x-xos-table": "app.workforce_events", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Update a workforce event", "description": "A briefing, crew call or meeting for an audience, with RSVP, location, agenda and check-in. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce event.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "event_kind": "Briefing", "title": "Load-in crew call", "agenda": "1. Safety brief. 2. Assignments.", "location": "Dock door 3", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "rsvp_required": true }, "schema": { "$ref": "#/components/schemas/WorkforceEventUpdate" } } } }, "responses": { "200": { "description": "The updated workforce event.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_kind": "Briefing", "title": "Load-in crew call", "agenda": "1. Safety brief. 2. Assignments.", "location": "Dock door 3", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organizer_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "rsvp_required": true, "canceled_at": "2026-10-08T14:30:00Z", "cancel_reason": "Dock closed for repairs." }, "schema": { "$ref": "#/components/schemas/WorkforceEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workforce-events/{id}/cancel": { "post": { "operationId": "workforceEvents.cancel", "tags": ["Workforce"], "x-xos-table": "app.workforce_events", "x-xos-capability": "schedule.timeline.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Cancel an event", "description": "Cancels the event with a reason; cancellation is final. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce event.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/CancelWorkforceEventRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "event_kind": "Briefing", "title": "Load-in crew call", "agenda": "1. Safety brief. 2. Assignments.", "location": "Dock door 3", "venue_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "audience_kind": "Organization", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "organizer_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "starts_at": "2026-10-08T14:30:00Z", "ends_at": "2026-10-08T14:30:00Z", "rsvp_required": true, "canceled_at": "2026-10-08T14:30:00Z", "cancel_reason": "Dock closed for repairs." }, "schema": { "$ref": "#/components/schemas/WorkforceEvent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workforce-events/{id}/rsvp": { "post": { "operationId": "workforceEvents.rsvp", "tags": ["Workforce"], "x-xos-table": "app.workforce_events", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-rpc": "app.rsvp_to_event", "summary": "RSVP to an event", "description": "Records or changes the caller's RSVP. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce event.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "response": "Going" }, "schema": { "$ref": "#/components/schemas/RsvpRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workforce_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "response": "Going", "responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/EventRsvp" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/workforce-events/{id}/check-in": { "post": { "operationId": "workforceEvents.checkIn", "tags": ["Workforce"], "x-xos-table": "app.workforce_events", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-rpc": "app.check_in_to_event", "summary": "Check in to an event", "description": "Checks the caller in, or another invitee when the caller organizes the event, from an hour before the start to the end. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the workforce event.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the workforce event.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "method": "Self" }, "schema": { "$ref": "#/components/schemas/EventCheckInRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workforce_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "check_in_method": "Self", "checked_in_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/EventCheckIn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/event-rsvps": { "get": { "operationId": "eventRsvps.list", "tags": ["Workforce"], "x-xos-table": "app.event_rsvps", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List event rsvp rows", "description": "An invitee's RSVP to an event. Returns a cursor page of event rsvp rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of event rsvp rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workforce_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "response": "Going", "responded_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EventRsvpPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/event-rsvps/{id}": { "get": { "operationId": "eventRsvps.get", "tags": ["Workforce"], "x-xos-table": "app.event_rsvps", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Get an event rsvp", "description": "An invitee's RSVP to an event. Returns one event rsvp with its `ETag`. A event rsvp the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the event rsvp.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the event rsvp.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The event rsvp.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workforce_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "response": "Going", "responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/EventRsvp" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/event-check-ins": { "get": { "operationId": "eventCheckIns.list", "tags": ["Workforce"], "x-xos-table": "app.event_check_ins", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List event check in rows", "description": "Attendance of an event, one per attendee. Returns a cursor page of event check in rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of event check in rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workforce_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "check_in_method": "Self", "checked_in_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/EventCheckInPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/event-check-ins/{id}": { "get": { "operationId": "eventCheckIns.get", "tags": ["Workforce"], "x-xos-table": "app.event_check_ins", "x-xos-capability": "schedule.timeline.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["schedule"] }], "summary": "Get an event check in", "description": "Attendance of an event, one per attendee. Returns one event check in with its `ETag`. A event check in the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the event check in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the event check in.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The event check in.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "workforce_event_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "check_in_method": "Self", "checked_in_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/EventCheckIn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-templates": { "get": { "operationId": "formTemplates.list", "tags": ["Workforce"], "x-xos-table": "app.form_templates", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["name"], "numeric": false }, "summary": "List form template rows", "description": "A no-code form with conditional fields, photos, GPS stamp, signature, scoring and approval routing. Project submissions become records of its canon kind and subtype. Returns a cursor page of form template rows the caller may see. The default order is `name` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of form template rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [ { "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" } ], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_state": "Draft", "current_version": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/FormTemplatePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "formTemplates.create", "tags": ["Workforce"], "x-xos-table": "app.form_templates", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a form template", "description": "A no-code form with conditional fields, photos, GPS stamp, signature, scoring and approval routing. Project submissions become records of its canon kind and subtype. Creates a form template. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FormTemplateCreate" } } } }, "responses": { "201": { "description": "The created form template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_state": "Draft", "current_version": 1 }, "schema": { "$ref": "#/components/schemas/FormTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-templates/{id}": { "get": { "operationId": "formTemplates.get", "tags": ["Workforce"], "x-xos-table": "app.form_templates", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a form template", "description": "A no-code form with conditional fields, photos, GPS stamp, signature, scoring and approval routing. Project submissions become records of its canon kind and subtype. Returns one form template with its `ETag`. A form template the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the form template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the form template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The form template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_state": "Draft", "current_version": 1 }, "schema": { "$ref": "#/components/schemas/FormTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "formTemplates.update", "tags": ["Workforce"], "x-xos-table": "app.form_templates", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a form template", "description": "A no-code form with conditional fields, photos, GPS stamp, signature, scoring and approval routing. Project submissions become records of its canon kind and subtype. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the form template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the form template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/FormTemplateUpdate" } } } }, "responses": { "200": { "description": "The updated form template.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_state": "Draft", "current_version": 1 }, "schema": { "$ref": "#/components/schemas/FormTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-templates/{id}/publish": { "post": { "operationId": "formTemplates.publish", "tags": ["Workforce"], "x-xos-table": "app.form_templates", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.publish_form_template", "summary": "Publish a form", "description": "Publishes a draft form as its next version. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the form template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the form template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_state": "Draft", "current_version": 1 }, "schema": { "$ref": "#/components/schemas/FormTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-templates/{id}/retire": { "post": { "operationId": "formTemplates.retire", "tags": ["Workforce"], "x-xos-table": "app.form_templates", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.retire_form_template", "summary": "Retire a form", "description": "Retires a published form; it keeps its submissions. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the form template.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the form template.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/RetireFormRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Rigging pre-use check", "description": "Before every lift.", "record_kind": "Inspection", "record_subtype": "Safety", "fields": [{ "key": "hoist_ok", "label": "Hoist inspected", "kind": "yes_no" }], "requires_signature": true, "requires_location": true, "pass_score": 2, "approver_role_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "template_state": "Draft", "current_version": 1 }, "schema": { "$ref": "#/components/schemas/FormTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-submissions": { "get": { "operationId": "formSubmissions.list", "tags": ["Workforce"], "x-xos-table": "app.form_submissions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List form submission rows", "description": "A submitted form: answers against one template version, score, GPS stamp, signature and approval. Returns a cursor page of form submission rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of form submission rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answers": { "hoist_ok": true }, "score": 3, "max_score": 3, "passed": true, "latitude": 25.7617, "longitude": -80.1918, "accuracy_m": 8, "signer_name": "Frank Adeyemi", "signature_path": "org/forms/sig.png", "signed_at": "2026-10-08T14:30:00Z", "submission_state": "Submitted", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decision_note": "Good to lift." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/FormSubmissionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "formSubmissions.create", "tags": ["Workforce"], "x-xos-table": "app.form_submissions", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a form submission", "description": "A submitted form: answers against one template version, score, GPS stamp, signature and approval. Creates a form submission. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "form_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answers": { "hoist_ok": true }, "latitude": 25.7617, "longitude": -80.1918, "accuracy_m": 8, "signer_name": "Frank Adeyemi", "signature_path": "org/forms/sig.png" }, "schema": { "$ref": "#/components/schemas/FormSubmissionCreate" } } } }, "responses": { "201": { "description": "The created form submission.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answers": { "hoist_ok": true }, "score": 3, "max_score": 3, "passed": true, "latitude": 25.7617, "longitude": -80.1918, "accuracy_m": 8, "signer_name": "Frank Adeyemi", "signature_path": "org/forms/sig.png", "signed_at": "2026-10-08T14:30:00Z", "submission_state": "Submitted", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decision_note": "Good to lift." }, "schema": { "$ref": "#/components/schemas/FormSubmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-submissions/{id}": { "get": { "operationId": "formSubmissions.get", "tags": ["Workforce"], "x-xos-table": "app.form_submissions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a form submission", "description": "A submitted form: answers against one template version, score, GPS stamp, signature and approval. Returns one form submission with its `ETag`. A form submission the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the form submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the form submission.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The form submission.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answers": { "hoist_ok": true }, "score": 3, "max_score": 3, "passed": true, "latitude": 25.7617, "longitude": -80.1918, "accuracy_m": 8, "signer_name": "Frank Adeyemi", "signature_path": "org/forms/sig.png", "signed_at": "2026-10-08T14:30:00Z", "submission_state": "Submitted", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decision_note": "Good to lift." }, "schema": { "$ref": "#/components/schemas/FormSubmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/form-submissions/{id}/decide": { "post": { "operationId": "formSubmissions.decide", "tags": ["Workforce"], "x-xos-table": "app.form_submissions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.decide_form_submission", "summary": "Approve or reject a submission", "description": "A holder of the form's approver role decides a submitted form; never the submitter. A rejection needs a note. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the form submission.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the form submission.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "approve": true, "note": "Good to lift." }, "schema": { "$ref": "#/components/schemas/FormDecisionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "form_template_version_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "submitted_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "answers": { "hoist_ok": true }, "score": 3, "max_score": 3, "passed": true, "latitude": 25.7617, "longitude": -80.1918, "accuracy_m": 8, "signer_name": "Frank Adeyemi", "signature_path": "org/forms/sig.png", "signed_at": "2026-10-08T14:30:00Z", "submission_state": "Submitted", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decision_note": "Good to lift." }, "schema": { "$ref": "#/components/schemas/FormSubmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-courses": { "get": { "operationId": "trainingCourses.list", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["title"], "numeric": false }, "summary": "List training course rows", "description": "A short training course of lessons and quizzes with completion records and expiry, linked to a role, a certification and a gate criterion. Returns a cursor page of training course rows the caller may see. The default order is `title` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of training course rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20, "course_state": "Draft" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TrainingCoursePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "trainingCourses.create", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a training course", "description": "A short training course of lessons and quizzes with completion records and expiry, linked to a role, a certification and a gate criterion. Creates a training course. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20 }, "schema": { "$ref": "#/components/schemas/TrainingCourseCreate" } } } }, "responses": { "201": { "description": "The created training course.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20, "course_state": "Draft" }, "schema": { "$ref": "#/components/schemas/TrainingCourse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-courses/{id}": { "get": { "operationId": "trainingCourses.get", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a training course", "description": "A short training course of lessons and quizzes with completion records and expiry, linked to a role, a certification and a gate criterion. Returns one training course with its `ETag`. A training course the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training course.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The training course.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20, "course_state": "Draft" }, "schema": { "$ref": "#/components/schemas/TrainingCourse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "trainingCourses.update", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a training course", "description": "A short training course of lessons and quizzes with completion records and expiry, linked to a role, a certification and a gate criterion. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training course.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20 }, "schema": { "$ref": "#/components/schemas/TrainingCourseUpdate" } } } }, "responses": { "200": { "description": "The updated training course.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20, "course_state": "Draft" }, "schema": { "$ref": "#/components/schemas/TrainingCourse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-courses/{id}/publish": { "post": { "operationId": "trainingCourses.publish", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.publish_training_course", "summary": "Publish a course", "description": "Publishes a draft course with at least one lesson and every quiz keyed. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training course.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20, "course_state": "Draft" }, "schema": { "$ref": "#/components/schemas/TrainingCourse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-courses/{id}/retire": { "post": { "operationId": "trainingCourses.retire", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.retire_training_course", "summary": "Retire a course", "description": "Retires a published course. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training course.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/RetireCourseRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Rigging basics", "summary": "Slings and shackles.", "role_code": "5000.01.01", "certification_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "gate_criterion_id": "G3.CREW_TRAINED", "validity_days": 365, "pass_percent": 80, "estimated_minutes": 20, "course_state": "Draft" }, "schema": { "$ref": "#/components/schemas/TrainingCourse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-courses/{id}/assign": { "post": { "operationId": "trainingCourses.assign", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.assign_training", "summary": "Assign a course", "description": "Assigns a published course to active members with an optional due date. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training course.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "membership_ids": ["0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"], "due_on": "2026-10-20", "reason": "New riggers" }, "schema": { "$ref": "#/components/schemas/AssignTrainingRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "assigned": 2 }, "schema": { "$ref": "#/components/schemas/AssignTrainingResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-courses/{id}/complete": { "post": { "operationId": "trainingCourses.complete", "tags": ["Workforce"], "x-xos-table": "app.training_courses", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.complete_training", "summary": "Complete a course", "description": "Grades the caller's quiz answers once every reading and video lesson is finished. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training course.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training course.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "answers": { "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f": 1 } }, "schema": { "$ref": "#/components/schemas/CompleteTrainingRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "score_percent": 90, "passed": true, "completed_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "certificate_number": "TRN-0001", "certification_holder_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TrainingCompletion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-lessons": { "get": { "operationId": "trainingLessons.list", "tags": ["Workforce"], "x-xos-table": "app.training_lessons", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List training lesson rows", "description": "A lesson of a training course: a reading, a video or a quiz. Changes only while the course is a draft. Returns a cursor page of training lesson rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of training lesson rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Slings", "lesson_kind": "Reading", "body": "Inspect every sling before use.", "video_url": "https://northwindlive.example/files/site-plan.pdf" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TrainingLessonPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "trainingLessons.create", "tags": ["Workforce"], "x-xos-table": "app.training_lessons", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a training lesson", "description": "A lesson of a training course: a reading, a video or a quiz. Changes only while the course is a draft. Creates a training lesson. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Slings", "lesson_kind": "Reading", "body": "Inspect every sling before use.", "video_url": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/TrainingLessonCreate" } } } }, "responses": { "201": { "description": "The created training lesson.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Slings", "lesson_kind": "Reading", "body": "Inspect every sling before use.", "video_url": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/TrainingLesson" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-lessons/{id}": { "get": { "operationId": "trainingLessons.get", "tags": ["Workforce"], "x-xos-table": "app.training_lessons", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a training lesson", "description": "A lesson of a training course: a reading, a video or a quiz. Changes only while the course is a draft. Returns one training lesson with its `ETag`. A training lesson the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training lesson.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training lesson.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The training lesson.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Slings", "lesson_kind": "Reading", "body": "Inspect every sling before use.", "video_url": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/TrainingLesson" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "trainingLessons.update", "tags": ["Workforce"], "x-xos-table": "app.training_lessons", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a training lesson", "description": "A lesson of a training course: a reading, a video or a quiz. Changes only while the course is a draft. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training lesson.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training lesson.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "position": 1, "title": "Slings", "body": "Inspect every sling before use.", "video_url": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/TrainingLessonUpdate" } } } }, "responses": { "200": { "description": "The updated training lesson.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Slings", "lesson_kind": "Reading", "body": "Inspect every sling before use.", "video_url": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/TrainingLesson" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "trainingLessons.delete", "tags": ["Workforce"], "x-xos-table": "app.training_lessons", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Delete a training lesson", "description": "A lesson of a training course: a reading, a video or a quiz. Changes only while the course is a draft. Soft-deletes the training lesson: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training lesson.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training lesson.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The training lesson moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-lessons/{id}/complete": { "post": { "operationId": "trainingLessons.complete", "tags": ["Workforce"], "x-xos-table": "app.training_lessons", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.complete_training_lesson", "summary": "Finish a lesson", "description": "Marks a reading or video lesson finished for the caller. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training lesson.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training lesson.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "title": "Slings", "lesson_kind": "Reading", "body": "Inspect every sling before use.", "video_url": "https://northwindlive.example/files/site-plan.pdf" }, "schema": { "$ref": "#/components/schemas/TrainingLesson" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-quiz-questions": { "get": { "operationId": "trainingQuizQuestions.list", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_questions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List training quiz question rows", "description": "A question of a quiz lesson; its correct option is a training quiz key that learners never read. Returns a cursor page of training quiz question rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of training quiz question rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_lesson_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "What do you do before a lift?", "options": ["Inspect the sling", "Skip it"] } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TrainingQuizQuestionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "trainingQuizQuestions.create", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_questions", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a training quiz question", "description": "A question of a quiz lesson; its correct option is a training quiz key that learners never read. Creates a training quiz question. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "training_lesson_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "What do you do before a lift?", "options": ["Inspect the sling", "Skip it"] }, "schema": { "$ref": "#/components/schemas/TrainingQuizQuestionCreate" } } } }, "responses": { "201": { "description": "The created training quiz question.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_lesson_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "What do you do before a lift?", "options": ["Inspect the sling", "Skip it"] }, "schema": { "$ref": "#/components/schemas/TrainingQuizQuestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-quiz-questions/{id}": { "get": { "operationId": "trainingQuizQuestions.get", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_questions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a training quiz question", "description": "A question of a quiz lesson; its correct option is a training quiz key that learners never read. Returns one training quiz question with its `ETag`. A training quiz question the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training quiz question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training quiz question.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The training quiz question.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_lesson_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "What do you do before a lift?", "options": ["Inspect the sling", "Skip it"] }, "schema": { "$ref": "#/components/schemas/TrainingQuizQuestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "trainingQuizQuestions.update", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_questions", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a training quiz question", "description": "A question of a quiz lesson; its correct option is a training quiz key that learners never read. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training quiz question.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training quiz question.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "position": 1, "prompt": "What do you do before a lift?", "options": ["Inspect the sling", "Skip it"] }, "schema": { "$ref": "#/components/schemas/TrainingQuizQuestionUpdate" } } } }, "responses": { "200": { "description": "The updated training quiz question.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_lesson_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "position": 1, "prompt": "What do you do before a lift?", "options": ["Inspect the sling", "Skip it"] }, "schema": { "$ref": "#/components/schemas/TrainingQuizQuestion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-quiz-keys": { "get": { "operationId": "trainingQuizKeys.list", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_keys", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List training quiz key rows", "description": "The correct option of a quiz question. Only course editors read it. Returns a cursor page of training quiz key rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of training quiz key rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_quiz_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "correct_option": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TrainingQuizKeyPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "trainingQuizKeys.create", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_keys", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a training quiz key", "description": "The correct option of a quiz question. Only course editors read it. Creates a training quiz key. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "training_quiz_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "correct_option": 1 }, "schema": { "$ref": "#/components/schemas/TrainingQuizKeyCreate" } } } }, "responses": { "201": { "description": "The created training quiz key.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_quiz_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "correct_option": 1 }, "schema": { "$ref": "#/components/schemas/TrainingQuizKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-quiz-keys/{id}": { "get": { "operationId": "trainingQuizKeys.get", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_keys", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a training quiz key", "description": "The correct option of a quiz question. Only course editors read it. Returns one training quiz key with its `ETag`. A training quiz key the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training quiz key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training quiz key.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The training quiz key.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_quiz_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "correct_option": 1 }, "schema": { "$ref": "#/components/schemas/TrainingQuizKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "trainingQuizKeys.update", "tags": ["Workforce"], "x-xos-table": "app.training_quiz_keys", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a training quiz key", "description": "The correct option of a quiz question. Only course editors read it. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training quiz key.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training quiz key.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "correct_option": 1 }, "schema": { "$ref": "#/components/schemas/TrainingQuizKeyUpdate" } } } }, "responses": { "200": { "description": "The updated training quiz key.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_quiz_question_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "correct_option": 1 }, "schema": { "$ref": "#/components/schemas/TrainingQuizKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-assignments": { "get": { "operationId": "trainingAssignments.list", "tags": ["Workforce"], "x-xos-table": "app.training_assignments", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List training assignment rows", "description": "A course assigned to a member with a due date. Deleting withdraws it. Returns a cursor page of training assignment rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of training assignment rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assigned_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "reason": "New riggers" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TrainingAssignmentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-assignments/{id}": { "get": { "operationId": "trainingAssignments.get", "tags": ["Workforce"], "x-xos-table": "app.training_assignments", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a training assignment", "description": "A course assigned to a member with a due date. Deleting withdraws it. Returns one training assignment with its `ETag`. A training assignment the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training assignment.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The training assignment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assigned_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "due_on": "2026-10-08", "reason": "New riggers" }, "schema": { "$ref": "#/components/schemas/TrainingAssignment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "trainingAssignments.delete", "tags": ["Workforce"], "x-xos-table": "app.training_assignments", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Delete a training assignment", "description": "A course assigned to a member with a due date. Deleting withdraws it. Soft-deletes the training assignment: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training assignment.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training assignment.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The training assignment moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-completions": { "get": { "operationId": "trainingCompletions.list", "tags": ["Workforce"], "x-xos-table": "app.training_completions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List training completion rows", "description": "A training attempt with its quiz score; a pass carries a certificate number and expiry. Returns a cursor page of training completion rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of training completion rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "score_percent": 90, "passed": true, "completed_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "certificate_number": "TRN-0001", "certification_holder_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/TrainingCompletionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-completions/{id}": { "get": { "operationId": "trainingCompletions.get", "tags": ["Workforce"], "x-xos-table": "app.training_completions", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a training completion", "description": "A training attempt with its quiz score; a pass carries a certificate number and expiry. Returns one training completion with its `ETag`. A training completion the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training completion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training completion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The training completion.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "score_percent": 90, "passed": true, "completed_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "certificate_number": "TRN-0001", "certification_holder_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TrainingCompletion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/training-completions/{id}/issue-certification": { "post": { "operationId": "trainingCompletions.issueCertification", "tags": ["Workforce"], "x-xos-table": "app.training_completions", "x-xos-capability": "people.certification.verify", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["people"] }], "x-xos-rpc": "app.issue_training_certification", "summary": "Issue the certification", "description": "A verifier issues the certification a passed course grants, never the learner. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the training completion.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the training completion.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "training_course_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "score_percent": 90, "passed": true, "completed_at": "2026-10-08T14:30:00Z", "expires_at": "2026-10-08T14:30:00Z", "certificate_number": "TRN-0001", "certification_holder_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/TrainingCompletion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/handbook-sections": { "get": { "operationId": "handbookSections.list", "tags": ["Workforce"], "x-xos-table": "app.handbook_sections", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["position"], "numeric": false }, "summary": "List handbook section rows", "description": "A chapter of the org handbook. Returns a cursor page of handbook section rows the caller may see. The default order is `position` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of handbook section rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Site rules", "position": 1 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/HandbookSectionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "handbookSections.create", "tags": ["Workforce"], "x-xos-table": "app.handbook_sections", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a handbook section", "description": "A chapter of the org handbook. Creates a handbook section. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Site rules", "position": 1 }, "schema": { "$ref": "#/components/schemas/HandbookSectionCreate" } } } }, "responses": { "201": { "description": "The created handbook section.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Site rules", "position": 1 }, "schema": { "$ref": "#/components/schemas/HandbookSection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/handbook-sections/{id}": { "get": { "operationId": "handbookSections.get", "tags": ["Workforce"], "x-xos-table": "app.handbook_sections", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a handbook section", "description": "A chapter of the org handbook. Returns one handbook section with its `ETag`. A handbook section the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the handbook section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the handbook section.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The handbook section.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Site rules", "position": 1 }, "schema": { "$ref": "#/components/schemas/HandbookSection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "handbookSections.update", "tags": ["Workforce"], "x-xos-table": "app.handbook_sections", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a handbook section", "description": "A chapter of the org handbook. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the handbook section.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the handbook section.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Site rules", "position": 1 }, "schema": { "$ref": "#/components/schemas/HandbookSectionUpdate" } } } }, "responses": { "200": { "description": "The updated handbook section.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Site rules", "position": 1 }, "schema": { "$ref": "#/components/schemas/HandbookSection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/handbook-articles": { "get": { "operationId": "handbookArticles.list", "tags": ["Workforce"], "x-xos-table": "app.handbook_articles", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-order": { "by": ["title"], "numeric": false }, "summary": "List handbook article rows", "description": "A handbook or SOP article: versioned on publish, optionally a mandatory read acknowledged per version. Returns a cursor page of handbook article rows the caller may see. The default order is `title` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of handbook article rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true, "article_state": "Draft", "published_version": 1, "published_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/HandbookArticlePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "handbookArticles.create", "tags": ["Workforce"], "x-xos-table": "app.handbook_articles", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Create a handbook article", "description": "A handbook or SOP article: versioned on publish, optionally a mandatory read acknowledged per version. Creates a handbook article. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true }, "schema": { "$ref": "#/components/schemas/HandbookArticleCreate" } } } }, "responses": { "201": { "description": "The created handbook article.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true, "article_state": "Draft", "published_version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HandbookArticle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/handbook-articles/{id}": { "get": { "operationId": "handbookArticles.get", "tags": ["Workforce"], "x-xos-table": "app.handbook_articles", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Get a handbook article", "description": "A handbook or SOP article: versioned on publish, optionally a mandatory read acknowledged per version. Returns one handbook article with its `ETag`. A handbook article the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the handbook article.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the handbook article.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The handbook article.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true, "article_state": "Draft", "published_version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HandbookArticle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "handbookArticles.update", "tags": ["Workforce"], "x-xos-table": "app.handbook_articles", "x-xos-capability": "knowledge.sop.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Update a handbook article", "description": "A handbook or SOP article: versioned on publish, optionally a mandatory read acknowledged per version. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the handbook article.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the handbook article.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true }, "schema": { "$ref": "#/components/schemas/HandbookArticleUpdate" } } } }, "responses": { "200": { "description": "The updated handbook article.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true, "article_state": "Draft", "published_version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HandbookArticle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/handbook-articles/{id}/publish": { "post": { "operationId": "handbookArticles.publish", "tags": ["Workforce"], "x-xos-table": "app.handbook_articles", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.publish_handbook_article", "summary": "Publish an article", "description": "Publishes the working text as the next version; a mandatory article then asks everyone to acknowledge it. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the handbook article.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the handbook article.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "change_summary": "Added the distance." }, "schema": { "$ref": "#/components/schemas/PublishArticleRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true, "article_state": "Draft", "published_version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HandbookArticle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/handbook-articles/{id}/acknowledge": { "post": { "operationId": "handbookArticles.acknowledge", "tags": ["Workforce"], "x-xos-table": "app.handbook_articles", "x-xos-capability": "knowledge.sop.acknowledge", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.acknowledge_handbook_article", "summary": "Acknowledge an article", "description": "Records that the caller read the current version. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the handbook article.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the handbook article.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true, "article_state": "Draft", "published_version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HandbookArticle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/handbook-articles/{id}/archive": { "post": { "operationId": "handbookArticles.archive", "tags": ["Workforce"], "x-xos-table": "app.handbook_articles", "x-xos-capability": "knowledge.sop.publish", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "summary": "Archive an article", "description": "Withdraws a published article. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the handbook article.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the handbook article.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "handbook_section_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "body": "Wear hearing protection near the stacks.", "is_mandatory": true, "article_state": "Draft", "published_version": 1, "published_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HandbookArticle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/knowledge-sources/search": { "get": { "operationId": "knowledgeSources.search", "tags": ["Workforce"], "x-xos-table": "app.assistant_knowledge_sources", "x-xos-capability": "knowledge.sop.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["knowledge"] }], "x-xos-rpc": "app.assistant_knowledge_sources", "summary": "Search knowledge sources", "description": "The Assistant's sources: published handbook articles, SOPs and training lessons the caller can read that match the question, ranked, with routes to cite. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The question.", "example": "hearing protection" }, "required": true, "description": "The question.", "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 25, "description": "At most this many.", "example": 8 }, "required": false, "description": "At most this many.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "source_kind": "Handbook", "source_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Hearing protection", "version": 2, "excerpt": "Wear hearing protection near the stacks.", "route": "/northwind-live/knowledge/handbook?peek=x", "rank": 0.42 } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/KnowledgeSourcePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-teams": { "get": { "operationId": "helpDeskTeams.list", "tags": ["Workforce"], "x-xos-table": "app.help_desk_teams", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["name"], "numeric": false }, "summary": "List help desk team rows", "description": "An internal team that answers help desk requests, with its first response target. Returns a cursor page of help desk team rows the caller may see. The default order is `name` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of help desk team rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "IT Desk", "team_kind": "Operations", "description": "Devices and accounts.", "first_response_hours": 8, "archived_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/HelpDeskTeamPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "helpDeskTeams.create", "tags": ["Workforce"], "x-xos-table": "app.help_desk_teams", "x-xos-capability": "org.help.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a help desk team", "description": "An internal team that answers help desk requests, with its first response target. Creates a help desk team. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "IT Desk", "team_kind": "Operations", "description": "Devices and accounts.", "first_response_hours": 8 }, "schema": { "$ref": "#/components/schemas/HelpDeskTeamCreate" } } } }, "responses": { "201": { "description": "The created help desk team.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "IT Desk", "team_kind": "Operations", "description": "Devices and accounts.", "first_response_hours": 8, "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HelpDeskTeam" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-teams/{id}": { "get": { "operationId": "helpDeskTeams.get", "tags": ["Workforce"], "x-xos-table": "app.help_desk_teams", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a help desk team", "description": "An internal team that answers help desk requests, with its first response target. Returns one help desk team with its `ETag`. A help desk team the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk team.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The help desk team.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "IT Desk", "team_kind": "Operations", "description": "Devices and accounts.", "first_response_hours": 8, "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HelpDeskTeam" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "helpDeskTeams.update", "tags": ["Workforce"], "x-xos-table": "app.help_desk_teams", "x-xos-capability": "org.help.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Update a help desk team", "description": "An internal team that answers help desk requests, with its first response target. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk team.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "IT Desk", "team_kind": "Operations", "description": "Devices and accounts.", "first_response_hours": 8 }, "schema": { "$ref": "#/components/schemas/HelpDeskTeamUpdate" } } } }, "responses": { "200": { "description": "The updated help desk team.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "IT Desk", "team_kind": "Operations", "description": "Devices and accounts.", "first_response_hours": 8, "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HelpDeskTeam" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-teams/{id}/archive": { "post": { "operationId": "helpDeskTeams.archive", "tags": ["Workforce"], "x-xos-table": "app.help_desk_teams", "x-xos-capability": "org.help.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Archive a team", "description": "The team stops taking requests. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk team.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk team.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "IT Desk", "team_kind": "Operations", "description": "Devices and accounts.", "first_response_hours": 8, "archived_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HelpDeskTeam" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-team-members": { "get": { "operationId": "helpDeskTeamMembers.list", "tags": ["Workforce"], "x-xos-table": "app.help_desk_team_members", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List help desk team member rows", "description": "A member who answers a help desk team's requests. Deleting removes them. Returns a cursor page of help desk team member rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of help desk team member rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/HelpDeskTeamMemberPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "helpDeskTeamMembers.create", "tags": ["Workforce"], "x-xos-table": "app.help_desk_team_members", "x-xos-capability": "org.help.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Create a help desk team member", "description": "A member who answers a help desk team's requests. Deleting removes them. Creates a help desk team member. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/HelpDeskTeamMemberCreate" } } } }, "responses": { "201": { "description": "The created help desk team member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/HelpDeskTeamMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-team-members/{id}": { "get": { "operationId": "helpDeskTeamMembers.get", "tags": ["Workforce"], "x-xos-table": "app.help_desk_team_members", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a help desk team member", "description": "A member who answers a help desk team's requests. Deleting removes them. Returns one help desk team member with its `ETag`. A help desk team member the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk team member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk team member.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The help desk team member.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/HelpDeskTeamMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "helpDeskTeamMembers.delete", "tags": ["Workforce"], "x-xos-table": "app.help_desk_team_members", "x-xos-capability": "org.help.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["org"] }], "summary": "Delete a help desk team member", "description": "A member who answers a help desk team's requests. Deleting removes them. Soft-deletes the help desk team member: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk team member.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk team member.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The help desk team member moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-requests": { "get": { "operationId": "helpDeskRequests.list", "tags": ["Workforce"], "x-xos-table": "app.support_tickets", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List help desk request rows", "description": "A help desk request: an Organization queue support ticket routed to an internal team, with assignment and response deadline. Returns a cursor page of help desk request rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of help desk request rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category": "Question", "severity": "Severity 3", "subject": "Tablet will not sign in", "body": "The dock tablet shows a blank screen.", "ticket_state": "Open", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assignee_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/HelpDeskRequestPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "helpDeskRequests.create", "tags": ["Workforce"], "x-xos-table": "app.support_tickets", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Create a help desk request", "description": "A help desk request: an Organization queue support ticket routed to an internal team, with assignment and response deadline. Creates a help desk request. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category": "Question", "severity": "Severity 3", "subject": "Tablet will not sign in", "body": "The dock tablet shows a blank screen." }, "schema": { "$ref": "#/components/schemas/HelpDeskRequestCreate" } } } }, "responses": { "201": { "description": "The created help desk request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category": "Question", "severity": "Severity 3", "subject": "Tablet will not sign in", "body": "The dock tablet shows a blank screen.", "ticket_state": "Open", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assignee_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HelpDeskRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-requests/{id}": { "get": { "operationId": "helpDeskRequests.get", "tags": ["Workforce"], "x-xos-table": "app.support_tickets", "x-xos-capability": "inbox.notifications.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "summary": "Get a help desk request", "description": "A help desk request: an Organization queue support ticket routed to an internal team, with assignment and response deadline. Returns one help desk request with its `ETag`. A help desk request the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The help desk request.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category": "Question", "severity": "Severity 3", "subject": "Tablet will not sign in", "body": "The dock tablet shows a blank screen.", "ticket_state": "Open", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assignee_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HelpDeskRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-requests/{id}/assign": { "post": { "operationId": "helpDeskRequests.assign", "tags": ["Workforce"], "x-xos-table": "app.support_tickets", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "app.assign_help_desk_request", "summary": "Assign a request", "description": "Assigns the request to a member of its team, optionally moving it to another team. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "assignee_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/AssignHelpDeskRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "ticket_number": "SUP-0001", "help_desk_team_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category": "Question", "severity": "Severity 3", "subject": "Tablet will not sign in", "body": "The dock tablet shows a blank screen.", "ticket_state": "Open", "membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "assignee_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "help_desk_response_due_at": "2026-10-08T14:30:00Z", "first_responded_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/HelpDeskRequest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-requests/{id}/answer": { "post": { "operationId": "helpDeskRequests.answer", "tags": ["Workforce"], "x-xos-table": "app.support_tickets", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "app.answer_help_desk_request", "summary": "Answer a request", "description": "A team member answers; the first answer records the response time. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "body": "Restarting the profile now." }, "schema": { "$ref": "#/components/schemas/AnswerHelpDeskRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "message_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/HelpDeskAnswer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/help-desk-requests/{id}/transition": { "post": { "operationId": "helpDeskRequests.transition", "tags": ["Workforce"], "x-xos-table": "app.support_tickets", "x-xos-capability": "inbox.notifications.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["inbox"] }], "x-xos-rpc": "app.transition_help_desk_request", "summary": "Move a request", "description": "A team member moves the request through Open, Waiting, Resolved and Closed with a reason. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the help desk request.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the help desk request.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "expected_state": "Open", "to_state": "Resolved", "reason": "Ready to go." }, "schema": { "$ref": "#/components/schemas/HelpDeskTransitionRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "ledger_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WorkforceLedgerEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/occupancy-counters": { "get": { "operationId": "occupancyCounters.list", "tags": ["Workforce"], "x-xos-table": "app.occupancy_counters", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["name"], "numeric": false }, "summary": "List occupancy counter rows", "description": "A live occupancy counter against the permitted occupant load, with alerts at 80, 90 and 100 percent. Returns a cursor page of occupancy counter rows the caller may see. The default order is `name` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of occupancy counter rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Main Floor", "load_basis": "Occupant Load Factor", "metric_domain": "capacity", "metric_item": "Assembly - standing space", "permitted_load": 100, "current_count": 82, "alert_level_percent": 80, "closed_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/OccupancyCounterPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/occupancy-counters/{id}": { "get": { "operationId": "occupancyCounters.get", "tags": ["Workforce"], "x-xos-table": "app.occupancy_counters", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get an occupancy counter", "description": "A live occupancy counter against the permitted occupant load, with alerts at 80, 90 and 100 percent. Returns one occupancy counter with its `ETag`. A occupancy counter the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the occupancy counter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the occupancy counter.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The occupancy counter.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Main Floor", "load_basis": "Occupant Load Factor", "metric_domain": "capacity", "metric_item": "Assembly - standing space", "permitted_load": 100, "current_count": 82, "alert_level_percent": 80, "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OccupancyCounter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/occupancy-counters/set-up": { "post": { "operationId": "occupancyCounters.setUp", "tags": ["Workforce"], "x-xos-table": "app.occupancy_counters", "x-xos-capability": "safety.emergency_code.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-rpc": "app.create_occupancy_counter", "summary": "Set up a counter", "description": "Sets up a counter sized by a permit load, a Bible occupant load factor or the space capacity. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Main Floor", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_item": "Assembly - standing space", "permitted_load": 400 }, "schema": { "$ref": "#/components/schemas/OccupancyCounterCreateRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Main Floor", "load_basis": "Occupant Load Factor", "metric_domain": "capacity", "metric_item": "Assembly - standing space", "permitted_load": 100, "current_count": 82, "alert_level_percent": 80, "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OccupancyCounter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/occupancy-counters/{id}/count": { "post": { "operationId": "occupancyCounters.count", "tags": ["Workforce"], "x-xos-table": "app.occupancy_counters", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-rpc": "app.record_occupancy_count", "summary": "Count people in or out", "description": "Counts people in (positive) or out (negative) at a door. Crossing 80, 90 or 100 percent alerts the dispatchers. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the occupancy counter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the occupancy counter.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "delta": 1, "door": "Gate A" }, "schema": { "$ref": "#/components/schemas/OccupancyCountRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Main Floor", "load_basis": "Occupant Load Factor", "metric_domain": "capacity", "metric_item": "Assembly - standing space", "permitted_load": 100, "current_count": 82, "alert_level_percent": 80, "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OccupancyCounter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/occupancy-counters/{id}/close": { "post": { "operationId": "occupancyCounters.close", "tags": ["Workforce"], "x-xos-table": "app.occupancy_counters", "x-xos-capability": "safety.emergency_code.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-rpc": "app.close_occupancy_counter", "summary": "Close a counter", "description": "Stops counting. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the occupancy counter.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the occupancy counter.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "space_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "name": "Main Floor", "load_basis": "Occupant Load Factor", "metric_domain": "capacity", "metric_item": "Assembly - standing space", "permitted_load": 100, "current_count": 82, "alert_level_percent": 80, "closed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/OccupancyCounter" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-thresholds": { "get": { "operationId": "weatherThresholds.list", "tags": ["Workforce"], "x-xos-table": "app.weather_thresholds", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List weather threshold rows", "description": "A weather action threshold of a project: one value per hazard and level, with its emergency plan source. Returns a cursor page of weather threshold rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of weather threshold rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "alert_level": "Monitor", "threshold_value": 30, "unit": "mph", "comparison": "At or Above", "source_note": "Emergency plan 4.2" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WeatherThresholdPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "weatherThresholds.create", "tags": ["Workforce"], "x-xos-table": "app.weather_thresholds", "x-xos-capability": "safety.emergency_code.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a weather threshold", "description": "A weather action threshold of a project: one value per hazard and level, with its emergency plan source. Creates a weather threshold. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "alert_level": "Monitor", "threshold_value": 30, "unit": "mph", "comparison": "At or Above", "source_note": "Emergency plan 4.2" }, "schema": { "$ref": "#/components/schemas/WeatherThresholdCreate" } } } }, "responses": { "201": { "description": "The created weather threshold.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "alert_level": "Monitor", "threshold_value": 30, "unit": "mph", "comparison": "At or Above", "source_note": "Emergency plan 4.2" }, "schema": { "$ref": "#/components/schemas/WeatherThreshold" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-thresholds/{id}": { "get": { "operationId": "weatherThresholds.get", "tags": ["Workforce"], "x-xos-table": "app.weather_thresholds", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a weather threshold", "description": "A weather action threshold of a project: one value per hazard and level, with its emergency plan source. Returns one weather threshold with its `ETag`. A weather threshold the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the weather threshold.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the weather threshold.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The weather threshold.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "alert_level": "Monitor", "threshold_value": 30, "unit": "mph", "comparison": "At or Above", "source_note": "Emergency plan 4.2" }, "schema": { "$ref": "#/components/schemas/WeatherThreshold" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "weatherThresholds.update", "tags": ["Workforce"], "x-xos-table": "app.weather_thresholds", "x-xos-capability": "safety.emergency_code.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update a weather threshold", "description": "A weather action threshold of a project: one value per hazard and level, with its emergency plan source. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the weather threshold.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the weather threshold.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "threshold_value": 30, "source_note": "Emergency plan 4.2" }, "schema": { "$ref": "#/components/schemas/WeatherThresholdUpdate" } } } }, "responses": { "200": { "description": "The updated weather threshold.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "alert_level": "Monitor", "threshold_value": 30, "unit": "mph", "comparison": "At or Above", "source_note": "Emergency plan 4.2" }, "schema": { "$ref": "#/components/schemas/WeatherThreshold" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-alert-roles": { "get": { "operationId": "weatherAlertRoles.list", "tags": ["Workforce"], "x-xos-table": "app.weather_alert_roles", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List weather alert role rows", "description": "A canon role the emergency plan names for a weather level; people assigned it on the project are alerted. Returns a cursor page of weather alert role rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of weather alert role rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "alert_level": "Monitor", "role_code": "5000.01.01" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WeatherAlertRolePage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "weatherAlertRoles.create", "tags": ["Workforce"], "x-xos-table": "app.weather_alert_roles", "x-xos-capability": "safety.emergency_code.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a weather alert role", "description": "A canon role the emergency plan names for a weather level; people assigned it on the project are alerted. Creates a weather alert role. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "alert_level": "Monitor", "role_code": "5000.01.01" }, "schema": { "$ref": "#/components/schemas/WeatherAlertRoleCreate" } } } }, "responses": { "201": { "description": "The created weather alert role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "alert_level": "Monitor", "role_code": "5000.01.01" }, "schema": { "$ref": "#/components/schemas/WeatherAlertRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-alert-roles/{id}": { "get": { "operationId": "weatherAlertRoles.get", "tags": ["Workforce"], "x-xos-table": "app.weather_alert_roles", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a weather alert role", "description": "A canon role the emergency plan names for a weather level; people assigned it on the project are alerted. Returns one weather alert role with its `ETag`. A weather alert role the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the weather alert role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the weather alert role.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The weather alert role.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "alert_level": "Monitor", "role_code": "5000.01.01" }, "schema": { "$ref": "#/components/schemas/WeatherAlertRole" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "weatherAlertRoles.delete", "tags": ["Workforce"], "x-xos-table": "app.weather_alert_roles", "x-xos-capability": "safety.emergency_code.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Delete a weather alert role", "description": "A canon role the emergency plan names for a weather level; people assigned it on the project are alerted. Soft-deletes the weather alert role: it moves to Trash and can be restored for its table's retention period.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the weather alert role.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the weather alert role.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "The weather alert role moved to Trash." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-readings": { "get": { "operationId": "weatherReadings.list", "tags": ["Workforce"], "x-xos-table": "app.weather_readings", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["observed_at"], "numeric": false, "descending": true }, "summary": "List weather reading rows", "description": "A weather reading on site, in the hazard's unit. Returns a cursor page of weather reading rows the caller may see. The default order is `observed_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of weather reading rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "reading_value": 33, "observed_at": "2026-10-08T14:30:00Z", "recorded_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WeatherReadingPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "weatherReadings.create", "tags": ["Workforce"], "x-xos-table": "app.weather_readings", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a weather reading", "description": "A weather reading on site, in the hazard's unit. Creates a weather reading. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "reading_value": 33, "observed_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WeatherReadingCreate" } } } }, "responses": { "201": { "description": "The created weather reading.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "reading_value": 33, "observed_at": "2026-10-08T14:30:00Z", "recorded_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WeatherReading" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-readings/{id}": { "get": { "operationId": "weatherReadings.get", "tags": ["Workforce"], "x-xos-table": "app.weather_readings", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a weather reading", "description": "A weather reading on site, in the hazard's unit. Returns one weather reading with its `ETag`. A weather reading the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the weather reading.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the weather reading.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The weather reading.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "reading_value": 33, "observed_at": "2026-10-08T14:30:00Z", "recorded_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/WeatherReading" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-alerts": { "get": { "operationId": "weatherAlerts.list", "tags": ["Workforce"], "x-xos-table": "app.weather_alerts", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["issued_at"], "numeric": false, "descending": true }, "summary": "List weather alert rows", "description": "A weather alert raised by a reading at the highest level met, cleared when readings fall below every level. Returns a cursor page of weather alert rows the caller may see. The default order is `issued_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of weather alert rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "alert_level": "Monitor", "weather_reading_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_at": "2026-10-08T14:30:00Z", "cleared_at": "2026-10-08T14:30:00Z" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/WeatherAlertPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/weather-alerts/{id}": { "get": { "operationId": "weatherAlerts.get", "tags": ["Workforce"], "x-xos-table": "app.weather_alerts", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a weather alert", "description": "A weather alert raised by a reading at the highest level met, cleared when readings fall below every level. Returns one weather alert with its `ETag`. A weather alert the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the weather alert.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the weather alert.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The weather alert.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "hazard": "Wind", "alert_level": "Monitor", "weather_reading_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "issued_at": "2026-10-08T14:30:00Z", "cleared_at": "2026-10-08T14:30:00Z" }, "schema": { "$ref": "#/components/schemas/WeatherAlert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/guest-check-ins": { "get": { "operationId": "guestCheckIns.list", "tags": ["Workforce"], "x-xos-table": "app.guest_check_ins", "x-xos-capability": "credentials.scan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List guest check in rows", "description": "A door check-in of an approved guest with plus-ones admitted and the credential scanned. Returns a cursor page of guest check in rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of guest check in rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_list_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "plus_ones_admitted": 2, "credential_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "door": "Gate A", "checked_in_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/GuestCheckInPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "guestCheckIns.create", "tags": ["Workforce"], "x-xos-table": "app.guest_check_ins", "x-xos-capability": "credentials.scan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Create a guest check in", "description": "A door check-in of an approved guest with plus-ones admitted and the credential scanned. Creates a guest check in. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "guest_list_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "plus_ones_admitted": 2, "door": "Gate A" }, "schema": { "$ref": "#/components/schemas/GuestCheckInCreate" } } } }, "responses": { "201": { "description": "The created guest check in.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_list_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "plus_ones_admitted": 2, "credential_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "door": "Gate A", "checked_in_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/GuestCheckIn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/guest-check-ins/{id}": { "get": { "operationId": "guestCheckIns.get", "tags": ["Workforce"], "x-xos-table": "app.guest_check_ins", "x-xos-capability": "credentials.scan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "summary": "Get a guest check in", "description": "A door check-in of an approved guest with plus-ones admitted and the credential scanned. Returns one guest check in with its `ETag`. A guest check in the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the guest check in.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the guest check in.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The guest check in.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_list_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "plus_ones_admitted": 2, "credential_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "door": "Gate A", "checked_in_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "schema": { "$ref": "#/components/schemas/GuestCheckIn" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/guest-check-ins/door-list": { "get": { "operationId": "guestCheckIns.doorList", "tags": ["Workforce"], "x-xos-table": "app.guest_check_ins", "x-xos-capability": "credentials.scan.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["credentials"] }], "x-xos-rpc": "app.door_guest_list", "summary": "Door list", "description": "Approved and checked-in guests of a project for door staff, filtered by name. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Project.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Project.", "name": "project_id", "in": "query" }, { "schema": { "type": "string", "maxLength": 200, "description": "Name contains this.", "example": "jordan" }, "required": false, "description": "Name contains this.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "guest_list_entry_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "guest_name": "Jordan Ellis", "plus_ones": 2, "entry_state": "Approved", "note": "Side stage.", "checked_in_at": "2026-10-08T14:30:00Z", "plus_ones_admitted": 2, "door": "Gate A" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/DoorGuestPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/lost-found-items": { "get": { "operationId": "lostFoundItems.list", "tags": ["Workforce"], "x-xos-table": "app.lost_found_items", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["found_at"], "numeric": false, "descending": true }, "summary": "List lost found item rows", "description": "An item in the lost and found log, with photos as attachments and its claim state. Returns a cursor page of lost found item rows the caller may see. The default order is `found_at` descending, newest first. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of lost found item rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_number": "LF-0001", "category": "Wallet", "description": "Brown leather wallet.", "found_at": "2026-10-08T14:30:00Z", "found_location": "Bar 2", "storage_location": "Security office locker 4", "logged_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_state": "Logged" } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/LostFoundItemPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "lostFoundItems.create", "tags": ["Workforce"], "x-xos-table": "app.lost_found_items", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Create a lost found item", "description": "An item in the lost and found log, with photos as attachments and its claim state. Creates a lost found item. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "example": { "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "category": "Wallet", "description": "Brown leather wallet.", "found_at": "2026-10-08T14:30:00Z", "found_location": "Bar 2", "storage_location": "Security office locker 4" }, "schema": { "$ref": "#/components/schemas/LostFoundItemCreate" } } } }, "responses": { "201": { "description": "The created lost found item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_number": "LF-0001", "category": "Wallet", "description": "Brown leather wallet.", "found_at": "2026-10-08T14:30:00Z", "found_location": "Bar 2", "storage_location": "Security office locker 4", "logged_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_state": "Logged" }, "schema": { "$ref": "#/components/schemas/LostFoundItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/lost-found-items/{id}": { "get": { "operationId": "lostFoundItems.get", "tags": ["Workforce"], "x-xos-table": "app.lost_found_items", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a lost found item", "description": "An item in the lost and found log, with photos as attachments and its claim state. Returns one lost found item with its `ETag`. A lost found item the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the lost found item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the lost found item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The lost found item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_number": "LF-0001", "category": "Wallet", "description": "Brown leather wallet.", "found_at": "2026-10-08T14:30:00Z", "found_location": "Bar 2", "storage_location": "Security office locker 4", "logged_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_state": "Logged" }, "schema": { "$ref": "#/components/schemas/LostFoundItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "lostFoundItems.update", "tags": ["Workforce"], "x-xos-table": "app.lost_found_items", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Update a lost found item", "description": "An item in the lost and found log, with photos as attachments and its claim state. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the lost found item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the lost found item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "category": "Wallet", "description": "Brown leather wallet.", "storage_location": "Security office locker 4" }, "schema": { "$ref": "#/components/schemas/LostFoundItemUpdate" } } } }, "responses": { "200": { "description": "The updated lost found item.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_number": "LF-0001", "category": "Wallet", "description": "Brown leather wallet.", "found_at": "2026-10-08T14:30:00Z", "found_location": "Bar 2", "storage_location": "Security office locker 4", "logged_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_state": "Logged" }, "schema": { "$ref": "#/components/schemas/LostFoundItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/lost-found-items/{id}/claim": { "post": { "operationId": "lostFoundItems.claim", "tags": ["Workforce"], "x-xos-table": "app.lost_found_items", "x-xos-capability": "safety.incident.write", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-rpc": "app.claim_lost_item", "summary": "Record a claim", "description": "Records a claim on a held item with the claimant's name, contact and proof. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the lost found item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the lost found item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claimant_name": "Riley Park", "claimant_contact": "+1 305 555 0142", "proof_description": "Named the card inside." }, "schema": { "$ref": "#/components/schemas/LostItemClaimRequest" } } } }, "responses": { "201": { "description": "The result.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lost_found_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "claimant_name": "Riley Park", "claimant_contact": "+1 305 555 0142", "proof_description": "Named the card inside.", "recorded_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "returned": true, "decision_note": "ID matched." }, "schema": { "$ref": "#/components/schemas/LostFoundClaim" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/lost-found-items/{id}/dispose": { "post": { "operationId": "lostFoundItems.dispose", "tags": ["Workforce"], "x-xos-table": "app.lost_found_items", "x-xos-capability": "safety.incident.close", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-rpc": "app.dispose_lost_item", "summary": "Dispose of an item", "description": "Disposes of an unclaimed held item with a reason. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the lost found item.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the lost found item.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "Posted to the wrong project." }, "schema": { "$ref": "#/components/schemas/DisposeLostItemRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_number": "LF-0001", "category": "Wallet", "description": "Brown leather wallet.", "found_at": "2026-10-08T14:30:00Z", "found_location": "Bar 2", "storage_location": "Security office locker 4", "logged_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "item_state": "Logged" }, "schema": { "$ref": "#/components/schemas/LostFoundItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/lost-found-claims": { "get": { "operationId": "lostFoundClaims.list", "tags": ["Workforce"], "x-xos-table": "app.lost_found_claims", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-order": { "by": ["created_at"], "numeric": false }, "summary": "List lost found claim rows", "description": "A claim on a lost item: the claimant, their contact (Confidential), their proof and how it was settled. Returns a cursor page of lost found claim rows the caller may see. The default order is `created_at` ascending. Supports sparse fieldsets and the filter grammar.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Fields" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Filter" } ], "responses": { "200": { "description": "A page of lost found claim rows.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "data": [ { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lost_found_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "claimant_name": "Riley Park", "claimant_contact": "+1 305 555 0142", "proof_description": "Named the card inside.", "recorded_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "returned": true, "decision_note": "ID matched." } ], "next_cursor": null }, "schema": { "$ref": "#/components/schemas/LostFoundClaimPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/lost-found-claims/{id}": { "get": { "operationId": "lostFoundClaims.get", "tags": ["Workforce"], "x-xos-table": "app.lost_found_claims", "x-xos-capability": "safety.incident.read", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "summary": "Get a lost found claim", "description": "A claim on a lost item: the claimant, their contact (Confidential), their proof and how it was settled. Returns one lost found claim with its `ETag`. A lost found claim the caller may not see returns 404.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the lost found claim.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the lost found claim.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/Fields" } ], "responses": { "200": { "description": "The lost found claim.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lost_found_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "claimant_name": "Riley Park", "claimant_contact": "+1 305 555 0142", "proof_description": "Named the card inside.", "recorded_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "returned": true, "decision_note": "ID matched." }, "schema": { "$ref": "#/components/schemas/LostFoundClaim" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/lost-found-claims/{id}/settle": { "post": { "operationId": "lostFoundClaims.settle", "tags": ["Workforce"], "x-xos-table": "app.lost_found_claims", "x-xos-capability": "safety.incident.close", "security": [{ "bearerJwt": [] }, { "apiKey": [] }, { "oauth2": ["safety"] }], "x-xos-rpc": "app.settle_lost_item_claim", "summary": "Settle a claim", "description": "Returns the item to the verified claimant, or rejects the claim with a reason. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Identifier of the lost found claim.", "example": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" }, "required": true, "description": "Identifier of the lost found claim.", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "returned": true, "note": "ID matched." }, "schema": { "$ref": "#/components/schemas/SettleClaimRequest" } } } }, "responses": { "200": { "description": "The result.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "example": { "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "created_at": "2026-10-08T14:30:00Z", "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "updated_at": "2026-10-08T14:30:00Z", "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "lost_found_item_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "claimant_name": "Riley Park", "claimant_contact": "+1 305 555 0142", "proof_description": "Named the card inside.", "recorded_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_by_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "decided_at": "2026-10-08T14:30:00Z", "returned": true, "decision_note": "ID matched." }, "schema": { "$ref": "#/components/schemas/LostFoundClaim" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": {} }