{ "openapi": "3.1.0", "info": { "title": "Remote Pro Ai Platform API", "version": "0.1.0", "summary": "Intake, scheduling, pricing, booking, Client OS, Talent OS, Trust Center and status for remote-pro.ai.", "description": "Generated from the platform route table (npm run openapi) — the published document equals the routes the server serves (contract-tested). Staff-only routes are never listed. Auth: session cookie (__Host-rp_session) + X-CSRF on cookie writes, or a Bearer session / OAuth 2.1 token. Errors use one bilingual envelope (EN/AR). Writes that create or pay accept an Idempotency-Key. Times are ISO 8601 with a zone; money is { amount, amount_minor, currency, display }.", "contact": { "name": "Remote Pro Ai", "email": "info@remote-pro.ai", "url": "https://remote-pro.ai/mcp/docs" } }, "servers": [ { "url": "https://remote-pro.ai", "description": "Production — one origin: the website and /api (also mcp.remote-pro.ai for /mcp, /v1, /oauth)" } ], "tags": [ { "name": "Agents" }, { "name": "Auth" }, { "name": "Billing" }, { "name": "Bookings" }, { "name": "Calendar" }, { "name": "Client OS" }, { "name": "Contracts" }, { "name": "Dev" }, { "name": "Intake" }, { "name": "MCP" }, { "name": "Meta" }, { "name": "OAuth" }, { "name": "Organisations" }, { "name": "Payments" }, { "name": "Proposals" }, { "name": "Quotes" }, { "name": "Scheduling" }, { "name": "Status" }, { "name": "Support" }, { "name": "System" }, { "name": "Talent" }, { "name": "Talent OS" }, { "name": "Tour" }, { "name": "Trust" }, { "name": "Webhooks" }, { "name": "talent" } ], "paths": { "/api/v1/agents/scope": { "post": { "operationId": "post_agents_scope", "summary": "Run the scope agent (proxy to the agent registry; 503 agent_unavailable when not registered)", "tags": [ "Agents" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messages": { "type": "array", "maxItems": 40, "items": { "type": "object", "properties": { "role": { "enum": [ "user", "assistant" ] }, "content": { "type": "string", "maxLength": 4000 } } } }, "text": { "type": "string", "maxLength": 4000 }, "context": { "type": "object" }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "buyer_country": { "type": "string", "maxLength": 2 }, "lang": { "enum": [ "en", "ar" ] } } } } } }, "responses": { "200": { "description": "Agent output (draft/answer) with run id and provider", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "description": "agent_unavailable" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "write" } }, "/api/v1/agents/rfp": { "post": { "operationId": "post_agents_rfp", "summary": "Run the rfp agent (proxy to the agent registry; 503 agent_unavailable when not registered)", "tags": [ "Agents" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "additionalProperties": false, "properties": { "question": { "type": "string", "minLength": 3, "maxLength": 2000 }, "context": { "type": "object" }, "lang": { "enum": [ "en", "ar" ] } } } } } }, "responses": { "200": { "description": "Agent output (draft/answer) with run id and provider", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "description": "agent_unavailable" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "write" } }, "/api/v1/agents/support": { "post": { "operationId": "post_agents_support", "summary": "Run the support agent (proxy to the agent registry; 503 agent_unavailable when not registered)", "tags": [ "Agents" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "additionalProperties": false, "properties": { "message": { "type": "string", "minLength": 2, "maxLength": 4000 }, "context": { "type": "object" }, "lang": { "enum": [ "en", "ar" ] } } } } } }, "responses": { "200": { "description": "Agent output (draft/answer) with run id and provider", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "description": "agent_unavailable" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "write" } }, "/api/v1/app/dashboard": { "get": { "operationId": "get_app_dashboard", "summary": "Client OS home: engagement, squad, trial, open invoices, SLA credits, pending approvals, bookings in progress", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Dashboard" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/app/roster": { "get": { "operationId": "get_app_roster", "summary": "Squad roster = Order Form lines with the anonymised specialist on each seat", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Roster" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/app/timesheets": { "get": { "operationId": "get_app_timesheets", "summary": "Weekly timesheets of the current engagement (newest first)", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "submitted", "approved", "auto_approved", "disputed", "locked", "draft" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Timesheets" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } }, "post": { "operationId": "post_app_timesheets", "summary": "Batch action on submitted timesheets: approve, or dispute with a reason", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "ids" ], "additionalProperties": false, "properties": { "action": { "enum": [ "approve", "dispute" ] }, "ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Updated" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client", "roles": [ "Admin", "Approver", "admin", "approver" ] } } }, "/api/v1/app/timesheets/{id}/approve": { "post": { "operationId": "post_app_timesheets_id_approve", "summary": "Approve one submitted timesheet", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Approved" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Not in submitted state" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client", "roles": [ "Admin", "Approver", "admin", "approver" ] } } }, "/api/v1/app/sla": { "get": { "operationId": "get_app_sla", "summary": "SLA commitments and service credits (5–15 % of the monthly fee, capped at 15 %)", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "SLA" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/app/invoices": { "get": { "operationId": "get_app_invoices", "summary": "Invoices with entity, VAT and e-invoice status (zatca | peppol | eta | none)", "tags": [ "Client OS", "Billing" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Invoices" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/app/invoices/{id}": { "get": { "operationId": "get_app_invoices_id", "summary": "One invoice; `{id}.xml` = the e-invoice XML (ZATCA UBL 2.1 / Peppol BIS 3), `{id}.pdf` = printable tax invoice (HTML fallback)", "tags": [ "Client OS", "Billing" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}(\\.(xml|pdf))?$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Invoice JSON, application/xml or text/html" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/app/seats": { "post": { "operationId": "post_app_seats", "summary": "Seat change → repriced with the R30 engine → amendment (contract kind amendment, sha256) → e-sign via POST /v1/contracts/{id}/sign", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "change" ], "additionalProperties": false, "properties": { "change": { "type": "object", "required": [ "action" ], "additionalProperties": false, "properties": { "action": { "enum": [ "add", "remove", "change_level", "change_hours" ] }, "seat_id": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" }, "practice": { "type": "string", "maxLength": 40 }, "level": { "enum": [ "mid", "senior", "lead" ] }, "hours": { "enum": [ 80, 160 ] }, "count": { "type": "integer", "minimum": 1, "maximum": 10 }, "effective_on": { "type": "string", "format": "date" } } } } } } } }, "responses": { "201": { "description": "Amendment issued" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client", "roles": [ "Admin", "Approver", "admin", "approver" ] } } }, "/api/v1/app/replace": { "post": { "operationId": "post_app_replace", "summary": "Request a replacement for a seat (proposal within 10 business days; practice-lead inbox)", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "seat_id", "reason" ], "additionalProperties": false, "properties": { "seat_id": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" }, "reason": { "type": "string", "minLength": 3, "maxLength": 1000 } } } } } }, "responses": { "201": { "description": "Replacement requested" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client", "roles": [ "Admin", "Approver", "admin", "approver" ] } } }, "/api/v1/app/documents": { "get": { "operationId": "get_app_documents", "summary": "Contracts and documents of the organisation with hashes and links", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Documents" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/app/nps": { "post": { "operationId": "post_app_nps", "summary": "Record a Net Promoter Score (0–10) for the current month", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "score" ], "additionalProperties": false, "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 10 }, "comment": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Recorded" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/support/tickets": { "post": { "operationId": "post_support_tickets", "summary": "Open a support ticket → { ticket_id, first_response: { by, answer, sources, escalate } } (support agent; honest escalation)", "tags": [ "Client OS", "Support" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "additionalProperties": false, "properties": { "subject": { "type": "string", "maxLength": 200 }, "message": { "type": "string", "minLength": 3, "maxLength": 5000 }, "lang": { "enum": [ "en", "ar" ] }, "priority": { "enum": [ "low", "normal", "high", "urgent" ] } } } } } }, "responses": { "201": { "description": "Ticket opened" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/appointments/slots": { "get": { "operationId": "get_appointments_slots", "summary": "Available slots in the visitor’s time zone (never past, working days of host and visitor); `days` = number of days with availability to return", "tags": [ "Scheduling" ], "security": [], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "enum": [ "scoping_call" ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string", "format": "time-zone" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "format": "country" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 14 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Slots grouped by local date", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/appointments/kinds": { "get": { "operationId": "get_appointments_kinds", "summary": "Meeting kinds offered by the scheduler (config/scheduler.json) with their durations", "tags": [ "Scheduling" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Kinds", "content": { "application/json": { "schema": { "type": "object", "properties": { "kinds": { "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/appointments": { "post": { "operationId": "post_appointments", "summary": "Book a slot; sends the confirmation with a full ICS invite", "tags": [ "Scheduling" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "start", "tz", "attendee", "consent" ], "additionalProperties": false, "properties": { "kind": { "enum": [ "scoping_call" ], "default": "scoping_call" }, "start": { "type": "string", "format": "date-time" }, "tz": { "type": "string", "format": "time-zone" }, "country": { "type": "string", "format": "country" }, "lang": { "enum": [ "en", "ar" ] }, "attendee": { "type": "object", "required": [ "name", "email" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email" }, "company": { "type": "string", "maxLength": 160 }, "phone": { "type": "string", "format": "e164" } } }, "answers": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "consent": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "const": true }, "policy_version": { "type": "string", "maxLength": 20 } } } } } } } }, "responses": { "201": { "description": "Booked", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Slot taken" }, "422": { "description": "Slot in the past" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/appointments/{reference}": { "get": { "operationId": "get_appointments_reference", "summary": "Appointment (manage link)", "tags": [ "Scheduling" ], "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^APT-(\\d{4}|DEMO)-\\d{6}$" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 64 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Appointment" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/appointments/{reference}/ics": { "get": { "operationId": "get_appointments_reference_ics", "summary": "Download the ICS invite", "tags": [ "Scheduling" ], "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^APT-(\\d{4}|DEMO)-\\d{6}$" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 64 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "text/calendar", "content": { "text/calendar": {} } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/appointments/{reference}/cancel": { "post": { "operationId": "post_appointments_reference_cancel", "summary": "Cancel (sends an ICS cancellation)", "tags": [ "Scheduling" ], "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^APT-(\\d{4}|DEMO)-\\d{6}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "additionalProperties": false, "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Cancelled" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/auth/start": { "post": { "operationId": "post_auth_start", "summary": "Email a one-time sign-in code (no account enumeration; dev_code only with --env development)", "tags": [ "Auth" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "kind": { "enum": [ "client", "talent" ], "default": "client" }, "lang": { "enum": [ "en", "ar" ] }, "next": { "type": "string", "maxLength": 300, "pattern": "^/" } } } } } }, "responses": { "200": { "description": "Code issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "sent" }, "channel": { "const": "email" }, "delivery": { "type": "string" }, "expires_at": { "type": "string" }, "resend_after_s": { "type": "integer" }, "dev_code": { "type": "string", "description": "Only with --env development" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/verify": { "post": { "operationId": "post_auth_verify", "summary": "Exchange the code for a session (HttpOnly cookie) and a CSRF token (rp_csrf cookie + body)", "tags": [ "Auth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "kind": { "enum": [ "client", "talent" ], "default": "client" } } } } } }, "responses": { "200": { "description": "Signed in", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "token_invalid" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/logout": { "post": { "operationId": "post_auth_logout", "summary": "Sign out: revoke the session and clear the cookies", "tags": [ "Auth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Signed out" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/step-up/start": { "post": { "operationId": "post_auth_step_up_start", "summary": "Email a step-up code to the signed-in person (before signing, paying or access changes)", "tags": [ "Auth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Code issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "sent" }, "channel": { "const": "email" }, "delivery": { "type": "string" }, "expires_at": { "type": "string" }, "resend_after_s": { "type": "integer" }, "dev_code": { "type": "string", "description": "Only with --env development" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/step-up": { "post": { "operationId": "post_auth_step_up", "summary": "Confirm a step-up code ({ code }); without a code, emails one (same as /step-up/start)", "tags": [ "Auth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "Step-up fresh, or code sent", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "token_invalid" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/passkeys/register/options": { "post": { "operationId": "post_auth_passkeys_register_options", "summary": "Passkey registration options (WebAuthn create): needs a session with a fresh step-up; attestation \"none\", user verification required", "tags": [ "Auth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "PublicKeyCredentialCreationOptions (base64url fields)" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "description": "step_up_required" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "description": "Passkeys disabled on this server" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/passkeys/register/verify": { "post": { "operationId": "post_auth_passkeys_register_verify", "summary": "Verify a passkey registration and store the credential (COSE public key, sign count, AAGUID, backup state)", "tags": [ "Auth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "response" ], "properties": { "id": { "type": "string", "maxLength": 1400 }, "rawId": { "type": "string", "maxLength": 1400 }, "type": { "const": "public-key" }, "response": { "type": "object" }, "nickname": { "type": "string", "maxLength": 60 }, "authenticatorAttachment": { "type": [ "string", "null" ] }, "clientExtensionResults": { "type": "object" } } } } } }, "responses": { "201": { "description": "Passkey stored" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "token_invalid (verification failed)" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "description": "Passkeys disabled on this server" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/passkeys/login/options": { "post": { "operationId": "post_auth_passkeys_login_options", "summary": "Passkey sign-in options (WebAuthn get, discoverable credentials; no account enumeration)", "tags": [ "Auth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "PublicKeyCredentialRequestOptions" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "description": "Passkeys disabled on this server" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/auth/passkeys/login/verify": { "post": { "operationId": "post_auth_passkeys_login_verify", "summary": "Verify a passkey assertion → session (HttpOnly cookie) + CSRF token, with a fresh step-up", "tags": [ "Auth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "response" ], "properties": { "id": { "type": "string", "maxLength": 1400 }, "rawId": { "type": "string", "maxLength": 1400 }, "type": { "const": "public-key" }, "response": { "type": "object" }, "nickname": { "type": "string", "maxLength": 60 }, "authenticatorAttachment": { "type": [ "string", "null" ] }, "clientExtensionResults": { "type": "object" } } } } } }, "responses": { "200": { "description": "Signed in" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "token_invalid (verification failed)" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "description": "Passkeys disabled on this server" } }, "x-owner": "pl-core", "x-rate-limit-bucket": "auth" } }, "/api/v1/availability": { "get": { "operationId": "get_availability", "summary": "Availability band for a practice (bands only, never counts below 5)", "tags": [ "Talent" ], "security": [], "parameters": [ { "name": "practice", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{2,40}$" } }, { "name": "level", "in": "query", "required": false, "schema": { "enum": [ "mid", "senior", "lead" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Band", "content": { "application/json": { "schema": { "type": "object", "properties": { "practice": { "type": "string" }, "band": { "enum": [ "lt5", "5-9", "10-24", "25+", null ] }, "text_en": { "type": "string" }, "text_ar": { "type": "string" }, "as_of": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core" } }, "/api/v1/bookings": { "post": { "operationId": "post_bookings", "summary": "Start a booking from a quote → { booking_id, state: scoped, next: account }", "tags": [ "Bookings" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "additionalProperties": false, "properties": { "quote_id": { "type": "string", "pattern": "^(?:[0-9a-fA-F-]{36}|Q-\\d{4}-\\d{6})$", "description": "Quote uuid, or the quote reference Q-YYYY-NNNNNN the public quote request returns" }, "product_id": { "type": [ "string", "null" ], "maxLength": 40 } } } } } }, "responses": { "200": { "description": "Existing booking for this quote" }, "201": { "description": "Booking created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-rate-limit-bucket": "write" } }, "/api/v1/bookings/{id}": { "get": { "operationId": "get_bookings_id", "summary": "Booking with its steps (account, kyb, nda, contract, esign, payment, trial), product, squad and totals", "tags": [ "Bookings" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Booking" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/bookings/{id}/account": { "post": { "operationId": "post_bookings_id_account", "summary": "Claim the booking for the signed-in client organisation (scoped → account; KYB-verified organisations move on to kyb_verified)", "tags": [ "Bookings" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Booking" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/bookings/{id}/nda": { "post": { "operationId": "post_bookings_id_nda", "summary": "Accept the mutual NDA (click) → nda_accepted", "tags": [ "Bookings" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accept" ], "properties": { "accept": { "const": true } } } } } }, "responses": { "200": { "description": "Booking" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Out of order" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/bookings/{id}/contract": { "post": { "operationId": "post_bookings_id_contract", "summary": "Generate the contract pack from templates → { docs: [{ id, kind, sha256, pdf_url, template_version }] }", "tags": [ "Bookings" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Contract pack" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Out of order" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/bookings/{id}/documents": { "get": { "operationId": "get_bookings_id_documents", "summary": "Contract pack of a booking", "tags": [ "Bookings" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Docs" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/bookings/{id}/payment-intent": { "post": { "operationId": "post_bookings_id_payment_intent", "summary": "Payment intent: card | mada (adapter; honest when unconfigured) · transfer (real reference + bank details) · po (finance review)", "tags": [ "Bookings", "Payments" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method" ], "additionalProperties": false, "properties": { "method": { "enum": [ "card", "mada", "transfer", "po" ] }, "po_number": { "type": "string", "maxLength": 60 } } } } } }, "responses": { "200": { "description": "Intent" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Out of order" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client", "roles": [ "Admin", "Approver", "Finance", "admin", "approver", "finance" ], "stepUp": true } } }, "/api/v1/dev/bookings/{id}/verify-kyb": { "post": { "operationId": "post_dev_bookings_id_verify_kyb", "summary": "DEV ONLY (404 in production): mark the booking organisation KYB-verified (registry adapters are unconfigured in development)", "tags": [ "Bookings", "Dev" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Booking" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/dev/payments/{id}/confirm": { "post": { "operationId": "post_dev_payments_id_confirm", "summary": "DEV ONLY (404 in production): confirm a payment as finance would", "tags": [ "Payments", "Dev" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Booking" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/calendar/earliest-start": { "get": { "operationId": "get_calendar_earliest_start", "summary": "Earliest start: 4 working days for every seat (bench, off-bench or on-site; client-clearance roles from the clearance date), counted on hub and client working days", "tags": [ "Calendar" ], "security": [], "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "default": "SA" } }, { "name": "bench", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Date and the rule used (R30 §3 shape: date, working_days, weekend, holidays_applied)", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/calendar/slots": { "get": { "operationId": "get_calendar_slots", "summary": "Scoping-call slots in the visitor’s zone (R30 §5 shape: flat { slots: [{ start_utc, end_utc, host }] } plus the day grouping)", "tags": [ "Calendar" ], "security": [], "parameters": [ { "name": "tz", "in": "query", "required": false, "schema": { "type": "string", "format": "time-zone" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 14, "default": 7 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Slots", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/calendar/working-days": { "get": { "operationId": "get_calendar_working_days", "summary": "Working days between two dates for a country (holidays included)", "tags": [ "Calendar" ], "security": [], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "format": "country", "default": "SA" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Count" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/calls": { "post": { "operationId": "post_calls", "summary": "Book a scoping call → { call_id, ics_url (served), join_url (null + reason without a conferencing adapter), confirmation_sent }", "tags": [ "Calendar" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slot_start_utc", "name", "email" ], "additionalProperties": false, "properties": { "slot_start_utc": { "type": "string", "format": "date-time" }, "tz": { "type": "string", "format": "time-zone" }, "country": { "type": [ "string", "null" ], "maxLength": 2 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email" }, "company": { "type": "string", "maxLength": 160 }, "topic": { "type": [ "string", "integer", "null" ], "maxLength": 500 }, "lang": { "enum": [ "en", "ar" ] }, "quote_id": { "type": "string", "maxLength": 64 }, "consent": { "type": "object" }, "whatsapp": { "type": "string", "maxLength": 40 }, "brief": { "type": "string", "maxLength": 4000 } } } } } }, "responses": { "201": { "description": "Call booked", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Slot taken" }, "422": { "description": "Slot in the past" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-rate-limit-bucket": "write" } }, "/api/v1/calls/{id}": { "get": { "operationId": "get_calls_id", "summary": "A booked call (needs the manage token from the confirmation)", "tags": [ "Calendar" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^APT-(\\d{4}|DEMO)-\\d{6}$" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 64 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Call" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/contracts/{id}/document": { "get": { "operationId": "get_contracts_id_document", "summary": "Contract document (honest printable HTML; SHA-256 re-verified against the stored hash)", "tags": [ "Contracts" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "text/html", "content": { "text/html": {} } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/contracts/{id}/sign": { "post": { "operationId": "post_contracts_id_sign", "summary": "Sign one contract document → { signature_id, signed_at, countersigned } (click needs a fresh step-up; e-sign providers answer honestly while unconfigured)", "tags": [ "Contracts" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method" ], "additionalProperties": false, "properties": { "method": { "enum": [ "click", "docusign", "nafath", "uaepass" ] }, "step_up_code": { "type": "string", "maxLength": 12 } } } } } }, "responses": { "200": { "description": "Signed" }, "202": { "description": "Sent to the e-sign provider queue (pending)" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "description": "Step-up required" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Out of order" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client", "roles": [ "Admin", "Approver", "Legal", "admin", "approver", "legal" ], "stepUp": true } } }, "/api/v1/intake/forms": { "get": { "operationId": "get_intake_forms", "summary": "Form catalogue: required fields and email policy per form", "tags": [ "Intake" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Forms", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/intake": { "post": { "operationId": "post_intake", "summary": "Submit any public form (stored, referenced, routed; honest channel states)", "tags": [ "Intake" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lang", "fields" ], "additionalProperties": false, "properties": { "form": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "form_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "page": { "type": "string", "maxLength": 300, "pattern": "^/" }, "lang": { "enum": [ "en", "ar" ] }, "fields": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "minLength": 2, "maxLength": 160 }, "role": { "type": "string", "maxLength": 160 }, "title": { "type": "string", "maxLength": 160 }, "country": { "type": "string", "format": "country" }, "phone": { "type": "string", "format": "e164" }, "message": { "type": "string", "minLength": 2, "maxLength": 4000 }, "topic": { "type": "string", "maxLength": 160 } }, "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ], "maxLength": 2000 } }, "utm": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 } }, "consent": { "type": "object", "additionalProperties": false, "properties": { "contact": { "const": true }, "given": { "const": true }, "purpose": { "type": "string", "maxLength": 60 }, "text": { "type": "string", "maxLength": 600 }, "marketing": { "type": "boolean" }, "policy_version": { "type": "string", "maxLength": 20 } } }, "website": { "type": "string", "maxLength": 200, "description": "Honeypot: leave empty." } } } } } }, "responses": { "201": { "description": "Received", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string" }, "status": { "type": "string" }, "channels": { "type": "object" }, "message": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake", "x-rate-limit-bucket": "write" } }, "/api/v1/intake/vendor-pack": { "post": { "operationId": "post_intake_vendor_pack", "summary": "Vendor pack request: 4 fields → immediate email with the pack links (MSA / SLA / DPA samples that exist today, 12-page profile slot pending, certificates status page)", "tags": [ "Intake" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lang", "fields" ], "additionalProperties": false, "properties": { "form": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "form_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "page": { "type": "string", "maxLength": 300, "pattern": "^/" }, "lang": { "enum": [ "en", "ar" ] }, "fields": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "minLength": 2, "maxLength": 160 }, "role": { "type": "string", "maxLength": 160 }, "title": { "type": "string", "maxLength": 160 }, "country": { "type": "string", "format": "country" }, "phone": { "type": "string", "format": "e164" }, "message": { "type": "string", "minLength": 2, "maxLength": 4000 }, "topic": { "type": "string", "maxLength": 160 }, "nda_accepted": { "type": "boolean" }, "government": { "type": "boolean" }, "deadline": { "type": "string", "maxLength": 40 }, "scope": { "type": "string", "maxLength": 4000 } }, "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ], "maxLength": 2000 } }, "utm": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 } }, "consent": { "type": "object", "additionalProperties": false, "properties": { "contact": { "const": true }, "given": { "const": true }, "purpose": { "type": "string", "maxLength": 60 }, "text": { "type": "string", "maxLength": 600 }, "marketing": { "type": "boolean" }, "policy_version": { "type": "string", "maxLength": 20 } } }, "upload": { "type": "object", "additionalProperties": false, "properties": { "filename": { "type": "string", "maxLength": 200 }, "bytes": { "type": "integer", "minimum": 1, "description": "File size in bytes; at most 52428800 (50 MB). Larger files are refused with code file_too_large and a bilingual message (Phase 13 N-24)." }, "content_type": { "type": "string", "maxLength": 100 } }, "description": "RFP document ≤ 50 MB: the answer carries a signed-upload slot (storage adapter) — never the file in this body" }, "website": { "type": "string", "maxLength": 200, "description": "Honeypot: leave empty." } } } } } }, "responses": { "201": { "description": "Received + pack email state", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake", "x-rate-limit-bucket": "write" } }, "/api/v1/intake/rfp": { "post": { "operationId": "post_intake_rfp", "summary": "RFP / RFI intake: ticket RFP-YYYY-NNNN, named owner slot (Account Director + Solutions Architect), reply within 5 business days; upload ≤ 50 MB through a signed-upload slot (storage adapter; honest pending when not connected)", "tags": [ "Intake" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lang", "fields" ], "additionalProperties": false, "properties": { "form": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "form_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "page": { "type": "string", "maxLength": 300, "pattern": "^/" }, "lang": { "enum": [ "en", "ar" ] }, "fields": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "minLength": 2, "maxLength": 160 }, "role": { "type": "string", "maxLength": 160 }, "title": { "type": "string", "maxLength": 160 }, "country": { "type": "string", "format": "country" }, "phone": { "type": "string", "format": "e164" }, "message": { "type": "string", "minLength": 2, "maxLength": 4000 }, "topic": { "type": "string", "maxLength": 160 }, "nda_accepted": { "type": "boolean" }, "government": { "type": "boolean" }, "deadline": { "type": "string", "maxLength": 40 }, "scope": { "type": "string", "maxLength": 4000 } }, "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ], "maxLength": 2000 } }, "utm": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 } }, "consent": { "type": "object", "additionalProperties": false, "properties": { "contact": { "const": true }, "given": { "const": true }, "purpose": { "type": "string", "maxLength": 60 }, "text": { "type": "string", "maxLength": 600 }, "marketing": { "type": "boolean" }, "policy_version": { "type": "string", "maxLength": 20 } } }, "upload": { "type": "object", "additionalProperties": false, "properties": { "filename": { "type": "string", "maxLength": 200 }, "bytes": { "type": "integer", "minimum": 1, "description": "File size in bytes; at most 52428800 (50 MB). Larger files are refused with code file_too_large and a bilingual message (Phase 13 N-24)." }, "content_type": { "type": "string", "maxLength": 100 } }, "description": "RFP document ≤ 50 MB: the answer carries a signed-upload slot (storage adapter) — never the file in this body" }, "website": { "type": "string", "maxLength": 200, "description": "Honeypot: leave empty." } } } } } }, "responses": { "201": { "description": "Ticket", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake", "x-rate-limit-bucket": "write" } }, "/api/v1/intake/security-questionnaire": { "post": { "operationId": "post_intake_security_questionnaire", "summary": "SIG Lite / CAIQ request: requires NDA acceptance first (fields.nda_accepted = true)", "tags": [ "Intake" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lang", "fields" ], "additionalProperties": false, "properties": { "form": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "form_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,59}$" }, "page": { "type": "string", "maxLength": 300, "pattern": "^/" }, "lang": { "enum": [ "en", "ar" ] }, "fields": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "minLength": 2, "maxLength": 160 }, "role": { "type": "string", "maxLength": 160 }, "title": { "type": "string", "maxLength": 160 }, "country": { "type": "string", "format": "country" }, "phone": { "type": "string", "format": "e164" }, "message": { "type": "string", "minLength": 2, "maxLength": 4000 }, "topic": { "type": "string", "maxLength": 160 }, "nda_accepted": { "type": "boolean" }, "government": { "type": "boolean" }, "deadline": { "type": "string", "maxLength": 40 }, "scope": { "type": "string", "maxLength": 4000 } }, "additionalProperties": { "type": [ "string", "number", "boolean", "object", "array", "null" ], "maxLength": 2000 } }, "utm": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 } }, "consent": { "type": "object", "additionalProperties": false, "properties": { "contact": { "const": true }, "given": { "const": true }, "purpose": { "type": "string", "maxLength": 60 }, "text": { "type": "string", "maxLength": 600 }, "marketing": { "type": "boolean" }, "policy_version": { "type": "string", "maxLength": 20 } } }, "upload": { "type": "object", "additionalProperties": false, "properties": { "filename": { "type": "string", "maxLength": 200 }, "bytes": { "type": "integer", "minimum": 1, "description": "File size in bytes; at most 52428800 (50 MB). Larger files are refused with code file_too_large and a bilingual message (Phase 13 N-24)." }, "content_type": { "type": "string", "maxLength": 100 } }, "description": "RFP document ≤ 50 MB: the answer carries a signed-upload slot (storage adapter) — never the file in this body" }, "website": { "type": "string", "maxLength": 200, "description": "Honeypot: leave empty." } } } } } }, "responses": { "201": { "description": "Received", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake", "x-rate-limit-bucket": "write" } }, "/api/v1/intake/{reference}/document": { "post": { "operationId": "post_intake_reference_document", "summary": "Attach one document (PDF or DOCX, ≤ 10 MB) to a public intake, e.g. the visitor's own NDA (trust-own-nda): raw body, X-File-Name; bound by the intake e-mail", "tags": [ "Intake" ], "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^RP-\\d{2}-\\d{6}$" } }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email", "maxLength": 254 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "201": { "description": "{ document_id, sha256, bytes, storage }" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown reference or e-mail" }, "409": { "$ref": "#/components/responses/Error" }, "415": { "description": "PDF or DOCX only" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake", "x-rate-limit-bucket": "uploads" } }, "/api/v1/kyb": { "post": { "operationId": "post_kyb", "summary": "Verify the organisation and its signatory (honest provider states; identity via Nafath, UAE PASS, Sumsub or manual)", "tags": [ "Organisations" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country", "signatory" ], "additionalProperties": false, "properties": { "org_id": { "type": "string", "minLength": 8, "maxLength": 64, "description": "Defaults to the signed-in person’s organisation; created from this KYB when they have none" }, "booking_id": { "type": "string", "maxLength": 64, "description": "The booking this KYB step belongs to (the site flow sends it)" }, "legal_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "registry_id": { "type": [ "string", "null" ], "maxLength": 40 }, "vat_id": { "type": [ "string", "null" ], "maxLength": 24 }, "signatory": { "type": "object", "required": [ "email", "source" ], "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ], "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "source": { "enum": [ "registry", "delegation" ] }, "delegation_doc": { "type": "string", "minLength": 3, "maxLength": 200, "description": "Document id or file name of the delegation letter" } } }, "identity": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "provider" ], "additionalProperties": false, "properties": { "provider": { "enum": [ "nafath", "uaepass", "sumsub", "manual" ] } } } ] } } } } } }, "responses": { "200": { "description": "KYB result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "verified", "pending_review", "pending_identity", "rejected" ] }, "checks": { "type": "array" }, "next": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-auth": { "kind": "client" }, "x-rate-limit-bucket": "write" } }, "/api/v1/kyb/identity/callback": { "get": { "operationId": "get_kyb_identity_callback", "summary": "Return from the identity provider (UAE PASS): records the result for the analyst and sends the buyer back to the flow", "tags": [ "Organisations" ], "security": [], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000 } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "302": { "description": "Back to the KYB step" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown state" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core" } }, "/api/mcp": { "post": { "operationId": "post__api_mcp", "summary": "MCP Streamable HTTP endpoint (JSON-RPC 2.0: initialize, ping, tools/list, tools/call)", "tags": [ "MCP" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Notification accepted" }, "400": { "description": "Bad request / missing session" }, "401": { "description": "Bad bearer token" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown session" }, "406": { "description": "Accept must include application/json and text/event-stream" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "mcp_anonymous" }, "delete": { "operationId": "delete__api_mcp", "summary": "End an MCP session (Mcp-Session-Id)", "tags": [ "MCP" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "204": { "description": "Ended" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown session" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "mcp_anonymous" } }, "/.well-known/mcp.json": { "get": { "operationId": "get__.well_known_mcp.json", "summary": "MCP server card: endpoint, transport, protocol versions, tools, auth", "tags": [ "MCP" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Server card", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents" } }, "/api/mcp/openapi.json": { "get": { "operationId": "get__api_mcp_openapi.json", "summary": "OpenAPI of the MCP REST mirror (generated from the route table) with the tool schemas", "tags": [ "MCP" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents" } }, "/api/v1/mcp/tools/{name}": { "post": { "operationId": "post_mcp_tools_name", "summary": "REST mirror: call any MCP tool with its JSON arguments", "tags": [ "MCP" ], "security": [], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "enum": [ "estimate_squad_cost", "check_availability", "get_security_docs", "search_talent", "request_proposal" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "structuredContent + summary" }, "400": { "description": "invalid_argument" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "description": "consent_required" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "mcp_anonymous" } }, "/api/v1/talent/search": { "get": { "operationId": "get_talent_search", "summary": "REST mirror of search_talent (anonymised)", "tags": [ "MCP", "Talent OS" ], "security": [], "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "practice", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "seniority", "in": "query", "required": false, "schema": { "enum": [ "mid", "senior", "lead" ] } }, { "name": "skills", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Anonymised results" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents" } }, "/api/v1/proposals": { "post": { "operationId": "post_proposals", "summary": "Create a draft proposal (REST mirror of request_proposal; public, OAuth proposals:write or client session)", "tags": [ "MCP", "Proposals" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Draft proposal" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "description": "consent_required" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "write" } }, "/api/v1/me": { "get": { "operationId": "get_me", "summary": "The signed-in person, organisation, role, session and CSRF token", "tags": [ "Auth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Me", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "Not signed in" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core" } }, "/api/v1/auth/session": { "get": { "operationId": "get_auth_session", "summary": "Alias of /v1/me (R28 I-4 name)", "tags": [ "Auth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Me", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core" } }, "/api/v1/metrics": { "get": { "operationId": "get_metrics", "summary": "Published delivery metrics: declared figures with lineage now; monthly delivery KPIs from their first publication (November 2026); null where nothing is published", "tags": [ "Status" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "{ period, first_publication, kpis[] }", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals" } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "get__.well_known_oauth_authorization_server", "summary": "OAuth 2.1 authorization server metadata (RFC 8414)", "tags": [ "OAuth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Metadata", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents" } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "get__.well_known_oauth_protected_resource", "summary": "Protected resource metadata for the MCP server (RFC 9728)", "tags": [ "OAuth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Metadata", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents" } }, "/api/oauth/register": { "post": { "operationId": "post__api_oauth_register", "summary": "Dynamic client registration (RFC 7591)", "tags": [ "OAuth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Client metadata + client_id (+ client_secret for confidential clients)" }, "400": { "description": "RFC 7591 error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "write" } }, "/api/oauth/authorize": { "get": { "operationId": "get__api_oauth_authorize", "summary": "Authorization request (code + PKCE S256) → redirect to the Client OS consent screen", "tags": [ "OAuth" ], "security": [], "parameters": [ { "name": "response_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "code_challenge", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resource", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "302": { "description": "Consent page, or redirect_uri with error" }, "400": { "description": "Unknown client or redirect_uri" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents" } }, "/api/v1/oauth/requests/{id}": { "get": { "operationId": "get_oauth_requests_id", "summary": "Pending authorization request for the consent screen", "tags": [ "OAuth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Request" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown or expired" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-auth": { "kind": "client" } } }, "/api/v1/oauth/requests/{id}/decision": { "post": { "operationId": "post_oauth_requests_id_decision", "summary": "Allow or deny a connected assistant (proposals:write needs an org admin)", "tags": [ "OAuth" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "allow" ], "additionalProperties": false, "properties": { "allow": { "type": "boolean" }, "org_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "{ redirect_to }" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "description": "proposals:write needs admin" }, "404": { "description": "Unknown or expired" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-auth": { "kind": "client" } } }, "/api/oauth/token": { "post": { "operationId": "post__api_oauth_token", "summary": "Token endpoint: authorization_code (+ code_verifier) and rotating refresh_token", "tags": [ "OAuth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "{ access_token, token_type, expires_in, refresh_token, scope }" }, "400": { "description": "RFC 6749 error" }, "401": { "description": "invalid_client" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "auth" } }, "/api/oauth/revoke": { "post": { "operationId": "post__api_oauth_revoke", "summary": "Token revocation (RFC 7009): always 200", "tags": [ "OAuth" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Revoked (or unknown)" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ai-agents", "x-rate-limit-bucket": "auth" } }, "/api/v1/orgs": { "post": { "operationId": "post_orgs", "summary": "Create the buyer organisation; the signed-in person becomes its Admin", "tags": [ "Organisations" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "legal_name", "country" ], "additionalProperties": false, "properties": { "legal_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "legal_name_ar": { "type": "string", "maxLength": 200 }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "registry_id": { "type": "string", "minLength": 3, "maxLength": 40 }, "vat_id": { "type": "string", "minLength": 5, "maxLength": 20 }, "buyer_type": { "enum": [ "enterprise", "startup", "studio", "founder", "government" ] }, "buyer_kind": { "enum": [ "business", "individual" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Already in an organisation, or the company is already registered" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-auth": { "kind": "client" }, "x-rate-limit-bucket": "write" } }, "/api/v1/orgs/{id}/members": { "get": { "operationId": "get_orgs_id_members", "summary": "Members of your organisation with their roles", "tags": [ "Organisations" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 64 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Members", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-auth": { "kind": "client" } }, "post": { "operationId": "post_orgs_id_members", "summary": "Invite a member with a role (Admin only, fresh step-up)", "tags": [ "Organisations" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 64 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "role" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "role": { "enum": [ "Admin", "Approver", "Finance", "Legal", "Viewer" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "lang": { "enum": [ "en", "ar" ] } } } } } }, "responses": { "201": { "description": "Invited", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Already a member elsewhere" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "pl-core", "x-auth": { "kind": "client", "roles": [ "Admin" ], "stepUp": true }, "x-rate-limit-bucket": "write" } }, "/api/v1/quotes/drafts": { "post": { "operationId": "post_quotes_drafts", "summary": "Save a Squad Builder draft → restore link valid 7 days (no prices). More than 25 seats → Account Director handoff flag", "tags": [ "Quotes" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input", "lang" ], "additionalProperties": false, "properties": { "input": { "type": "object", "additionalProperties": true, "properties": { "squad": { "type": "array", "maxItems": 40, "items": { "type": "object", "required": [ "level" ], "properties": { "practice": { "type": "string", "maxLength": 40 }, "role": { "type": [ "string", "null" ], "maxLength": 120 }, "level": { "type": "string", "maxLength": 20 }, "count": { "type": "integer", "minimum": 1, "maximum": 40 }, "hours": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "onsite": { "type": "boolean" }, "onsite_city": { "type": "string", "maxLength": 40 } } } }, "term_months": { "enum": [ 1, 3, 6, 12 ] }, "start": { "type": [ "string", "null" ] }, "rush": { "type": "boolean" }, "verified_startup": { "type": "boolean" }, "pack_id": { "type": "string", "maxLength": 40 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "buyer": { "type": "object", "properties": { "country": { "type": [ "string", "null" ], "maxLength": 2 }, "type": { "type": [ "string", "null" ], "maxLength": 20 } } }, "today": { "type": "string", "format": "date" }, "visits": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0, "maximum": 60 }, "city": { "type": "string", "maxLength": 40 } } } } }, "market": { "enum": [ "sa", "ae", "eg", "eu", "us", "row" ] }, "lang": { "enum": [ "en", "ar" ] }, "source": { "type": "string", "maxLength": 40, "pattern": "^[a-z0-9-]+$" } } } } } }, "responses": { "201": { "description": "Draft saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft_id": { "type": "string" }, "token": { "type": "string" }, "expires_at": { "type": "string" }, "expires_local": { "type": "string" }, "valid_days": { "type": "integer" }, "restore_url": { "type": "string" }, "seats": { "type": "integer" }, "account_director_handoff": { "type": [ "object", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-rate-limit-bucket": "write" } }, "/api/v1/quotes/drafts/{token}": { "get": { "operationId": "get_quotes_drafts_token", "summary": "Restore a Squad Builder draft by its link token (404 unknown, 410 after 7 days; no prices)", "tags": [ "Quotes" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Draft" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown token" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "description": "Expired" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-rate-limit-bucket": "public" } }, "/api/v1/contracts/governing-law": { "get": { "operationId": "get_contracts_governing_law", "summary": "Governing-law options for the contract generator by market (Germany, England & Wales, Delaware, New York + the entity laws); clause text pending founder / counsel", "tags": [ "Contracts" ], "security": [], "parameters": [ { "name": "market", "in": "query", "required": false, "schema": { "enum": [ "sa", "ae", "eg", "eu", "us", "row" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Options", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-rate-limit-bucket": "public" } }, "/api/v1/trust/downloads": { "post": { "operationId": "post_trust_downloads", "summary": "Log a Trust Center download (who downloaded what). Gated documents (work e-mail / NDA) need the intake reference of the request that opened them", "tags": [ "Trust" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "doc_id", "gate", "lang" ], "additionalProperties": false, "properties": { "doc_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,99}$" }, "doc_version": { "type": "string", "maxLength": 40 }, "gate": { "enum": [ "public", "work_email", "nda" ] }, "reference": { "type": "string", "pattern": "^(RP-\\d{2}-\\d{6}|RFP-\\d{4}-\\d{4})$" }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "maxLength": 160 }, "page": { "type": "string", "maxLength": 300, "pattern": "^/" }, "lang": { "enum": [ "en", "ar" ] } } } } } }, "responses": { "201": { "description": "Logged", "content": { "application/json": { "schema": { "type": "object", "properties": { "logged": { "type": "boolean" }, "id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake", "x-rate-limit-bucket": "write" } }, "/api/v1/app/contracts/{id}/addenda": { "post": { "operationId": "post_app_contracts_id_addenda", "summary": "Issue an addendum bound to one original contract (parent kept unchanged; SHA-256; e-sign via POST /v1/contracts/{id}/sign)", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "change" ], "additionalProperties": false, "properties": { "change": { "type": "string", "minLength": 3, "maxLength": 1000 }, "effective_on": { "type": "string", "format": "date" }, "governing_law": { "type": "string", "maxLength": 10 } } } } } }, "responses": { "201": { "description": "Addendum issued" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown contract" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client", "roles": [ "Admin", "Approver", "admin", "approver" ] } } }, "/api/v1/app/references": { "get": { "operationId": "get_app_references", "summary": "Unified reference chain of the signed-in client engagement: quote → booking → order form / SOW → invoices → replacements (one root number)", "tags": [ "Client OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Chain" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-auth": { "kind": "client" } } }, "/api/v1/payments/webhook/{provider}": { "post": { "operationId": "post_payments_webhook_provider", "summary": "Provider webhook (R30 alias of /api/v1/webhooks/{domain}/{provider}): verified by the configured adapter; 503 while the provider is unconfigured, 501 for a provider without an adapter", "tags": [ "Payments", "Webhooks" ], "security": [], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "stripe", "moyasar", "hyperpay", "docusign", "nafath", "uaepass", "zatca" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Accepted (new or duplicate deliveries)" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "Signature invalid" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "description": "Not implemented" }, "503": { "description": "Provider not connected" } }, "x-owner": "money-spine", "x-rate-limit-bucket": "public" } }, "/api/v1/quotes": { "post": { "operationId": "post_quotes", "summary": "Request a quote from an R30 squad input (or a fixed-price product). Anonymous: the itemised quote is e-mailed to the work address within about 2 minutes → { reference, delivery: \"email\", eta_minutes: 2, sent_to, hold_options } — never an amount. Signed-in (Client OS / staff): the priced quote (totals, share token, document URL)", "tags": [ "Quotes" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "squad": { "type": "array", "maxItems": 40, "items": { "type": "object", "required": [ "level" ], "properties": { "practice": { "type": "string", "maxLength": 40 }, "role": { "type": [ "string", "null" ], "maxLength": 120 }, "level": { "type": "string", "maxLength": 20 }, "count": { "type": "integer", "minimum": 1, "maximum": 40 }, "hours": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "onsite": { "type": "boolean" }, "onsite_city": { "type": "string", "maxLength": 40 } } } }, "term_months": { "enum": [ 1, 3, 6, 12 ] }, "start": { "type": [ "string", "null" ] }, "rush": { "type": "boolean" }, "verified_startup": { "type": "boolean" }, "pack_id": { "type": "string", "maxLength": 40 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "buyer": { "type": "object", "properties": { "country": { "type": [ "string", "null" ], "maxLength": 2 }, "type": { "type": [ "string", "null" ], "maxLength": 20 } } }, "today": { "type": "string", "format": "date" }, "visits": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0, "maximum": 60 }, "city": { "type": "string", "maxLength": 40 } } } } }, "product_id": { "type": [ "string", "null" ], "maxLength": 40 }, "contact": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email" }, "company": { "type": "string", "maxLength": 160 }, "country": { "type": "string", "format": "country" }, "phone": { "type": "string", "format": "e164" }, "government": { "type": "boolean" } } }, "source": { "type": "string", "maxLength": 40, "pattern": "^[a-z0-9-]+$", "description": "squad-builder | pricing | mcp | …" } } } } } }, "responses": { "201": { "description": "Quote requested (anonymous: receipt without prices; signed-in: the priced quote)", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Q-YYYY-NNNNNN" }, "delivery": { "type": "string", "enum": [ "email" ] }, "eta_minutes": { "type": "integer" }, "sent_to": { "type": [ "string", "null" ] }, "email_state": { "type": "string" }, "valid_until": { "type": "string" }, "hold_options": { "type": "object", "properties": { "free_hold_hours": { "type": "integer" }, "deposit_hold_days": { "type": "integer" }, "reserve_url": { "type": "string" }, "time_zone": { "type": "string" }, "if_reserved_now": { "type": "object" }, "start_date": { "type": "object", "description": "Future start date (input.start): 7-day hold with PO / LOI or 30-day hold with a deposit — rules only, no amounts" } } }, "route": { "type": "object" }, "channels": { "type": "object" }, "next_steps": { "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine", "x-rate-limit-bucket": "write" } }, "/api/v1/quotes/{id}": { "get": { "operationId": "get_quotes_id", "summary": "Quote by id; `/quotes/{id}.pdf` serves the document: PDF when a PDF engine is connected, otherwise an honest printable HTML (Content-Type text/html)", "tags": [ "Quotes" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}(\\.pdf)?$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Quote" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/q/{token}": { "get": { "operationId": "get_q_token", "summary": "Shared quote by share token (read-only, no contact data)", "tags": [ "Quotes" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Quote" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown token" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "description": "Expired" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "money-spine" } }, "/api/v1/status": { "get": { "operationId": "get_status", "summary": "Public status from real probes of our own components (no data where unmonitored; never a static green)", "tags": [ "Status" ], "security": [], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "{ status, components[{ id, name, state, uptime_90d_pct, last_probe_at, … }], incidents: [] }", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals" } }, "/api/v1/status/incidents": { "get": { "operationId": "get_status_incidents", "summary": "Published incidents (none recorded yet: the list is empty, not hidden)", "tags": [ "Status" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Page of incidents", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals" } }, "/api/v1/health": { "get": { "operationId": "get_health", "summary": "Service health (public, minimal: status + price-book version)", "tags": [ "System" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "description": "Unhealthy" } }, "x-owner": "platform-architect" } }, "/api/v1/health/live": { "get": { "operationId": "get_health_live", "summary": "Liveness probe", "tags": [ "System" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Process is up" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "platform-architect" } }, "/api/v1/health/ready": { "get": { "operationId": "get_health_ready", "summary": "Readiness probe (database, migrations, the one price book; in live mode also the go-live inputs)", "tags": [ "System" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Ready" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "description": "Not ready" } }, "x-owner": "platform-architect" } }, "/api/openapi.json": { "get": { "operationId": "get__api_openapi.json", "summary": "OpenAPI 3.1 document generated from the route table", "tags": [ "System" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "platform-architect" } }, "/api/v1/meta/markets": { "get": { "operationId": "get_meta_markets", "summary": "Markets for the header selector: currency, contracting entity, VAT treatment, meeting city, weekend, earliest start (D7)", "tags": [ "Meta" ], "security": [], "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "enum": [ "en", "ar" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Markets", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "platform-architect" } }, "/api/v1/security/csp-report": { "post": { "operationId": "post_security_csp_report", "summary": "CSP violation reports (report-to / report-uri)", "tags": [ "System" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "204": { "description": "Accepted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "platform-architect", "x-rate-limit-bucket": "reports" } }, "/.well-known/security.txt": { "get": { "operationId": "get__.well_known_security.txt", "summary": "security.txt (RFC 9116)", "tags": [ "System" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "security.txt", "content": { "text/plain": {} } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "platform-architect" } }, "/.well-known/did.json": { "get": { "operationId": "get__.well_known_did.json", "summary": "DID document (did:web) with the key that signs credentials and attestations", "tags": [ "Trust" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "DID document", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "platform-architect" } }, "/api/v1/talent/applications": { "post": { "operationId": "post_talent_applications", "summary": "Apply as a specialist (≤ 5 steps: one payload or step-wise with a continue token)", "description": "Shapes: { profile, experience, availability?, documents?, consent } · { step: 1..5, data, reference?, continue_token? } · flat { email, name, practice, role_id?, country, lang, level?, consent }. Screening runs through the screening adapter; while it is unconfigured the item goes to the talent-ops inbox (honest pending state).", "tags": [ "Talent OS" ], "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "See description; per-step schemas in x-steps.", "x-steps": { "profile": { "type": "object", "required": [ "name", "email" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 200 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "city": { "type": "string", "minLength": 1, "maxLength": 80 }, "phone": { "type": "string", "minLength": 1, "maxLength": 30 }, "lang": { "enum": [ "en", "ar" ] }, "linkedin_url": { "type": "string", "maxLength": 300, "pattern": "^https://" } } }, "experience": { "type": "object", "required": [ "practice", "level" ], "additionalProperties": false, "properties": { "practice": { "enum": [ "ai-data", "cybersecurity", "game-development", "mobile-web", "cloud-complex-systems", "design", "marketing", "business-development", "sales" ] }, "role_id": { "type": "string", "pattern": "^[a-z0-9-]{3,80}$" }, "level": { "enum": [ "mid", "senior", "lead" ] }, "years_experience": { "type": "integer", "minimum": 4, "maximum": 50 }, "skills": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "languages": { "type": "array", "maxItems": 8, "items": { "type": "string", "minLength": 1, "maxLength": 20 } }, "headline": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "availability": { "type": "object", "required": [ "state" ], "additionalProperties": false, "properties": { "state": { "enum": [ "now", "from_date", "unavailable" ] }, "from": { "type": "string", "format": "date" }, "hours_per_week": { "type": "integer", "minimum": 10, "maximum": 60 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 60 }, "onsite_ok": { "type": "array", "items": { "enum": [ "riyadh", "dubai", "doha", "cairo" ] } }, "residency_patterns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20 } } } }, "documents": { "type": "object", "additionalProperties": false, "properties": { "cv_document_id": { "type": "string", "maxLength": 80 }, "portfolio_urls": { "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 300, "pattern": "^https://" } } } }, "consent": { "type": "object", "required": [ "processing", "policy_version" ], "additionalProperties": false, "properties": { "processing": { "const": true }, "policy_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "background_check": { "type": "boolean" }, "marketing": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Step saved" }, "201": { "description": "Draft created (step-wise, step 1) with continue_token" }, "202": { "description": "Submitted: screening pending", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation (per step)" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Already submitted" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-rate-limit-bucket": "auth" } }, "/api/v1/talent/me": { "get": { "operationId": "get_talent_me", "summary": "My Talent OS profile: application steps, stage, availability, assessments, credentials", "tags": [ "Talent OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "Sign in" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-auth": { "kind": "talent" } } }, "/api/v1/talent/documents": { "post": { "operationId": "post_talent_documents", "summary": "Upload my CV (PDF or DOCX, ≤ 5 MB) for application step 4 → cv_document_id (storage adapter, honest state)", "tags": [ "Talent OS" ], "security": [], "parameters": [ { "name": "reference", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "continue_token", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "201": { "description": "{ document_id, sha256, bytes, storage }" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown application or token" }, "409": { "$ref": "#/components/responses/Error" }, "415": { "description": "PDF or DOCX only" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-rate-limit-bucket": "uploads" } }, "/api/v1/talent/applications/{reference}/cv": { "post": { "operationId": "post_talent_applications_reference_cv", "summary": "Attach the CV (PDF or DOCX, ≤ 10 MB) to a just-submitted application, bound by its reference and the applicant e-mail", "tags": [ "Talent OS" ], "security": [], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^TAL-\\d{4}-\\d{6}$" } }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email", "maxLength": 254 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "201": { "description": "{ document_id, sha256, bytes, storage }" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown reference or e-mail" }, "409": { "description": "A CV is already attached" }, "415": { "description": "PDF or DOCX only" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-rate-limit-bucket": "uploads" } }, "/api/v1/talent/application": { "get": { "operationId": "get_talent_application", "summary": "My application: step state (≤ 5 steps), status and screening state", "tags": [ "Talent OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Application", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "No application" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-auth": { "kind": "talent" } } }, "/api/v1/talent/application/review-request": { "post": { "operationId": "post_talent_application_review_request", "summary": "Ask for a human review of any automated step (GDPR Art. 22, PDPL, EU AI Act)", "tags": [ "Talent OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "step" ], "additionalProperties": false, "properties": { "step": { "enum": [ "screening", "assessment", "ai_interview", "matching", "other" ] }, "note": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "202": { "description": "Review requested (talent_ops inbox, SLA 2 working days)" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-auth": { "kind": "talent" } } }, "/api/v1/talent/assessments/start": { "post": { "operationId": "post_talent_assessments_start", "summary": "Start my technical assessment (assessments adapter; manual invitation while unconfigured)", "tags": [ "Talent OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "preferred_language": { "type": "string", "maxLength": 30 } } } } } }, "responses": { "202": { "description": "Assessment pending or invited", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "No talent profile" }, "409": { "description": "Application not submitted" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-auth": { "kind": "talent" } } }, "/api/v1/talent/credentials": { "get": { "operationId": "get_talent_credentials", "summary": "My issued credentials (\"Remote Pro Ai Vetted\", Open Badges 3.0 / VC 2.0)", "tags": [ "Talent OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Credentials", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-auth": { "kind": "talent" } } }, "/api/v1/talent/availability": { "put": { "operationId": "put_talent_availability", "summary": "Set my availability (feeds the public availability bands; counts below 5 are never shown)", "tags": [ "Talent OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Retries with the same key replay the original response." }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "additionalProperties": false, "properties": { "state": { "enum": [ "now", "from_date", "unavailable" ] }, "from": { "type": "string", "format": "date" }, "hours_per_week": { "type": "integer", "minimum": 10, "maximum": 60 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 60 }, "onsite_ok": { "type": "array", "items": { "enum": [ "riyadh", "dubai", "doha", "cairo" ] } }, "residency_patterns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20 } } } } } } }, "responses": { "200": { "description": "Saved, with the public band for my practice", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-auth": { "kind": "talent" } } }, "/api/v1/talent/payouts": { "get": { "operationId": "get_talent_payouts", "summary": "My payouts (payouts adapter mode reported honestly)", "tags": [ "Talent OS" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Payouts", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals", "x-auth": { "kind": "talent" } } }, "/api/v1/tour": { "get": { "operationId": "get_tour", "summary": "Product-tour snapshot of the demo account (Client OS view, read-only, watermarked)", "tags": [ "Tour" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Demo snapshot", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Demo not seeded" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "portals" } }, "/api/v1/verify/{credential_id}": { "get": { "operationId": "get_verify_credential_id", "summary": "Verify a \"Remote Pro Ai Vetted\" credential (urn:uuid, uuid or RPV-… id): signature, issuer key, expiry, revocation", "tags": [ "Trust" ], "security": [], "parameters": [ { "name": "credential_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 120 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "{ valid, status, issued_to_initials, role, level, issued_at, issuer_key_id, … }", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown credential" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/verify/credential": { "post": { "operationId": "post_verify_credential", "summary": "Verify a pasted VC document (signature, issuer, expiry, status list)", "tags": [ "Trust" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credential" ], "additionalProperties": false, "properties": { "credential": { "type": "object" } } } } } }, "responses": { "200": { "description": "{ verified, checks, status }", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake", "x-rate-limit-bucket": "write" } }, "/api/v1/credentials/status/{list}": { "get": { "operationId": "get_credentials_status_list", "summary": "Signed BitstringStatusListCredential (revocation)", "tags": [ "Trust" ], "security": [], "parameters": [ { "name": "list", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 999 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Status list credential", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "No such list" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/v1/credentials/{id}": { "get": { "operationId": "get_credentials_id", "summary": "The credential document (VC 2.0 / Open Badges 3.0, eddsa-jcs-2022 proof)", "tags": [ "Trust" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 120 } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Verifiable credential", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "description": "Unknown credential" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "identity-intake" } }, "/api/talent/v1/access": { "get": { "operationId": "get__api_talent_v1_access", "summary": "Disclosure layer of the current session (1 public · 2 verified work e-mail · 3 NDA). STUB: reads ctx.actor.talent_layer, else 1.", "tags": [ "talent" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta", "x-rate-limit-bucket": "public" } }, "/api/talent/v1/feed": { "get": { "operationId": "get__api_talent_v1_feed", "summary": "Layer-1 anonymised profiles (published + consented). Static build reads data/talent-feed.json instead.", "tags": [ "talent" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta", "x-rate-limit-bucket": "public" } }, "/api/talent/v1/profile/{id}": { "get": { "operationId": "get__api_talent_v1_profile_id", "summary": "One profile at the requested layer (≤ session layer, ≤ published layers)", "tags": [ "talent" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Profile identifier RP-XX-0000" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta", "x-rate-limit-bucket": "public" } }, "/api/talent/v1/anonymise/check": { "post": { "operationId": "post__api_talent_v1_anonymise_check", "summary": "Second-pass scan of a structured profile (no storage)", "tags": [ "talent" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta", "x-rate-limit-bucket": "public" } }, "/api/talent/v1/ops/profiles": { "get": { "operationId": "get__api_talent_v1_ops_profiles", "summary": "Talent Ops list (status · confidence · last sync · published layers)", "tags": [ "talent" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } }, "/api/talent/v1/ops/profiles/{id}/audit": { "get": { "operationId": "get__api_talent_v1_ops_profiles_id_audit", "summary": "Audit trail of one profile (who uploaded / edited / approved / published / un-published)", "tags": [ "talent" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Profile identifier RP-XX-0000" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } }, "/api/talent/v1/ops/profiles/{id}/approve": { "post": { "operationId": "post__api_talent_v1_ops_profiles_id_approve", "summary": "Practice Lead approval; requires contactCheckConfirmed: true; blocked by the second pass", "tags": [ "talent" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Profile identifier RP-XX-0000" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } }, "/api/talent/v1/ops/profiles/{id}/publish": { "post": { "operationId": "post__api_talent_v1_ops_profiles_id_publish", "summary": "Marketing publish (layers ≤ consent)", "tags": [ "talent" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Profile identifier RP-XX-0000" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } }, "/api/talent/v1/ops/profiles/{id}/hide": { "post": { "operationId": "post__api_talent_v1_ops_profiles_id_hide", "summary": "Marketing un-publish", "tags": [ "talent" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Profile identifier RP-XX-0000" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } }, "/api/talent/v1/me/consent": { "post": { "operationId": "post__api_talent_v1_me_consent", "summary": "Engineer consent (layer 1–3) — Talent OS", "tags": [ "talent" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } }, "/api/talent/v1/me/consent/withdraw": { "post": { "operationId": "post__api_talent_v1_me_consent_withdraw", "summary": "Withdraw consent: layer 1 hidden ≤ 24 h, layers 2–3 deleted ≤ 30 days", "tags": [ "talent" ], "security": [ { "cookieSession": [] }, { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } }, "/api/talent/v1/openapi.json": { "get": { "operationId": "get__api_talent_v1_openapi.json", "summary": "OpenAPI document of the talent module", "tags": [ "talent" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OpenAPI 3.1" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "x-owner": "ta" } } }, "components": { "securitySchemes": { "cookieSession": { "type": "apiKey", "in": "cookie", "name": "__Host-rp_session", "description": "Session cookie set after sign-in (rp_session on plain-HTTP development servers)." }, "bearer": { "type": "http", "scheme": "bearer", "description": "Session token or OAuth 2.1 access token (MCP account tools)." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 authorisation code with PKCE (S256). Access tokens last 60 minutes; refresh tokens rotate on every use. Tokens never approve, pay or sign.", "flows": { "authorizationCode": { "authorizationUrl": "https://remote-pro.ai/api/oauth/authorize", "tokenUrl": "https://remote-pro.ai/api/oauth/token", "refreshUrl": "https://remote-pro.ai/api/oauth/token", "scopes": { "proposals:read": "Read your organisation's proposals and quotes", "proposals:write": "Create draft proposals in Client OS", "squads:read": "Read squads, roster and engineer status", "timesheets:read": "Read submitted and approved timesheets", "invoices:read": "Read invoices, credits and e-invoice files", "documents:read": "Read contract and certificate metadata" } } } } }, "parameters": { "AcceptLanguage": { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "example": "ar" }, "description": "en or ar; ?lang= overrides." } }, "responses": { "Error": { "description": "Error envelope", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message_en", "message_ar", "status", "message", "i18n", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine code, e.g. validation_failed, state, policy_denied." }, "message_en": { "type": "string" }, "message_ar": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string", "description": "Message in the negotiated language." }, "i18n": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "details": { "description": "Field errors (422) or a state object (409: { required })", "oneOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "message_en": { "type": "string" }, "message_ar": { "type": "string" }, "i18n": { "type": "object" } } } } ] }, "request_id": { "type": "string" } } } } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message_en", "message_ar", "status", "message", "i18n", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine code, e.g. validation_failed, state, policy_denied." }, "message_en": { "type": "string" }, "message_ar": { "type": "string" }, "status": { "type": "integer" }, "message": { "type": "string", "description": "Message in the negotiated language." }, "i18n": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "details": { "description": "Field errors (422) or a state object (409: { required })", "oneOf": [ { "type": "null" }, { "type": "object" }, { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "message_en": { "type": "string" }, "message_ar": { "type": "string" }, "i18n": { "type": "object" } } } } ] }, "request_id": { "type": "string" } } } } } } } }