{
  "openapi": "3.1.0",
  "info": {
    "title": "DocGovernance API",
    "version": "0.1.0",
    "summary": "Evidence and action-provenance infrastructure for software and AI",
    "description": "Register artifacts, record material events, and issue portable evidence packages that can be independently verified."
  },
  "servers": [
    { "url": "https://docgovernance.com", "description": "Production" },
    { "url": "http://localhost:8080", "description": "Local development" }
  ],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/auth/signup": {
      "post": {
        "summary": "Create a browser user account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AuthRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Signed up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } },
          "400": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/auth/login": {
      "post": {
        "summary": "Create a browser session",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AuthRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Logged in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } },
          "401": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/account/current": {
      "get": {
        "summary": "Get the current identity, workspace, and product access context",
        "description": "Returns the authenticated user's central DocGovernance identity context and product entitlements. Inactive products are listed as inactive and must not be opened or used for delegated agent tokens.",
        "responses": {
          "200": { "description": "Current account context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountContextResponse" } } } },
          "401": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/entitlements": {
      "get": {
        "summary": "List product entitlements for the current organization",
        "responses": {
          "200": { "description": "Product entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEntitlementListResponse" } } } },
          "401": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/products/{product_id}/access": {
      "get": {
        "summary": "Check access to one connected product",
        "parameters": [
          { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "enum": ["docgovernance", "pdfrealm", "deletepii", "carrierlockbox", "brokerlockbox"] } }
        ],
        "responses": {
          "200": { "description": "Product access granted" },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/account-links": {
      "post": {
        "summary": "Link a reauthenticated legacy product account",
        "description": "Links an existing product account to the central DocGovernance identity only after the product-specific account has been reauthenticated. Matching email addresses are not sufficient.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ExternalAccountLinkRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Account linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountLinkResponse" } } } },
          "401": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/workflow-demos/carrier-packet": {
      "get": {
        "summary": "Get the synthetic carrier-packet workflow demonstration",
        "description": "Returns a synthetic demonstration workflow with participating products, permissions, approval states, artifact references, digests, and a demo workflow receipt.",
        "security": [],
        "responses": {
          "200": { "description": "Workflow demo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunResponse" } } } }
        }
      }
    },
    "/v1/workflows": {
      "get": {
        "summary": "List workflow runs for the current organization",
        "responses": {
          "200": { "description": "Workflow runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunListResponse" } } } },
          "401": { "$ref": "#/components/responses/Problem" }
        }
      },
      "post": {
        "summary": "Start an implemented workflow template",
        "description": "Starts the carrier-packet demonstration workflow for the authenticated organization. Other workflow templates are rejected until implemented.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WorkflowCreateRequest" },
              "examples": { "carrierPacket": { "value": { "template_id": "carrier_packet" } } }
            }
          }
        },
        "responses": {
          "201": { "description": "Workflow started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunResponse" } } } },
          "401": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/workflows/{workflow_run_id}": {
      "get": {
        "summary": "Get one workflow run",
        "parameters": [
          { "name": "workflow_run_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Workflow run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunResponse" } } } },
          "401": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/artifacts": {
      "post": {
        "summary": "Register a hash-only artifact version",
        "description": "Registers an artifact digest without uploading the original file. Requires Idempotency-Key.",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } },
          { "name": "X-Request-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ArtifactRegisterRequest" },
              "examples": {
                "hashOnly": {
                  "value": {
                    "external_id": "contract-10492",
                    "name": "Master Services Agreement",
                    "custody_mode": "hash_only",
                    "version": {
                      "digest": { "algorithm": "sha-256", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" },
                      "media_type": "application/pdf",
                      "size_bytes": 428912
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Artifact registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactRegisterResponse" } } } },
          "400": { "$ref": "#/components/responses/Problem" },
          "401": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "422": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/evidence/events": {
      "post": {
        "summary": "Append an evidence event to an artifact ledger",
        "responses": {
          "200": { "description": "Event appended" },
          "401": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/evidence/bundles": {
      "post": {
        "summary": "Create an evidence bundle for an artifact",
        "responses": {
          "200": { "description": "Bundle created" },
          "401": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/evidence/bundles/{bundleId}/download": {
      "get": {
        "summary": "Download an evidence bundle",
        "parameters": [{ "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Bundle bytes" },
          "401": { "$ref": "#/components/responses/Problem" },
          "404": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/evidence/verify-bundle": {
      "post": {
        "summary": "Verify an uploaded evidence bundle",
        "responses": {
          "200": { "description": "Verification result" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" }
    },
    "responses": {
      "Problem": {
        "description": "Problem details error",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/Problem" }
          }
        }
      }
    },
    "schemas": {
      "AuthRequest": {
        "type": "object",
        "required": ["email", "password"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "password": { "type": "string", "minLength": 8 }
        }
      },
      "AuthResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "user": { "type": "object" },
          "account": { "$ref": "#/components/schemas/AccountBootstrap" }
        }
      },
      "AccountBootstrap": {
        "type": "object",
        "properties": {
          "global_user": { "$ref": "#/components/schemas/GlobalUser" },
          "workspace": { "$ref": "#/components/schemas/Workspace" },
          "entitlement": { "type": "object" },
          "account_link": { "type": "object" }
        }
      },
      "AccountContextResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": {
            "type": "object",
            "required": ["global_user", "organization", "workspace", "products"],
            "properties": {
              "global_user": { "$ref": "#/components/schemas/GlobalUser" },
              "organization": {
                "type": "object",
                "required": ["id"],
                "properties": { "id": { "type": "string" } }
              },
              "workspace": { "$ref": "#/components/schemas/Workspace" },
              "products": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ProductEntitlementView" }
              }
            }
          }
        }
      },
      "GlobalUser": {
        "type": "object",
        "required": ["id", "primary_user_id", "email", "status"],
        "properties": {
          "id": { "type": "string" },
          "primary_user_id": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "display_name": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "suspended", "deleted"] },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Workspace": {
        "type": "object",
        "required": ["id", "organization_id", "name", "slug", "status"],
        "properties": {
          "id": { "type": "string" },
          "organization_id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "suspended", "deleted"] },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "ProductEntitlementView": {
        "type": "object",
        "required": ["id", "name", "role", "status"],
        "properties": {
          "id": { "type": "string", "enum": ["docgovernance", "pdfrealm", "deletepii", "carrierlockbox", "brokerlockbox"] },
          "name": { "type": "string" },
          "role": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "inactive"] },
          "plan": { "type": ["string", "null"] },
          "app_url": { "type": ["string", "null"] },
          "add_url": { "type": ["string", "null"] }
        }
      },
      "ProductEntitlementListResponse": {
        "type": "object",
        "required": ["data", "page"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductEntitlementView" } },
          "page": { "$ref": "#/components/schemas/Page" }
        }
      },
      "ExternalAccountLinkRequest": {
        "type": "object",
        "required": ["product", "legacy_user_id", "verification_method"],
        "additionalProperties": false,
        "properties": {
          "product": { "type": "string", "enum": ["pdfrealm", "deletepii", "carrierlockbox", "brokerlockbox"] },
          "legacy_user_id": { "type": "string", "minLength": 1, "maxLength": 200 },
          "verification_method": { "type": "string", "minLength": 1, "maxLength": 200 }
        }
      },
      "ExternalAccountLinkResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": {
            "type": "object",
            "required": ["id", "product", "global_user_id", "organization_id", "verification_method", "linked_at"],
            "properties": {
              "id": { "type": "string" },
              "product": { "type": "string" },
              "global_user_id": { "type": "string" },
              "organization_id": { "type": "string" },
              "verification_method": { "type": "string" },
              "linked_at": { "type": "string", "format": "date-time" },
              "migrated_at": { "type": ["string", "null"], "format": "date-time" },
              "legacy_credential_disabled_at": { "type": ["string", "null"], "format": "date-time" }
            }
          }
        }
      },
      "Page": {
        "type": "object",
        "required": ["next_cursor", "has_more"],
        "properties": {
          "next_cursor": { "type": ["string", "null"] },
          "has_more": { "type": "boolean" }
        }
      },
      "WorkflowCreateRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "template_id": { "type": "string", "enum": ["carrier_packet"], "default": "carrier_packet" }
        }
      },
      "WorkflowStep": {
        "type": "object",
        "required": ["id", "sequence", "product", "operation", "actor", "permission", "input_artifact", "output_artifact", "approval_status", "receipt_status", "input_digest", "output_digest"],
        "properties": {
          "id": { "type": "string" },
          "workflow_run_id": { "type": "string" },
          "agent_run_id": { "type": "string" },
          "sequence": { "type": "integer" },
          "product": { "type": "string" },
          "operation": { "type": "string" },
          "actor": { "type": "string" },
          "permission": { "type": "string" },
          "input_artifact": { "type": "string" },
          "output_artifact": { "type": "string" },
          "approval_status": { "type": "string" },
          "receipt_status": { "type": "string" },
          "input_digest": { "type": "string" },
          "output_digest": { "type": "string" },
          "recorded_at": { "type": "string", "format": "date-time" },
          "status": { "type": "string" }
        }
      },
      "WorkflowReceipt": {
        "type": "object",
        "required": ["receipt_id", "receipt_version", "environment", "workflow_run_id", "issued_at", "participating_products", "material_actions", "receipt_digest"],
        "properties": {
          "receipt_id": { "type": "string" },
          "receipt_version": { "type": "string" },
          "environment": { "type": "string" },
          "workflow_run_id": { "type": "string" },
          "organization_id": { "type": "string" },
          "workspace_id": { "type": "string" },
          "template_id": { "type": "string" },
          "issued_at": { "type": "string", "format": "date-time" },
          "participating_products": { "type": "array", "items": { "type": "string" } },
          "material_actions": { "type": "array", "items": { "type": "object" } },
          "receipt_digest": { "type": "string" }
        }
      },
      "WorkflowRun": {
        "type": "object",
        "required": ["id", "template_id", "name", "status", "organization_id", "workspace_id", "steps", "receipt"],
        "properties": {
          "id": { "type": "string" },
          "template_id": { "type": "string" },
          "name": { "type": "string" },
          "status": { "type": "string" },
          "organization_id": { "type": "string" },
          "workspace_id": { "type": "string" },
          "requested_by": { "type": "string" },
          "agent_run_id": { "type": "string" },
          "started_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": ["string", "null"], "format": "date-time" },
          "north_star_metric": { "type": "string" },
          "steps": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStep" } },
          "receipt": { "$ref": "#/components/schemas/WorkflowReceipt" }
        }
      },
      "WorkflowRunResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": { "$ref": "#/components/schemas/WorkflowRun" }
        }
      },
      "WorkflowRunListResponse": {
        "type": "object",
        "required": ["data", "page"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRun" } },
          "page": { "$ref": "#/components/schemas/Page" }
        }
      },
      "ArtifactRegisterRequest": {
        "type": "object",
        "required": ["external_id", "name", "custody_mode", "version"],
        "additionalProperties": false,
        "properties": {
          "external_id": { "type": "string", "minLength": 1, "maxLength": 200 },
          "name": { "type": "string", "minLength": 1, "maxLength": 300 },
          "description": { "type": "string", "maxLength": 2000 },
          "artifact_type": { "type": "string", "maxLength": 100 },
          "classification": { "type": "string", "maxLength": 100 },
          "custody_mode": { "const": "hash_only" },
          "metadata": { "type": "object", "additionalProperties": true },
          "version": {
            "type": "object",
            "required": ["digest", "media_type", "size_bytes"],
            "properties": {
              "digest": {
                "type": "object",
                "required": ["algorithm", "value"],
                "properties": {
                  "algorithm": { "const": "sha-256" },
                  "value": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
                }
              },
              "media_type": { "type": "string", "maxLength": 255 },
              "size_bytes": { "type": "integer", "minimum": 0 }
            }
          }
        }
      },
      "ArtifactRegisterResponse": {
        "type": "object",
        "required": ["data", "included"],
        "properties": {
          "data": { "type": "object" },
          "included": { "type": "object" }
        }
      },
      "Problem": {
        "type": "object",
        "required": ["type", "title", "status", "detail", "instance", "code", "request_id"],
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "detail": { "type": "string" },
          "instance": { "type": "string" },
          "code": { "type": "string" },
          "request_id": { "type": "string" },
          "field_errors": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  }
}