{"openapi":"3.0.3","info":{"title":"Nexus Execution API","version":"v1"},"servers":[{"url":"/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/enterprise/connectors":{"get":{"operationId":"listEnterpriseConnectors","description":"List the organization's enterprise integration connectors (ERP, CRM, accounting, inventory, asset management, maintenance, logistics). Requires integration.manage and an administrator role."},"post":{"operationId":"registerEnterpriseConnector","description":"Register a reusable outbound connector with HTTPS-only base URL, SSRF-protected host resolution, bearer or header API-key auth, and a per-connector rate limit. Credentials are server-managed and never returned after registration. Requires integration.manage and an administrator role."}},"/enterprise/connectors/{connectorId}":{"get":{"operationId":"getEnterpriseConnector","description":"Fetch one connector (secret redacted). Organization-scoped; cross-tenant reads return 404."}},"/enterprise/connectors/{connectorId}/rotate":{"post":{"operationId":"rotateConnectorCredential","description":"Replace the connector credential server-side. Audited."}},"/enterprise/connectors/{connectorId}/revoke":{"post":{"operationId":"revokeEnterpriseConnector","description":"Revoke a connector; revoked connectors refuse invocation. Audited."}},"/enterprise/connectors/{connectorId}/test":{"post":{"operationId":"testEnterpriseConnector","description":"Governed connectivity test (GET on the connector base URL) with bounded retries and a logged delivery."}},"/enterprise/connectors/{connectorId}/invoke":{"post":{"operationId":"invokeEnterpriseConnector","description":"Governed outbound invocation: validated method/path, JSON payload, optional idempotency key (24h replay window), per-connector rate limit, exponential-backoff retries on 5xx/transport errors, full delivery log. Returns the delivery outcome; connector targets never gain execution authority."}},"/enterprise/connectors/{connectorId}/deliveries":{"get":{"operationId":"listConnectorDeliveries","description":"Delivery log for one connector: method, path, status, latency, attempts, outcome, error."}},"/enterprise/connectors/access-review":{"get":{"operationId":"enterpriseAccessReview","description":"Integration access review: connectors with usage recency and a stale flag for credentials unused for 30 days."}},"/webhooks/deliveries":{"get":{"operationId":"listWebhookDeliveries","description":"Organization-scoped webhook delivery history with per-delivery status, attempts, terminal flag and next attempt time. Requires webhook.manage."}},"/business/audit-export":{"get":{"operationId":"exportOrganizationAudit","description":"Organization administrators only: export the tenant's own audit stream (task lifecycle, loss/enterprise, billing) with from/to ISO bounds and a limit up to 5000. Other tenants' records are structurally excluded."}},"/business/governance-policies":{"get":{"operationId":"getGovernancePolicies","description":"Organization execution policies (budget ceilings, approval thresholds, staleness auto-cancel)."},"post":{"operationId":"updateGovernancePolicies","description":"Organization administrators only: merge-validated policy set (max_task_budget_minor, require_approval_above_minor, require_explicit_requester_approval, auto_cancel_stale_hours). Audited."}},"/business-network/connections":{"get":{"operationId":"listNetworkConnections","description":"Organization-to-organization network relationships with status filter."},"post":{"operationId":"requestNetworkConnection","description":"Request (or mutually accept) a network connection with another registered organization. Only public profile fields are ever visible across tenants."}},"/business-network/connections/{connectionId}":{"post":{"operationId":"respondToNetworkConnection","description":"Accept, decline or withdraw a pending network connection."}},"/business-network/trust":{"get":{"operationId":"networkContextualTrust","description":"Contextual trust signals for a peer organization: connection state, relationship age, verification status, published capabilities. Explicitly not a financial or identity guarantee."}},"/discovery/providers":{"get":{"operationId":"searchProviders","security":[],"description":"Public read-only search over Nexus-registered providers. Results include factual match reasons, total_count, page offsets, and explicit unverified/self-reported labels.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":240}},{"name":"service","in":"query","schema":{"type":"string","maxLength":80}},{"name":"location","in":"query","schema":{"type":"string","maxLength":160}},{"name":"availability","in":"query","schema":{"type":"string","enum":["available","busy","not_provided"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["relevance","recent","name","rating","availability"],"default":"recent"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Page of registered provider listings with pagination metadata and match explanations."}}},"post":{"operationId":"registerProvider","description":"Create or update the authenticated organization's provider listing; submitted credentials are claims, not verified facts."}},"/discovery/voice-search":{"post":{"operationId":"voiceSearchProviders","security":[],"description":"Public voice-intent search over Nexus-registered providers. Parses a spoken request transcript into a structured intent (service, location, urgency, availability, sort, budget) and returns the matching directory page. Transcripts are parsed and not persisted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":400,"description":"Raw spoken request transcript, e.g. 'find me an electrician around GRA, Port Harcourt who can come today'."},"limit":{"type":"integer","minimum":1,"maximum":30,"default":20},"offset":{"type":"integer","minimum":0,"maximum":100000,"default":0}}}}}},"responses":{"200":{"description":"Directory search results with the parsed intent attached under `intent`, including confidence and any fields that were not understood."},"400":{"description":"Empty or non-string transcript."}}}},"/discovery/requests":{"get":{"operationId":"listServiceRequests","description":"List service requests for the authenticated organization, including provider responses."},"post":{"operationId":"submitServiceRequest","description":"Submit a confirmed service request; creates provider inbox offers but does not itself book a provider."}},"/discovery/provider-requests":{"get":{"operationId":"listProviderRequests","description":"List requests routed to the authenticated organization's active provider listing."}},"/discovery/requests/{request_id}/disputes":{"post":{"operationId":"openBookingDispute","description":"Open a dispute for an accepted booking; only the original customer or booked provider may open a case."}},"/discovery/disputes":{"get":{"operationId":"listBookingDisputes","description":"List dispute cases visible to the authenticated booking party."}},"/discovery/disputes/{dispute_id}/messages":{"post":{"operationId":"addBookingDisputeMessage","description":"Add a message to an active dispute as one of the original booking parties."}},"/platform-admin/booking-disputes":{"get":{"operationId":"listPlatformBookingDisputes","description":"Super Admin-only global booking dispute queue."}},"/platform-admin/executions":{"get":{"operationId":"listPlatformExecutions","description":"Super Admin-only global task metadata monitor; never returns task payloads or evidence content."}},"/platform-admin/booking-disputes/{dispute_id}/resolve":{"post":{"operationId":"resolveBookingDispute","description":"Super Admin-only audited resolve/reject decision. Does not issue refunds or move money."}},"/platform-admin/trust-claims":{"get":{"operationId":"listPlatformTrustClaims","description":"Super Admin-only global Trust Passport claim oversight queue."}},"/platform-admin/trust-claims/{claim_id}/revoke":{"post":{"operationId":"revokePlatformTrustClaim","description":"Super Admin-only global Trust Passport claim revocation with mandatory confirmation and audit reason."}},"/discovery/provider-requests/{request_id}/response":{"post":{"operationId":"respondToProviderRequest","description":"Provider can express interest, decline, or send a quote to a request routed to its own listing."}},"/tasks":{"post":{"operationId":"createTask","description":"Create an execution task."}},"/tasks/{task_id}":{"get":{"operationId":"getTask"}},"/tasks/{task_id}/start":{"post":{"operationId":"startTask","description":"Start an assigned task as its authorized executor. Idempotency-Key is recommended for retries."}},"/tasks/{task_id}/verify":{"post":{"operationId":"verifyTaskEvidence","description":"Run deterministic technical checks on the active evidence submission. The result never establishes physical truth; eligible work remains pending a human decision."}},"/tasks/{task_id}/cancel":{"post":{"operationId":"cancelTask","description":"Cancel an eligible task and release held funds."}},"/tasks/{task_id}/events":{"get":{"operationId":"listTaskEvents"}},"/tasks/{task_id}/schedule":{"get":{"operationId":"getTaskSchedule"},"post":{"operationId":"setTaskSchedule"}},"/tasks/{task_id}/geo-constraint":{"get":{"operationId":"getTaskGeoConstraint"},"post":{"operationId":"setTaskGeoConstraint"}},"/tasks/{task_id}/assignment-failures":{"get":{"operationId":"listAssignmentFailures"},"post":{"operationId":"failTaskAssignment"}},"/business/equipment":{"get":{"operationId":"listEquipmentAssets","description":"Organization-scoped equipment asset registry with computed health (condition, 30-day failures and downtime, maintenance spend, schedule state, open issues)."},"post":{"operationId":"registerEquipmentAsset","description":"Register an equipment asset with location, criticality and optional maintenance interval. Requires task.create. Registry context only; nothing is executed."}},"/business/equipment/{asset_id}":{"get":{"operationId":"getEquipmentAsset","description":"Asset detail: registry fields, condition history, computed health and maintenance schedule state."}},"/business/equipment/{asset_id}/condition":{"post":{"operationId":"recordEquipmentCondition","description":"Record a condition observation (healthy, degraded, failed, under_repair) with optional notes. Audited; no autonomous action."}},"/business/equipment-overview":{"get":{"operationId":"getEquipmentPilotOverview","description":"Pilot dashboard aggregate: asset counts by condition, overdue schedules, open issues, 30-day downtime and spend, plus loss-intelligence financial classes (estimated exposure is never a confirmed loss; savings are evidence-backed)."}},"/business/equipment-issues":{"get":{"operationId":"listEquipmentIssues","description":"Open equipment-domain loss detections with supporting evidence, methodology, confidence, estimated exposure, recommended action, asset context and whether an investigation exists."}},"/business/equipment/tasks":{"post":{"operationId":"createDetectionTask","description":"Derive a structured corrective maintenance task from an equipment detection through the standard task pipeline (validation, idempotency, outbox, matching, approvals). Task creation only; execution governance is never bypassed. requestSchema: {detection_id, budget_amount_minor, deadline_hours?, title?}."}},"/procurement/intelligence":{"get":{"operationId":"getProcurementIntelligence","description":"Organization-scoped, explainable procurement metrics and workflow alerts. Requesters see only their own requests. Potential budget headroom is not represented as realized savings; no supplier contact, external order, delivery verification, or payment is triggered."}},"/procurement/command-centre":{"get":{"operationId":"getProcurementCommandCentre","description":"Organization-scoped operational metrics for open requests, RFQ responses, approaching/overdue deadlines, supplier inbox and invoice exceptions."}},"/procurement/notifications":{"get":{"operationId":"listProcurementNotifications","description":"List organization-scoped in-app procurement notifications with actor-specific read state."}},"/procurement/notifications/{notification_id}/read":{"post":{"operationId":"markProcurementNotificationRead","description":"Mark a procurement notification as read for the authenticated actor only."}},"/procurement/automation/run":{"post":{"operationId":"runProcurementDeadlineChecks","description":"Run idempotent in-app RFQ deadline reminders for the authenticated organization. Does not send external messages or auto-close requests."}},"/procurement/approval-policy":{"get":{"operationId":"getProcurementApprovalPolicy","description":"Read the organization's procurement single-approval threshold policy."},"post":{"operationId":"setProcurementApprovalPolicy","description":"Administrator-only. Configure a currency-specific amount threshold above which two distinct authorized administrators must approve. Does not authorize automatic order or payment."}},"/business-network/matches":{"get":{"operationId":"matchBusinessSuppliers","security":[],"description":"Public read-only supplier fit search. Hard constraints are applied before explainable preference ranking; fit score is not a trust score or endorsement. Supplier claims remain unverified unless independently reviewed.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":160}},{"name":"country","in":"query","schema":{"type":"string","maxLength":100}},{"name":"category","in":"query","schema":{"type":"string","maxLength":100}},{"name":"quantity","in":"query","schema":{"type":"integer","minimum":1}},{"name":"currency","in":"query","schema":{"type":"string","pattern":"^[A-Z]{3}$"}},{"name":"max_price_minor","in":"query","schema":{"type":"integer","minimum":0}},{"name":"max_lead_time_days","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Eligible supplier capabilities, fit explanations, exclusions, pagination metadata, and candidate-scan truncation state."}}}},"/procurement/invitations":{"post":{"operationId":"inviteSupplierToRfq","description":"Invite a registered public supplier business to an open organization-scoped procurement request. Records an in-platform invitation only; external email or messaging requires a configured notification integration."}},"/procurement/invitations/mine":{"get":{"operationId":"listMySupplierRfqInvitations","description":"List RFQ invitations addressed to the authenticated supplier organization."}},"/procurement/invitations/{invitation_id}/respond":{"post":{"operationId":"respondToSupplierRfq","description":"Submit one quote against an invitation for the authenticated supplier organization. Quote is added to the buyer's procurement record without granting the supplier general access to buyer data."}},"/procurement/invitations/{invitation_id}/decline":{"post":{"operationId":"declineSupplierRfq","description":"Decline a pending RFQ invitation for the authenticated supplier organization."}},"/procurement/requests/{request_id}/invitations":{"get":{"operationId":"listRfqInvitations","description":"List suppliers invited to a buyer-owned procurement request."}},"/procurement/requests":{"get":{"operationId":"listProcurementRequests","description":"List procurement requests scoped to the authenticated organization; requesters see only their own requests."},"post":{"operationId":"createProcurementRequest","description":"Create an approval-gated procurement request. Requires Idempotency-Key. Does not contact suppliers or initiate payment.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200}}],"responses":{"201":{"description":"Procurement request created or idempotently replayed."},"409":{"description":"Idempotency payload conflict."}}}},"/procurement/requests/{request_id}":{"get":{"operationId":"getProcurementRequest","description":"Get organization-scoped request, quote comparisons, invoice status, and procurement event history. Requesters can view only their own requests."}},"/procurement/requests/{request_id}/quotes":{"post":{"operationId":"recordSupplierQuote","description":"Operator/admin records a supplier quote. Requires Idempotency-Key; currency must match the request."}},"/procurement/requests/{request_id}/select-quote":{"post":{"operationId":"selectProcurementQuote","description":"Select a quote for the request, enforcing request ownership, currency, and budget. Selection is not purchase approval."}},"/procurement/requests/{request_id}/approve":{"post":{"operationId":"approveProcurementRequest","description":"Administrator-only approval gate before an order can be recorded. Does not place an external order or authorize payment."}},"/procurement/requests/{request_id}/order":{"post":{"operationId":"recordProcurementOrder","description":"Record that an authorized operator has placed an order externally. Nexus does not create the external order."}},"/procurement/requests/{request_id}/delivery":{"post":{"operationId":"recordProcurementDelivery","description":"Record a delivery evidence reference. The reference is operator-supplied and is not independently verified by this endpoint."}},"/procurement/requests/{request_id}/invoices":{"post":{"operationId":"recordProcurementInvoice","description":"Compare invoice amount and currency to the selected quote. Variances require review; no payment is initiated."}},"/procurement/requests/{request_id}/resolve-discrepancy":{"post":{"operationId":"resolveProcurementInvoiceDiscrepancy","description":"Administrator-only explicit variance resolution with a mandatory reason. Does not authorize payment."}},"/procurement/requests/{request_id}/close":{"post":{"operationId":"closeProcurementRequest","description":"Close only after reconciliation and resolution of all invoice discrepancies."}},"/procurement/requests/{request_id}/cancel":{"post":{"operationId":"cancelProcurementRequest","description":"Administrator-only cancellation before order placement."}},"/business/work-items":{"get":{"operationId":"listBusinessWorkItems","description":"List organization-scoped business work items. Requesters see only their own requests. New items remain pending approval and are not dispatched.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Approval-gated business work items."}}},"post":{"operationId":"createBusinessWorkItem","description":"Create a standard Nexus task linked to a business work item. Requires Idempotency-Key. Creation does not itself route or dispatch work; an organization administrator must approve it, then an authorized operator explicitly launches it.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"object","description":"Standard Nexus task payload, including title, action, location coordinates, future deadline, requirements, evidence_requirements, and budget."}}}}}},"responses":{"201":{"description":"Work item created in PENDING_APPROVAL state; no dispatch occurred."},"409":{"description":"Idempotency key conflict or request already in progress."}}}},"/business/work-items/{id}":{"get":{"operationId":"getBusinessWorkItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Business work item and linked task."},"404":{"description":"Not found in this organization."}}}},"/business/work-items/{id}/approve":{"post":{"operationId":"approveBusinessWorkItem","description":"Organization administrator approval only. Approval does not itself route or dispatch the task.","responses":{"200":{"description":"Work item approved; explicit launch remains required."}}}},"/business/work-items/{id}/reject":{"post":{"operationId":"rejectBusinessWorkItem","description":"Organization administrator rejects a pending item and cancels its linked unlaunched task.","responses":{"200":{"description":"Rejected work item and cancelled task."}}}},"/business/work-items/{id}/launch":{"post":{"operationId":"launchBusinessWorkItem","description":"Explicitly route an approved task through the existing Nexus matching engine. Does not imply executor acceptance or completed work.","responses":{"200":{"description":"Routing result and linked task state."}}}},"/business/operations":{"get":{"operationId":"getBusinessOperationsOverview","description":"Organization-scoped task outcome metrics and prioritized operational alerts. Signals derive from task metadata and do not prove physical outcomes or financial savings.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Task state counts, outcome rates, and prioritized alerts."}}}},"/business/autopilot":{"get":{"operationId":"getBusinessAutopilotBriefing","description":"Read-only, organization-scoped task and procurement briefing. Includes deadline, supplier-response, invitation, and invoice-discrepancy signals for roles permitted to use procurement; requester procurement views are limited to their own requests. Recommendations never dispatch, approve, place orders, send external messages, pay, or modify records.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Summary, prioritized recommendations, alerts, and explicit execution limitations."}}}},"/business/workflow-baselines":{"get":{"operationId":"listWorkflowBaselines","description":"Organization-scoped user-supplied workflow baselines compared with matching recorded task metadata. Estimated capacity value is a proxy, not realized savings."},"post":{"operationId":"createWorkflowBaseline","description":"Admin-only immutable baseline snapshot. Requires workflow_key, workflow_name, tasks_per_week, minutes_per_task, and failure_rate_percent; optional hourly_cost_minor and currency. No execution action is triggered."}},"/business/outcome-intelligence":{"get":{"operationId":"getBusinessOutcomeIntelligence","description":"Read-only organization-scoped outcome indicators, task-state distribution, turnaround proxies, and evidence-conscious recommendations. Does not claim physical truth, causation, or financial savings.","responses":{"200":{"description":"Outcome metrics, sample sizes, recommendations, and explicit limitations."}}}},"/business/risk-radar":{"get":{"operationId":"getBusinessRiskRadar","description":"Organization-scoped deterministic risk signals derived from task state, deadlines, assignments, and update timestamps. Does not claim to predict real-world risk.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Risk level, severity counts, and operational alerts."}}}},"/business/cost-intelligence":{"get":{"operationId":"getBusinessCostIntelligence","description":"Organization-scoped task outcome and turnaround proxies. Does not infer financial cost or savings without verified inputs.","responses":{"200":{"description":"Completion/failure rates and duration proxy."}}}},"/business/memory":{"get":{"operationId":"listCompanyMemory","description":"Search organization-scoped company knowledge records. Knowledge is user supplied and not independently certified.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":160}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Company memory records."}}},"post":{"operationId":"createCompanyMemory","description":"Create a knowledge record for the authenticated organization. Admin/operator role and task.create permission required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","content"],"properties":{"title":{"type":"string","maxLength":160},"content":{"type":"string","maxLength":12000},"tags":{"type":"array","maxItems":12,"items":{"type":"string","maxLength":40}},"source":{"type":"string","maxLength":80}}}}}},"responses":{"201":{"description":"Created organization-scoped knowledge record."}}}},"/business/memory/{id}":{"delete":{"operationId":"deleteCompanyMemory","description":"Soft-delete a knowledge record within the authenticated organization. Admin role required.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Record removed from active memory."},"404":{"description":"Record not found in this organization."}}}},"/business/automation-profile":{"get":{"operationId":"getBusinessAutomationProfile","description":"Read organization automation preferences; existing engine authorization remains authoritative.","responses":{"200":{"description":"Automation profile and enforcement limitations."}}},"post":{"operationId":"updateBusinessAutomationProfile","description":"Update organization admin's automation preferences. Only fixed notification actions may be selected; this does not grant execution permissions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"autonomy_mode":{"type":"string","enum":["observe","recommend","approval_required","bounded_autonomy"]},"automatic_actions":{"type":"array","maxItems":3,"items":{"type":"string","enum":["notify.owner","notify.requester","notify.operator"]}}}}}}},"responses":{"200":{"description":"Saved configuration-only profile. High-impact approval remains required."}}}},"/business/events":{"post":{"operationId":"ingestBusinessEvent","description":"Convert a supported authenticated business event into an idempotent execution task. Requires task.create; does not automatically dispatch or assert that the reported condition is true. event_id is scoped to the organization and actor. Required task fields include location coordinates, future deadline, and budget.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_id","event_type","task"],"properties":{"event_id":{"type":"string","maxLength":160},"event_type":{"type":"string","enum":["maintenance.inspection.required","facility.issue.detected","delivery.milestone.missed","inventory.shortage.detected"]},"summary":{"type":"string","maxLength":140},"task":{"type":"object","description":"Standard Nexus task fields including title, location, deadline, and budget."}}}}}},"responses":{"201":{"description":"Task created or safely replayed for this event identifier."},"400":{"description":"Unsupported or invalid event."},"409":{"description":"Event identifier reused with different task details."}}}},"/business/loss-records":{"get":{"operationId":"listLossRecords","description":"Organization-scoped loss-domain source data records (inventory, equipment, logistics, financial, project). Read requires task.read.","parameters":[{"name":"record_type","in":"query","schema":{"type":"string","maxLength":100}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":200}}],"responses":{"200":{"description":"Ingested loss-domain records and their lineage."}}},"post":{"operationId":"ingestLossRecord","description":"Ingest one loss-domain source record. Admin/operator role and task.create permission required. Ingestion is idempotent per organization record_type/record_reference: byte-identical replays are accepted; divergent payloads are rejected without overwrite and do not trigger automatic execution.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["record_type","idempotency_key","source_system","data"],"properties":{"record_type":{"type":"string","maxLength":100},"record_reference":{"type":"string","maxLength":160},"idempotency_key":{"type":"string","maxLength":200},"source_system":{"type":"string","maxLength":60},"observed_at":{"type":"string"},"occurred_at":{"type":"string"},"currency":{"type":"string","maxLength":8},"data":{"type":"object","description":"Structured loss-domain payload consumed by deterministic detection rules; keys are validated per record_type."}}}}}},"responses":{"200":{"description":"Record ingested or deterministically replayed."},"400":{"description":"Validation failure for the record_type schema."},"409":{"description":"Same record reference with a different payload."}}}},"/business/loss-profile":{"get":{"operationId":"getLossCalculationProfile","description":"Organization calculation profile: exposure formulas per rule, working capital model, proposal threshold, and settled evidence-weight threshold. Exposes how numbers are computed; never asserts they are realized losses.","responses":{"200":{"description":"Effective calculation profile (default when unset)."}}}},"/business/loss-records/{id}":{"get":{"operationId":"getLossRecord","description":"One ingested loss-domain record with source data and lineage.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Record payload and capture lineage."},"404":{"description":"Not found in this organization."}}}},"/business/loss-intelligence/overview":{"get":{"operationId":"getLossIntelligenceOverview","description":"Organization-scoped loss intelligence overview: confirmed exposure by currency, estimated exposure, recovered and prevented value, severity counts, and open investigation and prediction counts. Estimated exposure is a calculation over user-supplied data, never asserted realized loss.","responses":{"200":{"description":"Aggregated loss overview with explicit calculation limitations."}}}},"/business/loss-intelligence/records/{id}":{"get":{"operationId":"getLossRecord","description":"One ingested loss-domain record with source data and lineage.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Record payload and capture lineage."},"404":{"description":"Not found in this organization."}}}},"/business/loss-detections":{"get":{"operationId":"listLossDetections","description":"Organization-scoped deterministic loss detections from user-supplied data. Each detection carries exposure calculation, methodology, source records, and confidence. Statuses: OPEN, CONFIRMED, PREVENTED, DISMISSED.","parameters":[{"name":"domain","in":"query","schema":{"type":"string","enum":["inventory","equipment","logistics","financial","project"]}},{"name":"status","in":"query","schema":{"type":"string","maxLength":40}},{"name":"severity","in":"query","schema":{"type":"string","maxLength":20}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":200}}],"responses":{"200":{"description":"Detection list and aggregate exposure by currency."}}}},"/business/loss-detections/run":{"post":{"operationId":"runLossDetection","description":"Run deterministic detection rules over ingested loss-domain records. Admin role required. Idempotent against unchanged data; corroboration updates confidence and exposure for existing detections. Does not move money, dispatch tasks, or send messages.","responses":{"200":{"description":"Detection run summary: created, corroborated, and predictions derived."},"403":{"description":"Administrator role required."}}}},"/business/loss-detections/{id}":{"get":{"operationId":"getLossDetection","description":"Detection detail: calculation, methodology, linked source records, history, and linked investigation.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detection detail."},"404":{"description":"Not found in this organization."}}}},"/business/loss-detections/{id}/classify":{"post":{"operationId":"classifyLossDetection","description":"Quick classification of a detection as CONFIRMED or DISMISSED before an investigation. Admin role required; the classification reason is recorded. Full lifecycle decisions (CONFIRM_LOSS, PREVENTED_LOSS, NO_LOSS) belong to investigations.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision","reason"],"properties":{"decision":{"type":"string","enum":["CONFIRMED","DISMISSED"]},"reason":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"Updated detection with recorded classification."},"404":{"description":"Not found in this organization."}}}},"/business/loss-predictions":{"get":{"operationId":"listLossPredictions","description":"Organization-scoped forward-looking loss predictions (frequency trends, stockout horizon) with signals, confidence, and explicit insufficient-evidence entries when data volume is below the settled evidence threshold.","parameters":[{"name":"status","in":"query","schema":{"type":"string","maxLength":20}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":200}}],"responses":{"200":{"description":"Prediction list with methodology and limitation notes."}}}},"/business/loss-predictions/{id}/close":{"post":{"operationId":"closeLossPrediction","description":"Close a prediction with a human-recorded outcome (REALIZED, PREVENTED, INACCURATE). Admin role required.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["resolved_as"],"properties":{"resolved_as":{"type":"string","enum":["REALIZED","PREVENTED","INACCURATE"]}}}}}},"responses":{"200":{"description":"Closed prediction with recorded outcome."},"404":{"description":"Not found in this organization."}}}},"/business/loss-investigations":{"get":{"operationId":"listLossInvestigations","description":"Organization-scoped loss investigations with detection, corrective task linkage, verification state, and recovered value.","parameters":[{"name":"status","in":"query","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":200}}],"responses":{"200":{"description":"Investigation list."}}}},"/business/loss-investigations/{id}":{"get":{"operationId":"getLossInvestigation","description":"Investigation detail with detection, task history, recoveries, and audit history.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Investigation detail."},"404":{"description":"Not found in this organization."}}}},"/business/loss-investigations/{id}/assign":{"post":{"operationId":"assignLossInvestigation","description":"Assign or reassign the reviewer for a loss investigation. Admin role required.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reviewer"],"properties":{"reviewer":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"Updated investigation."},"404":{"description":"Not found in this organization."}}}},"/business/loss-investigations/{id}/link":{"post":{"operationId":"linkLossCorrectiveTask","description":"Link an existing, same-organization Nexus task as the corrective task for an investigation; moves an OPEN/UNDER_REVIEW investigation to EXECUTION_IN_PROGRESS. Admin role required.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task_id"],"properties":{"task_id":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"Updated investigation with the linked corrective task."},"404":{"description":"Investigation or task not found in this organization."}}}},"/business/loss-investigations/{id}/decision":{"post":{"operationId":"decideLossInvestigation","description":"Record decision: CONFIRM_LOSS (investigation proceeds to corrective execution), PREVENTED_LOSS, or NO_LOSS. Admin role required.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision","reason"],"properties":{"decision":{"type":"string","enum":["CONFIRM_LOSS","PREVENTED_LOSS","NO_LOSS"]},"reason":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"Updated investigation and detection status."},"404":{"description":"Not found in this organization."}}}},"/business/loss-investigations/{id}/verify":{"post":{"operationId":"verifyLossInvestigation","description":"Mark a linked corrective-executed investigation as verification pending. Admin role required.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Investigation set to VERIFICATION_PENDING."},"404":{"description":"Not found in this organization."}}}},"/business/loss-investigations/{id}/outcome":{"post":{"operationId":"recordLossOutcome","description":"Record a verified financial outcome (RECOVERED or PREVENTED value) against an investigation. Requires a distinct named approver (never the recording actor), evidence references, and cannot exceed the confirmed exposure. Admin/super-admin/finance-manager role; the underlying financial adjustment is owned by organizations.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","amount_minor","currency","approved_by"],"properties":{"kind":{"type":"string","enum":["RECOVERED","PREVENTED"]},"amount_minor":{"type":"integer","minimum":1},"currency":{"type":"string","maxLength":8},"approved_by":{"type":"string","maxLength":120},"evidence_references":{"type":"array","maxItems":8,"items":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Recorded recovery entry and updated totals."},"400":{"description":"Invalid outcome payload."},"409":{"description":"Recovery exceeds confirmed exposure or investigation state forbids it."}}}}},"/business/loss-investigations/{id}/execute":{"post":{"operationId":"executeLossCorrectiveTask","description":"Create and link a corrective task through the standard Nexus task pipeline (billing hold, matching, routing stay authoritative; no auto-dispatch). Admin role required; execution mutations remain gated by execution-mode policy.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"object","description":"Standard Nexus task payload including location, deadline, and budget supplied by the investigator."}}}}}},"responses":{"200":{"description":"Created corrective task linked to the investigation."},"404":{"description":"Not found in this organization."}}}},"/trust/passport":{"get":{"operationId":"getOwnTrustPassport","description":"Assemble the caller's own Trust Passport from verified records and their provenance (identity and credential claims, per-organization behavioural facts, settled payments, dispute counts, active grants). Subjects see themselves only; facts remain organization-scoped and are not a character model or a credit score."}},"/trust/passport/export":{"get":{"operationId":"exportOwnTrustPassport","description":"Export the caller's own Trust Passport as a durable JSON export. Writes an export register entry with record count plus a SHA-256 digest of the export payload, records access-log entries, and returns an explicit retention window for the register."},"post":{"operationId":"exportOwnTrustPassportPost","description":"Export the caller's own Trust Passport (same contract as GET) with an optional purpose_note recorded in the audit trail.","responses":{"200":{"description":"Export payload with digest and retention metadata."}}}},"/trust/exports":{"get":{"operationId":"listTrustPassportExports","description":"List the caller's own passport exports and their digests/retention windows."}},"/trust/facts":{"get":{"operationId":"listBehaviourFactSubjects","description":"Organization-scoped listing of subjects with computed behavioural facts (admin/operator/requester roles). Executors receive their own latest facts directly.","responses":{"200":{"description":"Subjects with latest behaviour computation run references."}}}},"/trust/facts/{subject_id}":{"get":{"operationId":"getBehaviourFacts","description":"Latest behavioural facts for one subject within the caller's organization. Facts are classified verified_fact / inferred_pattern / insufficient_evidence with methodology, evidence references, confidence and limitations; timing observations are neutral and never read as honesty signals.","parameters":[{"name":"subject_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/trust/facts/{subject_id}/runs":{"get":{"operationId":"listBehaviourFactRuns","description":"Computation-run history for one subject within the caller's organization.","parameters":[{"name":"subject_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}}]}},"/trust/facts/{subject_id}/compute":{"post":{"operationId":"computeBehaviourFacts","description":"Recompute deterministic behavioural facts for a subject from the organization's own execution records (tasks, assignments, verification runs and human reviews, disputes, settled payments). Subject's own executor identity or organization admin/operator only; bounded by a 7-1095 day lookback window. Never uses protected characteristics; never judges character.","parameters":[{"name":"subject_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lookback_days":{"type":"integer","minimum":7,"maximum":1095,"default":180}}}}}},"responses":{"200":{"description":"Computation run summary with rule version and category counts."},"403":{"description":"Not the subject nor an organization administrator."}}}},"/trust/grants":{"get":{"operationId":"listTrustGrants","description":"Consent grants visible to the caller: a subject (executor or matching actor identity) sees their own grants; controller or grantee organization administrators see grants in their organization. Effective status (including expiry) is evaluated at read time.","parameters":[{"name":"subject_id","in":"query","schema":{"type":"string","maxLength":128}}]},"post":{"operationId":"createTrustGrant","description":"Issue a purpose-specific consent grant: a subject (or a controller-organization administrator acting on their behalf) authorizes one grantee organization for an explicit field scope with a bounded expiry (1 hour to 365 days) under nexus-trust-disclosure-v1. The grantee and controller organizations must differ; data_export is subject self-service only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_id","grantee_organization_id","purpose_code","fields","consent_disclosure_version","expires_at"],"properties":{"subject_id":{"type":"string","maxLength":128},"grantee_organization_id":{"type":"string","maxLength":128},"purpose_code":{"type":"string","enum":["professional_history","work_completion","credential_verify","credit_evaluation"]},"fields":{"type":"array","minItems":1,"items":{"type":"string"}},"consent_disclosure_version":{"type":"string","maxLength":80},"expires_at":{"type":"string","description":"ISO timestamp with timezone, within 365 days"},"controller_consent_ref":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Grant issued (re-granting supersedes a prior grant for the same tuple and records the previous status)."},"403":{"description":"Caller is neither the subject nor a controller administrator."},"400":{"description":"Validation failure for purpose, fields, expiry or consent version."}}}},"/trust/grants/{grant_id}":{"get":{"operationId":"getTrustGrant","description":"One consent grant with its effective status; the subject or an organization of the grant may read it.","parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Grant detail."},"404":{"description":"Not visible to this caller."}}}},"/trust/grants/{grant_id}/revoke":{"post":{"operationId":"revokeTrustGrant","description":"Revoke a grant. The subject or the controller organization may revoke at any time; the reason is mandatory and recorded, and the revocation is logged.","parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":3,"maxLength":500}}}}}},"responses":{"200":{"description":"Grant revoked; future disclosure is refused and logged."},"403":{"description":"Caller is not the subject nor the controller organization."}}}},"/trust/access-log":{"get":{"operationId":"listTrustAccessLog","description":"Append-only access log: subjects see entries about themselves; organization administrators see entries for their organization's controller or grantee roles. Grants, disclosures, denials, scope denials, expirations and revocations are all recorded.","parameters":[{"name":"subject_id","in":"query","schema":{"type":"string"}},{"name":"purpose_code","in":"query","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}]}},"/trust/disclosure/{grant_id}":{"post":{"operationId":"postTrustDisclosure","description":"Selective disclosure read for the grantee organization: returns ONLY the intersection of requested fields with the grant's field scope, each fact carrying provenance (controller organization, rule version), record timestamps, confidence, explicit limitations and challenge overlays. Every read is logged, including denials and scope denials. Executor identities cannot consume disclosures.","parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requested_fields"],"properties":{"requested_fields":{"type":"array","minItems":1,"items":{"type":"string","maxLength":80}},"purpose_note":{"type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"Authorized fields only, with provenance, limitations and access_id."},"403":{"description":"Grant expired, revoked, or requested fields are outside the grant scope; the denial is logged."},"404":{"description":"Grant not found or the caller is not the grantee; logged."}}}},"/trust/challenges":{"get":{"operationId":"listTrustChallenges","description":"Challenges visible to the caller: the subject's own challenges plus, for administrators, challenges within their organization."},"post":{"operationId":"fileTrustChallenge","description":"An individual files a correction or dispute against one of their records: a trust claim, a behavioural fact, or a credit assessment. Opening a challenge creates a linked open human-review row; it never changes the challenged record's stored value by itself.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_type","target_id","statement","requested_correction"],"properties":{"target_type":{"type":"string","enum":["trust_claim","behaviour_fact","credit_assessment"]},"target_id":{"type":"string","maxLength":128},"statement":{"type":"string","minLength":8,"maxLength":2000},"requested_correction":{"type":"string","minLength":3,"maxLength":1000}}}}}},"responses":{"200":{"description":"Challenge filed with an open human review."},"404":{"description":"Target is not among the caller's records."}}}},"/trust/challenges/{challenge_id}":{"get":{"operationId":"getTrustChallenge","description":"One challenge; the subject or the target organization may read it."}},"/trust/challenges/{challenge_id}/review":{"post":{"operationId":"startTrustChallengeReview","description":"Move an open challenge to under_review; the reviewing human is an organization or platform administrator distinct from the filer by construction of the resolve step.","parameters":[{"name":"challenge_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Challenge under review."},"409":{"description":"Challenge is not open or is already resolved."}}}},"/trust/challenges/{challenge_id}/resolve":{"post":{"operationId":"resolveTrustChallenge","description":"Resolve an under-review challenge: accepted (record corrected or needs re-verification; accepted claim challenges set the claim to pending with an audit event) or rejected (record upheld). The resolver MUST be a distinct human from the filer; the decision is recorded in the linked human-review row with reason and identity.","parameters":[{"name":"challenge_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision","note"],"properties":{"decision":{"type":"string","enum":["accepted","rejected"]},"note":{"type":"string","minLength":3,"maxLength":1000}}}}}},"responses":{"200":{"description":"Resolved challenge with resolution note."},"409":{"description":"Resolver equals the filer, the state forbids resolution, or the challenge is already resolved."}}}},"/trust/challenges/{challenge_id}/withdraw":{"post":{"operationId":"withdrawTrustChallenge","description":"The filer withdraws an open or under-review challenge. Accepted or rejected challenges cannot be withdrawn; the state transition is recorded and the linked human-review row is closed.","parameters":[{"name":"challenge_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Challenge withdrawn or already terminal."},"404":{"description":"Challenge not found among the caller's records."}}}},"/trust/human-reviews":{"get":{"operationId":"listTrustHumanReviews","description":"Human-review queue rows (challenge and credit-assessment reviews) with status, decision, decision_reason, decided_by and decided_at; organizations see their own, platform administrators see all."},"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","completed"]}}]},"/trust/credit/model-info":{"get":{"operationId":"getCreditModelInfo","description":"Published credit-assessment model governance information: model versions, separated components, decision-support-only status, human review requirement before release, explicit absence of imputation and protected characteristics, and monitoring limitations."}},"/trust/credit/assessments":{"get":{"operationId":"listCreditAssessments","description":"Lender-side assessment runs; released runs expose separated components, pending runs expose only their pending state (fail-closed).","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending_human_review","released","rejected","withdrawn"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}]},"post":{"operationId":"createCreditAssessment","description":"Create a credit assessment run for one subject from authorized controller organizations. Requires an active credit_evaluation consent grant from each controller covering the subject and the lender. Computes five separated components (professional_reliability, income_stability, repayment_capacity, repayment_performance, fraud_identity_risk); missing evidence yields insufficient_evidence rather than imputation. Execution does not approve credit: the run enters pending_human_review and is withheld until a distinct human reviewer releases it. Nexus never decides loans, rates, or eligibility.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_id","controller_organization_ids"],"properties":{"subject_id":{"type":"string","maxLength":128},"controller_organization_ids":{"type":"array","minItems":1,"items":{"type":"string","maxLength":128}},"supplied_context":{"type":"object","description":"Lender-supplied references (lender_supplied, obligations_supplied, repayment_history_supplied, purpose_note, cashflow_references) recorded as references; Nexus does not score beyond system evidence."},"purpose_note":{"type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"Pending-human-review run for the requesting role; components withheld until release."},"403":{"description":"No active consent grant, wrong role, or self-controller conflict."}}}},"/trust/credit/assessments/{run_id}":{"get":{"operationId":"getCreditAssessment","description":"One assessment run. For the lender: released runs expose the separated components with evidence and explanations; pending runs intentionally expose no components. The subject sees a subject-shaped view with an explicit challenge note.","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Run view shaped by the caller's authorization."},"404":{"description":"Run not visible to this caller."}}}},"/trust/credit/assessments/{run_id}/review":{"post":{"operationId":"reviewCreditAssessment","description":"Human oversight gate: a lender reviewer distinct from the requesting actor approves (releases components with a recorded identity, reason and review time) or rejects the run. This is an independent authorization step, not an automated scoring event.","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision","reason"],"properties":{"decision":{"type":"string","enum":["approved","rejected"]},"reason":{"type":"string","minLength":3,"maxLength":1000}}}}}},"responses":{"200":{"description":"Released or rejected run with the recorded human decision."},"403":{"description":"Not a lender reviewer."},"409":{"description":"Reviewer equals the requester, or the run is not pending."}}}},"/trust/credit/assessments/{run_id}/withdraw":{"post":{"operationId":"withdrawCreditAssessment","description":"Withdraw a pending assessment run (requesting actor or lender administrator). Released or rejected runs cannot be withdrawn.","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Withdrawn run."},"409":{"description":"Run is not pending."}}}},"/routing/queue":{"get":{"operationId":"getRoutingQueue","description":"Organization-scoped bounded human-routing work queue; requires task.match."}},"/tasks/{task_id}/evidence/{evidence_id}":{"get":{"operationId":"getTaskEvidenceObject","description":"Retrieve task-scoped evidence for an authorized participant."}},"/tasks/{task_id}/evidence-upload-intent":{"post":{"operationId":"createEvidenceUploadIntent"}},"/tasks/{task_id}/evidence":{"post":{"operationId":"submitTaskEvidence","description":"Submit task-bound evidence. Requires evidence_consent=true and consent_version=proof-of-work-disclosure-v1. Private binary objects are server-hashed; server receipt time is recorded separately from client-reported capture time. A human review is required before completion or payment."}},"/tasks/{task_id}/outcome":{"get":{"operationId":"getTaskOutcome","description":"Verified-outcome contract (nexus.task_outcome.v1): lifecycle state, verification verdict, and authenticated evidence summary. verified is true only when human review approved the submitted evidence; an executor completion claim alone is never an outcome."}},"/tasks/{task_id}/scope":{"post":{"operationId":"createTaskScopeToken","description":"Issue a per-task scope token (nexus.scope.v1, nxscp_ bearer prefix) bound to exactly one task and organization: a least-privilege permission subset (task.read, evidence.submit \u2014 never broader role permissions) with a TTL between 60 and 3600 seconds. The scoped credential is confined to /v1/tasks/<task_id> and /api/tasks/<task_id> routes for external execution agents; it cannot mint further scope tokens."}},"/tasks/{task_id}/verification-review":{"post":{"operationId":"reviewTaskVerification"}},"/evidence/uploads/{upload_token}":{"post":{"operationId":"uploadTaskEvidence","description":"Upload raw evidence bytes using a task-bound single-use token."}},"/assignments/{assignment_id}/response":{"post":{"operationId":"respondToAssignmentOffer","description":"Assigned executor can accept or reject an offer; responses are organization-scoped and safe to retry."}},"/assignments/{assignment_id}/lease":{"get":{"operationId":"getAssignmentLease"},"post":{"operationId":"acquireAssignmentLease"}},"/assignments/{assignment_id}/lease/release":{"post":{"operationId":"releaseAssignmentLease"}},"/assignments/{assignment_id}/negotiations":{"post":{"operationId":"negotiateAssignment"}},"/executors":{"post":{"operationId":"registerExecutorProfile","description":"Register an executor profile in the caller's organization."}},"/executors/{executor_id}":{"get":{"operationId":"getExecutorProfile"}},"/executors/{executor_id}/availability":{"post":{"operationId":"setExecutorAvailability"}},"/executors/{executor_id}/credentials/verify":{"post":{"operationId":"verifyExecutorCredential"}},"/executors/{executor_id}/credentials/revoke":{"post":{"operationId":"revokeExecutorCredential"}},"/executors/{executor_id}/behaviour-profile":{"get":{"operationId":"getExecutorBehaviourProfile","description":"Verified-outcome behaviour profile (nexus.behaviour_profile.v1): commitment fulfilment, verification results, on-time share, and delivery consistency computed strictly from human-verified work records. Self-access for the executor, same-organization administrator/operator review, every access audited. Never a statement about honesty, identity, or creditworthiness; no self-reported claims are used.","parameters":[{"name":"executor_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Profile with metrics, fixed tier policy, methodology, and explicit non-inferences."},"404":{"description":"Executor not found or outside the caller's organization."}}}},"/behaviour/fairness":{"get":{"operationId":"getBehaviourFairnessOverview","description":"Organization-level fairness monitoring (nexus.behaviour_fairness.v1): verified-outcome tier distribution across executors, fixed tier policy, and disclosure of what the profiles can and cannot infer. Administrator/operator role required. Nexus stores no demographic attributes.","responses":{"200":{"description":"Cohort distribution and fairness methodology."}}}},"/trust-passport/{subject_id}":{"get":{"operationId":"getTrustPassport"}},"/platform-admin/trust-claims/{claim_id}/review":{"post":{"operationId":"reviewGlobalTrustClaim","description":"Super Admin-only review of a pending trust claim; requires a review reason and evidence reference for verification."}},"/trust-passport/{subject_id}/verify":{"get":{"operationId":"verifyTrustPassportContext","description":"Returns a context-specific verification result that accounts for revocation and expiry."}},"/trust-passport/{subject_id}/claims":{"post":{"operationId":"issueTrustClaim","description":"Administrator-only. Use pending during review; verified claims require an evidence_reference."}},"/trust-passport/claims/{claim_id}/revoke":{"post":{"operationId":"revokeTrustClaim","description":"Administrator-only, organization-scoped claim revocation with audit record."}},"/ops/health":{"get":{"operationId":"getOperationalHealth","description":"Administrator-only consolidated operational health: queue depths (outbox, dead letters, webhook deliveries), worker heartbeats, database probe and integrity, task lifecycle distribution, integration failure counts, security alert summary, and threshold-driven actionable alerts with suggested actions. Quiet unless thresholds are crossed."}},"/executor-network/operations":{"get":{"operationId":"getExecutorNetworkOperations","description":"Administrator-only executor network report: availability distribution, suspended lifecycle records, credentials expiring within a configurable window, verified completion totals. Reliability detail stays in the audited behaviour-intelligence profile; no unexplained universal score."}},"/ops/metrics":{"get":{"operationId":"getOperationalMetrics","description":"Administrator-only Prometheus metrics; low-cardinality and process-local."}},"/network":{"get":{"operationId":"getNetworkOverview"}},"/network/health":{"get":{"operationId":"getNetworkHealth"}},"/events":{"get":{"operationId":"listOrganizationEvents","description":"Organization-scoped durable event stream (nexus.event.v1) from the transactional outbox, with versioned envelope metadata, server-owned correlation ids, provenance, and filters (event_type, task_id, correlation_id). Executor identities cannot read the stream; legacy pre-envelope events are reported as unversioned, never rewritten.","parameters":[{"name":"event_type","in":"query","schema":{"type":"string","maxLength":200}},{"name":"task_id","in":"query","schema":{"type":"string","maxLength":200}},{"name":"correlation_id","in":"query","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Versioned event page with total count and provenance."}}}},"/evidence":{"get":{"operationId":"listEvidence"}},"/verification/queue":{"get":{"operationId":"getVerificationQueue"}},"/platform/catalog":{"get":{"operationId":"getPlatformCatalog","security":[]}},"/billing/plans":{"get":{"operationId":"getBillingPlans","security":[]}},"/billing/subscription":{"get":{"operationId":"getBillingSubscription"},"post":{"operationId":"assignOrganizationPlan","description":"Non-production administrator operation only; production changes require provider-backed billing."}},"/billing/usage":{"get":{"operationId":"getBillingUsage"}},"/billing/catalog":{"get":{"operationId":"getPublishedUsagePrices","description":"Returns active public Nexus unit prices. Metered task overage is charged only after included allowance and organization opt-in."}},"/billing/spending-controls":{"get":{"operationId":"getOrganizationSpendingControls"},"post":{"operationId":"updateOrganizationSpendingControls","description":"Organization administrator only. Explicit PAYG consent, monthly limit, and allow_overage are audited; amount fields use currency minor units."}},"/billing/history":{"get":{"operationId":"getOrganizationBillingHistory","description":"Organization-scoped settled ledger entries and invoices on record. Invoice generation is not yet enabled."}},"/billing/webhooks/{provider}":{"post":{"operationId":"receiveBillingWebhook","security":[],"description":"Provider-neutral HMAC-SHA256 signed event receiver. Send X-Nexus-Signature with t and v1 fields; signature is calculated over timestamp + dot + exact raw request body."}},"/workflow-runs":{"get":{"operationId":"listWorkflowRuns","description":"List recent workflow runs scoped to the authenticated organization; supports bounded status filtering."}},"/maintenance/reassign":{"post":{"operationId":"processAutomaticReassignmentQueue","description":"Operator-triggered, organization-scoped processing of durable reassignment claims."}},"/workflow-runs/{run_id}":{"get":{"operationId":"getWorkflowRunDetail","description":"Organization-scoped workflow run detail including payload, result, lease metadata, and retry audit history."}},"/workflow-runs/{run_id}/retry":{"post":{"operationId":"retryWorkflowRun","description":"Operator/admin-only audited retry for failed workflow runs; already queued requests are idempotent."}},"/workflows":{"get":{"operationId":"listWorkflows"},"post":{"operationId":"createWorkflow"}},"/workflows/templates":{"get":{"operationId":"listWorkflowTemplates"}},"/workflows/templates/{template_id}/install":{"post":{"operationId":"installWorkflowTemplate","description":"Install a fixed, predefined notification workflow in the caller organization; duplicate event/action combinations are not created."}},"/workflows/{workflow_id}/enabled":{"post":{"operationId":"setWorkflowEnabled"}},"/workflows/dispatch":{"post":{"operationId":"dispatchWorkflows","description":"Organization-scoped manual dispatch into the durable worker queue."}},"/notifications":{"get":{"operationId":"listWorkflowNotifications","description":"List in-app workflow notifications for operators in the caller's organization."}},"/maintenance/expire":{"post":{"operationId":"processExpiredWork","description":"Expire overdue tasks and stale offers for the caller's organization."}},"/capacity/reservations":{"post":{"operationId":"reserveExecutorCapacity"}},"/payments":{"get":{"operationId":"listPayments"},"post":{"operationId":"createPayment"}},"/payments/{payment_id}":{"get":{"operationId":"getPayment"}},"/payments/{payment_id}/operations":{"get":{"operationId":"listPaymentOperations"},"post":{"operationId":"operatePayment"}},"/payments/{payment_id}/disputes":{"post":{"operationId":"openPaymentDispute"}},"/payments/{payment_id}/reconcile":{"post":{"operationId":"reconcilePayment"}},"/payments/{payment_id}/resolve-operation":{"post":{"operationId":"resolvePendingPaymentOperation"}},"/financial/settlements":{"get":{"operationId":"listPaymentSettlements"}},"/financial/recovery/run":{"post":{"operationId":"recoverFinancialWork"}},"/webhooks":{"post":{"operationId":"createWebhook"}},"/webhooks/replay":{"post":{"operationId":"replayWebhookDelivery"}},"/webhooks/health":{"get":{"operationId":"getWebhookHealth"}},"/integrations":{"get":{"operationId":"listIntegrations"},"post":{"operationId":"createIntegration"}},"/integrations/{integration_id}":{"delete":{"operationId":"revokeIntegration"}},"/integrations/{integration_id}/promote":{"post":{"operationId":"promoteIntegration","description":"Explicitly promote a sandbox integration to live with rate and quota controls."}},"/integrations/{integration_id}/rotate":{"post":{"operationId":"rotateIntegrationCredential","description":"Rotate a client secret; the replacement is returned once and invalidates the old secret."}},"/integrations/sandbox/execute":{"post":{"operationId":"sandboxExecute","description":"Simulate matching/execution without production side effects."}},"/usage":{"get":{"operationId":"getUsage"}},"/agents/policies":{"get":{"operationId":"listAgentPolicies"},"post":{"operationId":"putAgentPolicy"}},"/agents/runs":{"get":{"operationId":"listAgentRuns"},"post":{"operationId":"proposeAgentRun","description":"Evaluate a proposed agent action; does not perform the action."}},"/agents/runs/{run_id}":{"get":{"operationId":"getAgentRun"}},"/agents/runs/{run_id}/checkpoints":{"post":{"operationId":"checkpointAgentRun"}},"/agents/runs/{run_id}/execute":{"post":{"operationId":"executeAgentRun","description":"Execute only a registered, policy-approved tool; writes are idempotent by run ID."}},"/agents/runs/{run_id}/retry":{"post":{"operationId":"retryAgentRun","description":"Retry a failed run within its durable attempt budget."}},"/agents/runs/{run_id}/approval":{"post":{"operationId":"decideAgentApproval"}},"/agents/runs/{run_id}/checkpoints/verify":{"get":{"operationId":"verifyAgentCheckpointIntegrity"}},"/agents/runs/{run_id}/reconcile":{"post":{"operationId":"reconcileInterruptedAgentRun","description":"Admin-only; safe retry requires evidence and explicit no-side-effect confirmation."}},"/agents/recover-stale":{"post":{"operationId":"recoverStaleAgentRuns","description":"Admin-only quarantine of stale RUNNING executions; no automatic replay."}},"/agents/emergency-stop":{"get":{"operationId":"getAgentEmergencyStop"},"post":{"operationId":"setAgentEmergencyStop"}},"/developer/api-keys":{"get":{"operationId":"listApiKeys"},"post":{"operationId":"createApiKey"}},"/developer/api-keys/{key_id}/rotate":{"post":{"operationId":"rotateApiKey","description":"Rotate a developer API key; the new secret is returned once."}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"x-nexus-principles":["deterministic authorization","idempotent mutations","evidence-backed outcomes","organization isolation"],"request_id":"req_e8d5be08a34baf88670852bfcc259e49"}