{
  "openapi": "3.1.0",
  "info": {
    "title": "HARBINGER Private Preview API",
    "version": "2026-08-27.preview",
    "description": "Reference contract for a future approval-only, organization-isolated, purpose-bound customer READ_ONLY API. The separate public synthetic demo endpoint serves precomputed fixed examples at /api/demo/v3/golden-thread and is described by /openapi-demo.json. No customer operational endpoint, Customer Sandbox, or credential is provided through this contract."
  },
  "x-harbinger-availability": "REFERENCE_IMPLEMENTATION",
  "x-harbinger-operational-endpoint": false,
  "x-harbinger-public-demo-runtime": "RUNNING_AT_/api/demo/v3/golden-thread",
  "x-harbinger-public-demo-openapi": "/openapi-demo.json",
  "x-harbinger-deployment-package": "CUSTOMER_INFRASTRUCTURE_CANDIDATE_NOT_DEPLOYED_UNSIGNED",
  "externalDocs": {
    "description": "Availability, lifecycle, and authority boundary",
    "url": "https://developer.calamophyton.com/docs/api/overview"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/subjects/{subjectId}": {
      "get": {
        "operationId": "getSubject",
        "summary": "Read an approved subject and its relationship candidates",
        "parameters": [
          {
            "$ref": "#/components/parameters/SubjectId"
          },
          {
            "$ref": "#/components/parameters/DataPurpose"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SubjectResponse"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    },
    "/v1/subjects/{subjectId}/{view}": {
      "get": {
        "operationId": "getSubjectView",
        "summary": "Read an approved observation, change, evidence, or gap view",
        "parameters": [
          {
            "$ref": "#/components/parameters/SubjectId"
          },
          {
            "$ref": "#/components/parameters/View"
          },
          {
            "$ref": "#/components/parameters/DataPurpose"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/CollectionResponse"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Short-lived access token issued separately inside an approved organization environment."
      }
    },
    "parameters": {
      "SubjectId": {
        "name": "subjectId",
        "in": "path",
        "required": true,
        "description": "A subject inside the approved organization and data scope. The synthetic supply-chain subject is a structure fixture, not a real organization.",
        "schema": {
          "type": "string",
          "enum": [
            "example-insurance",
            "synthetic-industrial-supply-chain"
          ]
        }
      },
      "View": {
        "name": "view",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "observations",
            "changes",
            "evidence",
            "gaps"
          ]
        }
      },
      "DataPurpose": {
        "name": "Harbinger-Data-Purpose",
        "in": "header",
        "required": true,
        "description": "The approved processing purpose bound to both the organization and subject domain.",
        "schema": {
          "type": "string",
          "enum": [
            "DUE_DILIGENCE_EVALUATION",
            "SUPPLY_CHAIN_EARLY_WARNING_EVALUATION"
          ]
        }
      }
    },
    "schemas": {
      "Authority": {
        "type": "object",
        "required": [
          "fact",
          "decision",
          "execution"
        ],
        "properties": {
          "fact": {
            "const": "NONE"
          },
          "decision": {
            "const": "NONE"
          },
          "execution": {
            "const": "NONE"
          }
        },
        "additionalProperties": false
      },
      "Envelope": {
        "type": "object",
        "required": [
          "contract",
          "requestId",
          "organizationId",
          "purpose",
          "datasetDigest",
          "datasetAsOf",
          "candidateOnly",
          "authority",
          "data"
        ],
        "properties": {
          "contract": {
            "const": "harbinger.private_preview.response.v1"
          },
          "requestId": {
            "type": "string"
          },
          "organizationId": {
            "type": "string"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "DUE_DILIGENCE_EVALUATION",
              "SUPPLY_CHAIN_EARLY_WARNING_EVALUATION"
            ]
          },
          "datasetDigest": {
            "type": "string"
          },
          "datasetAsOf": {
            "type": "string",
            "format": "date-time"
          },
          "candidateOnly": {
            "const": true
          },
          "authority": {
            "$ref": "#/components/schemas/Authority"
          }
        }
      },
      "SubjectData": {
        "type": "object",
        "required": [
          "subject",
          "relationships"
        ],
        "properties": {
          "subject": {
            "type": "object",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "relationships": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "additionalProperties": false
      },
      "CollectionData": {
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1,
        "properties": {
          "observations": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "changes": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "gaps": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "requestId"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "responses": {
      "SubjectResponse": {
        "description": "Bounded subject candidate view",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Envelope"
                },
                {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SubjectData"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "CollectionResponse": {
        "description": "Bounded candidate collection",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Envelope"
                },
                {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CollectionData"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "BadRequest": {
        "description": "Missing or malformed purpose or request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid credential",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Organization, user, purpose, capability, or data scope is not approved",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Subject, view, or unsupported authority-bearing route does not exist",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Only the documented READ_ONLY method is permitted",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "x-harbinger-document-origin": "CONFIGURED_FOR_BUILD",
  "x-harbinger-server-issuance": "NO_SERVER_URL_PUBLISHED · ISSUED SEPARATELY ONLY AFTER ENVIRONMENT APPROVAL"
}