{ "openapi": "3.1.0", "info": { "title": "System Friction Institute External Agent API", "version": "1.10.0", "description": "Governed machine interface for authorized AI clients. GPT Actions authenticate with SFI OAuth. Institutional principals receive explicitly configured authority; normal accounts receive only owner-scoped personal Lab, Cognitive and Studio capabilities.", "termsOfService": "https://systemfriction.org/privacy" }, "externalDocs": { "description": "SFI Privacy & External Agent Data Policy", "url": "https://systemfriction.org/privacy" }, "servers": [ { "url": "https://systemfriction.org" } ], "security": [ { "sfiOAuth": [] } ], "paths": { "/api/external/v1/manifest": { "get": { "operationId": "getSfiManifest", "summary": "Discover current SFI agent capabilities", "security": [], "responses": { "200": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/api/external/v1/console": { "get": { "operationId": "readSfiConsole", "summary": "Read the compact governed SFI machine console", "x-sfi-scope": "observe", "security": [ { "sfiOAuth": [ "observe" ] } ], "responses": { "200": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/external/v1/execution-contract": { "post": { "operationId": "getSfiExecutionContract", "summary": "Get the SFI method/measurement contract for an object without sending raw content", "description": "Describe representation, function, question and objective. Supply a client-computed content hash when available.", "x-sfi-scope": "observe", "security": [ { "sfiOAuth": [ "observe" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionContractRequest" } } } }, "responses": { "200": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Invalid object declaration" }, "401": { "description": "Unauthorized" } } } }, "/api/external/v1/result": { "post": { "operationId": "persistSfiStructuredResult", "summary": "Persist a sanitized structured material-analysis result without raw object persistence", "description": "Persists one structured DERIVED analysis result associated with a cycle/object. The Action surface explicitly exposes object identity/provenance, measurements, epistemic partition, primary/rival hypotheses, risks, invariants and optional perturbation/prediction. Raw binary/file/bytes/blob/base64 content remains forbidden and is stripped server-side. This operation does not create ACCEPTED EVIDENCE, canonical truth, RETURN, closure or learning promotion.", "x-sfi-scope": "lab:write", "security": [ { "sfiOAuth": [ "lab:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructuredResultRequest" } } } }, "responses": { "201": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Object and structured result required" }, "401": { "description": "Unauthorized" }, "413": { "description": "Structured result exceeds size limit" } } } }, "/api/external/v1/signal": { "get": { "operationId": "readSfiOpenCycles", "summary": "Read universal open cycles or canonical history for one cycle", "x-sfi-scope": "observe", "security": [ { "sfiOAuth": [ "observe" ] } ], "parameters": [ { "name": "cycleId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Unauthorized" } } }, "post": { "operationId": "processSfiSignal", "summary": "Resolve, observe, run, resume, contrast and close a governed universal SFI cycle", "description": "Supports status/intake/run/return/close for institutional signal cycles. Intake returns unresolved questions, material-observation sufficiency, evidence requirements and any suggested same-object resume cycle. Run fails closed before cognitive inference when the object lacks material observation or required public evidence. Use resumeCycleId to rerun the same open cycle after ingestion/capability remediation; prior runs remain in the same logbook. A bounded AI synthesis may generate falsifiable primary/rival hypotheses and discriminating predictions after deterministic execution. Return is contrasted against predictions. Close is rejected until the methodological closure envelope is sufficient. Closure does not enter institutional learning automatically; learning remains quarantined until governed ROOT promotion.", "security": [ { "sfiOAuth": [ "lab:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalRequest" } } } }, "responses": { "200": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "201": { "description": "Signal/return/closure persisted" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Clarification, object observation, same-cycle resume validation or methodological closure is incomplete" }, "424": { "description": "Required public evidence could not be acquired sufficiently" }, "503": { "description": "Cognitive runtime failure" } } } }, "/api/external/v1/observe": { "post": { "operationId": "observeSfi", "summary": "Read an allowlisted governed SFI state surface", "x-sfi-scope": "observe", "security": [ { "sfiOAuth": [ "observe" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObserveRequest" } } } }, "responses": { "200": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Surface not allowed" }, "401": { "description": "Unauthorized" } } } }, "/api/external/v1/propose": { "post": { "operationId": "proposeSfiAction", "summary": "Submit a governed action proposal for ROOT review", "x-sfi-scope": "propose", "security": [ { "sfiOAuth": [ "propose" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeRequest" } } } }, "responses": { "201": { "description": "Generic SFI response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Title and summary required" }, "401": { "description": "Unauthorized" } } } }, "/api/external/v1/evidence-candidates": { "post": { "operationId": "proposeSfiEvidenceCandidate", "summary": "Submit a source URL as an evidence candidate for ROOT review", "description": "The external principal may submit a candidate, but ROOT remains the acceptance authority.", "x-sfi-scope": "propose", "security": [ { "sfiOAuth": [ "propose" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceCandidateRequest" } } } }, "responses": { "200": { "description": "Candidate already existed" }, "201": { "description": "Evidence candidate registered" }, "400": { "description": "Invalid candidate" }, "401": { "description": "Unauthorized" } } } }, "/api/external/v1/execute": { "post": { "operationId": "executeAuthorizedSfiAction", "summary": "Execute an already-authorized internal SFI action", "description": "Dispatches only an already-authorized queued proposal. This endpoint cannot approve a proposal or promote canon.", "x-sfi-scope": "execute", "security": [ { "sfiOAuth": [ "execute" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteRequest" } } } }, "responses": { "200": { "description": "Execution result" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Queued governed proposal required" } } } }, "/api/external/v1/proposal-return": { "post": { "operationId": "recordSfiProposalReturn", "summary": "Record an observed return for an already queued proposal", "x-sfi-scope": "execute", "security": [ { "sfiOAuth": [ "execute" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalReturnRequest" } } } }, "responses": { "201": { "description": "Observed return persisted" }, "400": { "description": "Invalid return" }, "401": { "description": "Unauthorized" }, "409": { "description": "Queued proposal required" } } } }, "/api/external/v1/lab": { "post": { "operationId": "operateSfiLab", "summary": "Read, persist or run institutional Method Lab operations according to the operation-specific scope", "description": "Institutional Method Lab route. Personal OAuth tenants are blocked from this path and must use /api/external/v1/personal-lab.", "security": [ { "sfiOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabRequest" } } } }, "responses": { "200": { "description": "Method Lab result" }, "201": { "description": "Persisted Method Lab record" }, "400": { "description": "Invalid operation" }, "401": { "description": "Unauthorized" }, "503": { "description": "Runtime failure" } } } }, "/api/external/v1/studio": { "post": { "operationId": "operateOwnedSfiStudioObjects", "summary": "List, inspect, read features/content, or analyze Studio objects owned by the OAuth principal", "description": "User-bound Studio route. Every object operation resolves OAuth subject_id to studio_objects.owner_id.", "security": [ { "sfiOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioRequest" } } } }, "responses": { "200": { "description": "Studio read/reused analysis result" }, "202": { "description": "Studio analysis executed" }, "400": { "description": "Invalid Studio operation" }, "401": { "description": "Missing or insufficient OAuth scope" }, "403": { "description": "User-bound OAuth required" }, "404": { "description": "Owned object not found" }, "415": { "description": "Analyzer not exposed for modality" } } } }, "/api/external/v1/cognitive": { "post": { "operationId": "operatePersonalCognitiveWorkspace", "summary": "Read/run Personal Cognitive and govern owner-scoped cognition/observation patterns", "description": "OAuth subject-bound Personal Cognitive surface. state/patterns require lab:read; propose/confirm/reject pattern operations require lab:write; run requires lab:run. Inferred patterns require at least two distinct owner-scoped run/evidence references before candidacy. Self-declared patterns are stored as DECLARED, not as proof. Confirmation accepts the representation for PERSON_CT only. PERSON_CT cannot become institutional Cognitive Spine state by inheritance; the separate Person→Institution gate remains mandatory.", "security": [ { "sfiOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalCognitiveRequest" } } } }, "responses": { "200": { "description": "Personal Cognitive workspace state" }, "201": { "description": "Personal Cognitive run persisted" }, "207": { "description": "Run completed with degraded automation results" }, "400": { "description": "Invalid operation" }, "401": { "description": "Unauthorized" }, "403": { "description": "OAuth subject required" }, "404": { "description": "Owned case/evidence not found" }, "409": { "description": "Pattern lacks recurrent support, is already terminal, or conflicts with existing owner-scoped state" } } } }, "/api/external/v1/personal-lab": { "post": { "operationId": "operatePersonalLabWorkspace", "summary": "Read, create and run owner-scoped personal Lab work", "description": "OAuth subject-bound. state/report require lab:read; create_case/persist require lab:write; run requires lab:run.", "security": [ { "sfiOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalLabRequest" } } } }, "responses": { "200": { "description": "Personal Lab state or report" }, "201": { "description": "Owned case/evidence/run persisted" }, "207": { "description": "Run completed with degraded automation results" }, "400": { "description": "Invalid operation" }, "401": { "description": "Unauthorized" }, "403": { "description": "OAuth subject required" }, "404": { "description": "Owned case/evidence not found" } } } }, "/api/external/v1/cases": { "post": { "operationId": "operateSfiCaseWorkspace", "summary": "Plan, read, create and populate tenant-scoped SFI Case Platform cases", "description": "User-bound OAuth adapter over the existing Case Platform. Call intake_plan first when case context is incomplete; it returns only unresolved questions. Operations use cases:read or cases:write internally. This route cannot accept evidence, make governance decisions, authorize intervention, record observed RETURN, or create truth claims.", "security": [ { "sfiOAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseWorkspaceRequest" } } } }, "responses": { "200": { "description": "Case read, intake plan or transition result" }, "201": { "description": "Case, source or bounded case object persisted" }, "400": { "description": "Invalid or authority-forbidden case operation" }, "401": { "description": "Missing or insufficient cases scope" }, "403": { "description": "User-bound OAuth required or tenant access forbidden" }, "404": { "description": "Case not found in an accessible tenant" }, "409": { "description": "Case creation is missing required intake context" } } } }, "/api/external/v1/bootstrap": { "get": { "operationId": "getSfiCognitiveBootstrap", "summary": "Hydrate the authorized AI client with the current governed SFI cognitive contract", "description": "Returns a versioned compact context capsule: constitution hash/reference, ontology, epistemic rules, methodology, learning policy, sealed Cognitive Spine snapshot identity, bounded memory/approved decisions, promoted calibrated learning and current open-cycle state. Prior context remains context, not a new observation.", "x-sfi-scope": "observe", "security": [ { "sfiOAuth": [ "observe" ] } ], "parameters": [ { "name": "caseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional current case identifier used to bind the bootstrap capsule to the caller workflow. It does not expand visibility by itself." } ], "responses": { "200": { "description": "Versioned SFI cognitive bootstrap capsule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Unauthorized or observe scope missing" }, "503": { "description": "Bootstrap materialization failed; caller must not silently substitute an unversioned persona prompt" } } } } }, "components": { "schemas": { "SignalObject": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "url", "web_page", "text", "audio", "video", "image", "document", "dataset", "json", "csv", "conversation", "email", "code", "api_response", "sensor", "event", "organization", "person", "place", "composite", "unknown" ] }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "sourceUrl": { "type": "string" }, "assetRef": { "type": "string" }, "objectHash": { "type": "string" }, "contentHash": { "type": "string" }, "fingerprint": { "type": "string" }, "extracted": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "provenance": { "type": "object", "additionalProperties": true }, "observedAt": { "type": "string" } }, "additionalProperties": false }, "ExecutionContractInput": { "type": "object", "required": [ "signal" ], "properties": { "signal": { "$ref": "#/components/schemas/SignalObject" }, "question": { "type": "string" }, "objective": { "type": "string" }, "declaredFunction": { "type": "string" }, "systemType": { "type": "string" }, "context": { "type": "object", "additionalProperties": true }, "declaredTarget": {}, "declaredExclusions": { "type": "array", "items": {} }, "invariants": { "type": "array", "items": {} }, "constraints": { "type": "array", "items": {} }, "requestedAgents": { "type": "array", "items": { "type": "string" } }, "llmAugmentation": { "type": "boolean" } }, "additionalProperties": false }, "ExecutionContractRequest": { "type": "object", "required": [ "input" ], "properties": { "input": { "$ref": "#/components/schemas/ExecutionContractInput" } }, "additionalProperties": false }, "StructuredResultRequest": { "type": "object", "required": [ "object", "result" ], "description": "Persist one sanitized structured material-analysis result. object/result are mandatory; raw content must never be embedded.", "properties": { "cycleId": { "type": "string" }, "question": { "type": "string" }, "objective": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "lineage": { "type": "array", "items": { "type": "string" } }, "object": { "$ref": "#/components/schemas/StructuredResultObject" }, "result": { "$ref": "#/components/schemas/StructuredAnalysisResult" }, "analyzer": { "$ref": "#/components/schemas/StructuredResultAnalyzer" } }, "additionalProperties": false }, "HypothesisInput": { "type": "object", "required": [ "statement" ], "properties": { "statement": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "role": { "type": "string", "enum": [ "primary", "rival" ] } }, "additionalProperties": false }, "UniversalCycleInput": { "type": "object", "required": [ "signal" ], "properties": { "signal": { "$ref": "#/components/schemas/SignalObject" }, "question": { "type": "string" }, "objective": { "type": "string" }, "declaredFunction": { "type": "string" }, "systemType": { "type": "string" }, "context": { "type": "object", "additionalProperties": true }, "declaredTarget": {}, "declaredExclusions": { "type": "array", "items": {} }, "invariants": { "type": "array", "items": {} }, "constraints": { "type": "array", "items": {} }, "hypotheses": { "type": "array", "items": { "$ref": "#/components/schemas/HypothesisInput" } }, "requestedAgents": { "type": "array", "items": { "type": "string" } }, "llmAugmentation": { "type": "boolean" } }, "additionalProperties": false }, "SignalRequest": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string", "enum": [ "status", "intake", "run", "return", "close" ] }, "input": { "$ref": "#/components/schemas/UniversalCycleInput" }, "continueWithOpenCycles": { "type": "boolean", "description": "Explicitly allow an independent parallel cycle for the same object. Do not use this to continue the same methodological question; use resumeCycleId instead." }, "cycleId": { "type": "string" }, "objectKey": { "type": "string" }, "outcome": {}, "classification": { "type": "string" }, "notes": { "type": "string" }, "reason": { "type": "string" }, "evidenceRefs": { "type": "array", "items": { "type": "string" } }, "resumeCycleId": { "type": "string", "description": "Open universal cycle id to reuse when a capability was remediated or a new observation for the same object becomes available. The existing logbook and prior failed/degraded runs are preserved." }, "resumeReason": { "type": "string", "description": "Reason for same-cycle rerun, for example CAPABILITY_REMEDIATION_OR_NEW_OBSERVATION." }, "aiSynthesis": { "type": "boolean", "default": true, "description": "Run one bounded governed AI synthesis after deterministic cognitive execution. Set false only when deterministic outputs alone are desired." }, "closure": { "type": "object", "additionalProperties": true, "description": "Methodological closure envelope. Contrastable/longitudinal/intervention cycles require primary+rival hypothesis, prediction, expected/contradiction signals, observation window, observed return, contrast, updated confidence, outcome and learning candidate. DESCRIPTIVE_DELIMITED may close with explicit conclusion plus limitations/missing evidence." } }, "additionalProperties": false }, "ObserveRequest": { "type": "object", "required": [ "surface" ], "properties": { "surface": { "type": "string", "enum": [ "proposals", "evidence" ] } }, "additionalProperties": false }, "ProposeRequest": { "type": "object", "required": [ "title", "summary" ], "properties": { "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "action": { "type": [ "object", "string", "null" ], "additionalProperties": true } }, "additionalProperties": false }, "EvidenceCandidateRequest": { "type": "object", "required": [ "proposal_id", "source_url" ], "properties": { "proposal_id": { "type": "string", "minLength": 1 }, "source_url": { "type": "string", "format": "uri", "pattern": "^https?://" }, "title": { "type": "string" }, "evidence_note": { "type": "string" } }, "additionalProperties": false }, "ExecuteRequest": { "type": "object", "required": [ "proposal_id", "confirm" ], "properties": { "proposal_id": { "type": "string", "minLength": 1 }, "confirm": { "type": "boolean", "const": true } }, "additionalProperties": false }, "ProposalReturnRequest": { "type": "object", "required": [ "proposal_id", "outcome", "evidence_refs" ], "properties": { "proposal_id": { "type": "string", "minLength": 1 }, "observed_at": { "type": "string" }, "outcome": {}, "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string" } } }, "additionalProperties": true }, "LabRequest": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string", "enum": [ "state", "report", "persist", "run" ] }, "title": { "type": "string" }, "content": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "source": { "type": "string" }, "commandId": { "type": "string" }, "refs": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "protocolId": { "type": "string", "enum": [ "sociotechnical_simulation", "economic_simulation" ] }, "confirm": { "type": "boolean" }, "evidenceIds": { "type": "array", "items": { "type": "string" } }, "parameters": { "type": "object", "additionalProperties": true }, "cognitiveSpineContextRefs": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "StudioRequest": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string", "enum": [ "list", "inspect", "features", "content", "analyze" ] }, "objectId": { "type": "string" }, "force": { "type": "boolean" } }, "additionalProperties": false }, "PersonalCognitiveRequest": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string", "enum": [ "state", "patterns", "propose_pattern", "confirm_pattern", "reject_pattern", "run" ], "description": "Owner-scoped Personal Cognitive operation. Pattern mutations require lab:write; cognitive execution requires lab:run." }, "objective": { "type": "string" }, "question": { "type": "string" }, "caseId": { "type": "string" }, "evidenceIds": { "type": "array", "items": { "type": "string" } }, "requestedAutomations": { "type": "array", "items": { "type": "string" } }, "cognitiveIntents": { "type": "array", "items": { "type": "string" } }, "dimension": { "type": "string", "enum": [ "COGNITION", "OBSERVATION" ] }, "category": { "type": "string", "enum": [ "PROBLEM_DECOMPOSITION", "EVIDENCE_SELECTION", "ATTENTION_ALLOCATION", "SIGNAL_DISCRIMINATION", "HYPOTHESIS_FORMATION", "RIVAL_GENERATION", "DECISION_THRESHOLD", "EXECUTION_RHYTHM", "CONTRADICTION_RESPONSE", "RETURN_CALIBRATION", "TEMPORAL_FRAMING", "SYSTEM_BOUNDARY_SELECTION" ] }, "statement": { "type": "string" }, "operationalMeaning": { "type": [ "string", "null" ] }, "useCases": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "array", "items": { "type": "string" } }, "counterSignals": { "type": "array", "items": { "type": "string" } }, "supportingRunIds": { "type": "array", "items": { "type": "string" } }, "supportingEvidenceIds": { "type": "array", "items": { "type": "string" } }, "selfDeclared": { "type": "boolean", "description": "When true the pattern is stored as DECLARED and does not require recurrence support. It remains a representation, not a proven behavioral invariant." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "patternId": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PersonalLabRequest": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string", "enum": [ "state", "report", "create_case", "persist", "run" ] }, "title": { "type": "string" }, "domain": { "type": "string" }, "objective": { "type": "string" }, "baseline": { "type": "string" }, "verificationWindow": { "type": "string", "enum": [ "72h", "7d", "30d" ] }, "caseId": { "type": "string" }, "label": { "type": "string" }, "content": { "type": "string" }, "source": { "type": "string" }, "reliability": { "type": "number", "minimum": 0, "maximum": 1 }, "evidenceType": { "type": "string" }, "uri": { "type": "string" }, "observedAt": { "type": "string" }, "protocolId": { "type": "string", "enum": [ "sociotechnical_simulation", "economic_simulation" ] }, "evidenceIds": { "type": "array", "items": { "type": "string" } }, "parameters": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "GenericResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "generatedAt": { "type": "string" }, "eventId": { "type": "string" }, "canonicalEventId": { "type": "string" }, "data": {}, "principal": {}, "cycle": {}, "console": {}, "workspace": {}, "warnings": { "type": "array", "items": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "message": { "type": "string" } }, "additionalProperties": true }, "CaseWorkspaceRequest": { "type": "object", "additionalProperties": false, "required": [ "operation" ], "properties": { "operation": { "type": "string", "enum": [ "list", "read", "intake_plan", "create", "add_source", "add_object", "transition", "reports" ] }, "draft": { "type": "object", "additionalProperties": true, "description": "Pre-case draft used by intake_plan. SFI returns only unresolved questions and does not create a case." }, "caseId": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "clientId": { "type": [ "string", "null" ] }, "serviceProfileId": { "type": "string" }, "subject": { "type": "string" }, "scope": { "type": "string" }, "systemBoundaryRef": { "type": "object", "additionalProperties": true }, "temporalWindow": { "type": "object", "additionalProperties": true }, "source": { "type": "object", "additionalProperties": true }, "kind": { "type": "string" }, "canonicalRef": { "type": "object", "additionalProperties": true }, "sourceRefs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recordRefs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "payload": { "type": "object", "additionalProperties": true }, "observedAt": { "type": [ "string", "null" ] }, "status": { "type": "string" } } }, "StructuredResultObject": { "type": "object", "description": "Sanitized identity/provenance envelope for the materially inspected object. Raw content, bytes, blobs and base64 are forbidden.", "properties": { "objectKey": { "type": "string", "description": "Stable methodological object identity used to match/open/resume cycles." }, "id": { "type": "string" }, "kind": { "type": "string", "description": "Representation kind such as dataset, document, text, image, audio, video, json, csv or conversation." }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "logicalFilename": { "type": "string", "description": "Logical/original filename when known." }, "observedTransportFilename": { "type": "string", "description": "Filename exposed by the transport/client; preserve alias differences rather than silently renaming." }, "size": { "type": "integer", "minimum": 0 }, "objectHash": { "type": "string", "description": "Client-computed material/content fingerprint when available; SHA-256 is preferred." }, "contentHash": { "type": "string", "description": "Alias for a material/content fingerprint when objectHash is not used." }, "fingerprint": { "type": "string", "description": "Alternative client content fingerprint." }, "contentHashBasis": { "type": "string", "description": "Hash basis such as SHA256 or CLIENT_CONTENT_FINGERPRINT. Reference identity must remain distinct from content identity." }, "materialIdentityVerified": { "type": "boolean" }, "sourceUrl": { "type": "string" }, "assetRef": { "type": "string" }, "metadata": { "type": "object", "description": "Sanitized non-raw metadata only.", "additionalProperties": true }, "provenance": { "type": "object", "description": "Sanitized provenance/lineage metadata. Do not place raw object content here.", "properties": { "sourceRef": { "type": "string" }, "caseId": { "type": "string" }, "acquisitionMethod": { "type": "string" }, "observedAt": { "type": "string" }, "logicalFilename": { "type": "string" }, "observedTransportFilename": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "StructuredEpistemicEntry": { "type": "object", "required": [ "statement" ], "properties": { "statement": { "type": "string" }, "basis": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "refs": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "StructuredEpistemicPartition": { "type": "object", "description": "Keep observed/declared/derived/inferred/simulated/missing categories distinct. Nothing in this object is automatically ACCEPTED EVIDENCE.", "properties": { "observed": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredEpistemicEntry" } }, "declared": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredEpistemicEntry" } }, "derived": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredEpistemicEntry" } }, "inferred": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredEpistemicEntry" } }, "simulated": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredEpistemicEntry" } }, "missing": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredEpistemicEntry" } }, "unresolved": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredEpistemicEntry" } } }, "additionalProperties": false }, "StructuredHypothesis": { "type": "object", "required": [ "statement" ], "properties": { "id": { "type": "string" }, "statement": { "type": "string" }, "role": { "type": "string", "enum": [ "primary", "rival" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "supportRefs": { "type": "array", "items": { "type": "string" } }, "contradictionRefs": { "type": "array", "items": { "type": "string" } }, "discriminatingTest": { "type": "string" } }, "additionalProperties": true }, "StructuredRisk": { "type": "object", "required": [ "statement" ], "properties": { "id": { "type": "string" }, "statement": { "type": "string" }, "likelihood": { "type": "number", "minimum": 0, "maximum": 1 }, "impact": { "type": "number", "minimum": 0, "maximum": 1 }, "basis": { "type": "string" }, "refs": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "StructuredMeasurementBundle": { "type": "object", "description": "Sanitized material measurements. Use the explicit common fields when applicable and custom only for additional bounded measurements.", "properties": { "summary": { "type": "string" }, "sheetCount": { "type": "integer", "minimum": 0 }, "rowCount": { "type": "integer", "minimum": 0 }, "analyzableRowCount": { "type": "integer", "minimum": 0 }, "malformedRows": { "type": "integer", "minimum": 0 }, "headers": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "string" } }, "timeCoverage": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "basis": { "type": "string" } }, "additionalProperties": true }, "missingness": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "missing": { "type": "integer", "minimum": 0 }, "share": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": true } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "value": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "share": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": true } }, "temporalConsistency": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "leftColumn": { "type": "string" }, "rightColumn": { "type": "string" }, "comparableRows": { "type": "integer", "minimum": 0 }, "violations": { "type": "integer", "minimum": 0 }, "violationShare": { "type": "number", "minimum": 0, "maximum": 1 }, "interpretation": { "type": "string" } }, "additionalProperties": true } }, "durations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "startColumn": { "type": "string" }, "endColumn": { "type": "string" }, "comparableRows": { "type": "integer", "minimum": 0 }, "negativeRows": { "type": "integer", "minimum": 0 }, "medianHours": { "type": "number" }, "p90Hours": { "type": "number" }, "meanHours": { "type": "number" }, "maxHours": { "type": "number" } }, "additionalProperties": true } }, "recurrence": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer", "minimum": 0 }, "share": { "type": "number", "minimum": 0, "maximum": 1 }, "basis": { "type": "string" } }, "additionalProperties": true } }, "measurementLimitations": { "type": "array", "items": { "type": "string" } }, "custom": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "StructuredPerturbation": { "type": "object", "properties": { "action": { "type": "string" }, "rationale": { "type": "string" }, "reversibility": { "type": "string" }, "riskLevel": { "type": "string" }, "expectedEffect": { "type": "string" }, "constraints": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "StructuredPrediction": { "type": "object", "properties": { "statement": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "expectedSignals": { "type": "array", "items": { "type": "string" } }, "contradictionSignals": { "type": "array", "items": { "type": "string" } }, "observationWindow": { "type": "string" } }, "additionalProperties": true }, "StructuredAnalysisResult": { "type": "object", "required": [ "measurements", "epistemicPartition" ], "description": "Sanitized structured analysis returned by an authorized extractor. This is a DERIVED result, not ACCEPTED EVIDENCE or canonical truth.", "properties": { "summary": { "type": "string" }, "measurements": { "$ref": "#/components/schemas/StructuredMeasurementBundle" }, "epistemicPartition": { "$ref": "#/components/schemas/StructuredEpistemicPartition" }, "hypotheses": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredHypothesis" } }, "rivals": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredHypothesis" } }, "risks": { "type": "array", "items": { "$ref": "#/components/schemas/StructuredRisk" } }, "invariants": { "type": "array", "items": { "type": "string" } }, "perturbation": { "$ref": "#/components/schemas/StructuredPerturbation" }, "prediction": { "$ref": "#/components/schemas/StructuredPrediction" }, "unresolved": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "StructuredResultAnalyzer": { "type": "object", "properties": { "name": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "method": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": true } }, "securitySchemes": { "sfiOAuth": { "type": "oauth2", "description": "User-bound SFI identity for GPT Actions. Institutional accounts may receive explicit institutional scopes; normal accounts are reduced to owner-scoped personal workspace capabilities.", "flows": { "authorizationCode": { "authorizationUrl": "https://systemfriction.org/api/oauth/authorize", "tokenUrl": "https://systemfriction.org/api/oauth/token", "scopes": { "observe": "Read governed institutional SFI state when the authenticated principal is allowed.", "propose": "Submit governed institutional proposals and evidence candidates for ROOT review.", "execute": "Execute only already-authorized queued institutional proposals and record proposal-scoped returns.", "lab:read": "Read Method Lab or personal Cognitive/Lab state permitted to the OAuth tenant.", "lab:write": "Persist permitted structured or owner-scoped personal Lab records.", "lab:run": "Run supported Method Lab or owner-scoped personal Cognitive/Lab runtimes.", "studio:read": "List, inspect and read features for Studio objects owned by the OAuth principal.", "studio:content": "Obtain a short-lived signed URL for Studio content owned by the OAuth principal.", "studio:run": "Run the server-side Studio analyzer for owned audio/video objects.", "cases:read": "Read SFI cases available to the authenticated subject through active tenant membership.", "cases:write": "Create and populate bounded SFI Case Platform records through authenticated tenant membership." } } } } } }, "x-sfi-governance": { "principle": "Observation, inference, evidence candidacy, evidence acceptance, proposal authorization, execution, return and canonical promotion remain distinct states.", "defaultObjectStorage": "REFERENCE_ONLY", "rawObjectPersistence": false, "identityRule": "Content fingerprint and reference-envelope hash are distinct. Never compare a referenceHash as if it were the bytes/content hash.", "personalWorkspaceBoundary": "Normal OAuth accounts are tenant user:. Personal Cognitive, Personal Lab and Studio operations are owner-scoped and cannot access institutional proposal, execution, ROOT evidence or canonical promotion planes.", "studioOwnerBoundary": "OAuth subject_id must equal studio_objects.owner_id; shared/static tokens are rejected from the external Studio route.", "preferredObjectFlow": [ "cognitive-bootstrap", "case-intake-resolution", "execution-contract or governed ingestion", "material-observation hydration", "sufficiency gate", "evidence requirement resolution", "bounded public source acquisition when required", "minimum relevant cognitive runtime", "bounded AI synthesis", "return", "contrast/calibration", "methodological closure", "learning quarantine", "ROOT learning promotion when eligible" ], "evidenceCandidateFlow": [ "request_evidence", "search/manual/external candidate", "ROOT accept/reject", "canonical evidence writer" ], "publicAuthentication": "OAuth only; static X-SFI-Token remains an internal server-to-server mechanism and is intentionally not advertised in this OpenAPI document.", "rootReserved": [ "evidence candidate acceptance", "approval", "canonical promotion", "unguarded external action", "preserve-evidence exception" ], "privacyPolicy": "https://systemfriction.org/privacy", "console": "/api/external/v1/console", "discovery": [ "/llms.txt", "/llms-full.txt", "/ai-index.json", "/field-schema.json", "/privacy", "/api/external/v1/manifest" ], "caseWorkspaceBoundary": "Case Platform access is subject-bound and tenant-scoped. intake_plan creates no case. cases:write can create SOURCE/RECORD/INFERENCE/EPISTEMIC_ASSESSMENT objects only within the adapter allowlist; it cannot mint accepted EVIDENCE, GOVERNANCE_DECISION, INTERVENTION, RETURN or TRUTH_CLAIM authority.", "universalCycleBoundary": "SOURCE/OBSERVATION/DERIVATION/INFERENCE/SIMULATION/RETURN/CONTRAST/CLOSURE remain distinct. Same-cycle rerun preserves prior history. AI synthesis is inference only. Closure completeness does not canonize truth.", "learningQuarantineBoundary": "SFI_STRUCTURED_ANALYSIS_RESULT_RECEIVED and closed cycles do not directly enter the Cognitive Spine. TEST_SYNTHETIC, FAILED_EXPERIMENT and unpromoted OPERATIONAL_EVIDENCE remain outside institutional learning. Only ROOT-governed SFI_UNIVERSAL_LEARNING_PROMOTED records derived from CALIBRATED_RETURN may enter the universal-cycle learning source plane.", "cognitiveBootstrapBoundary": "Bootstrap exposes a sealed bounded institutional context for an authorized session. It does not mint evidence, authorize actions, inherit PERSON_CT into institutional state, or promote learning.", "structuredResultActionBoundary": "The structured-result Action schema must expose the backend-required object + result payload, including measurements and epistemic partition. Tool-schema truncation is a blocking contract failure, not permission to degrade the payload into lineage or metadata.", "personCtPatternBoundary": "COGNITION and OBSERVATION patterns are private owner-scoped representations. Agent prose does not auto-create a pattern. Inferred candidates require recurrent owned support and person confirmation; self-declarations remain DECLARED. No PERSON_CT pattern enters institutional Cognitive Spine by inheritance." } }