{
  "openapi": "3.0.3",
  "info": {
    "title": "CARE Machine API",
    "version": "1.0.0",
    "description": "Bearer-authenticated machine APIs for agent definition ingestion, assessment catalog packs (same JSON as the website runner), and assessment export CRUD.\n\n**Authentication:** `Authorization: Bearer <token>` and/or `X-CARE-Ingestion-Token: <token>` (agent-scoped tokens for definition GET, assessment catalog, and assessment export routes).\n\n**Definition POST** stages a pending import until Accept/Discard in CARE.\n**Assessment POST** follows tenant merge policy (defaults: empty export auto-merges; merges onto existing exports stage with `pending_review: true` until Accept on `/agent-assessment`). Omit = leave; JSON `null` = can’t-answer; booleans overwrite.\n**Assessment catalog** exposes description/evaluation/assessment pack JSON for external assessors."
  },
  "servers": [
    {
      "url": "/",
      "description": "Same origin as this CARE deployment"
    }
  ],
  "tags": [
    {
      "name": "Ingestion – definition",
      "description": "Import schema, staged agent import, and Agent Builder instruction export"
    },
    {
      "name": "Ingestion – assessment catalog",
      "description": "List/get runner pack JSON (description, evaluation, assessment) — same as the website"
    },
    {
      "name": "Ingestion – assessments",
      "description": "List/get/merge/delete agent assessment exports (canonical)"
    }
  ],
  "components": {
    "securitySchemes": {
      "IngestionBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "CARE ingestion token",
        "description": "Agent, user, or company ingestion secret from API Integration → API Key (assessment routes require agent token)."
      },
      "IngestionHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CARE-Ingestion-Token",
        "description": "Same secret as Bearer when Authorization cannot reach PHP."
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "enum": [false] },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "details": {}
            }
          }
        }
      },
      "AssessmentPayload": {
        "type": "object",
        "required": ["meta"],
        "properties": {
          "meta": {
            "type": "object",
            "required": ["assessment_id"],
            "properties": {
              "assessment_id": {
                "type": "string",
                "description": "Must equal the path `{assessment_key}`."
              }
            },
            "additionalProperties": true
          },
          "state": {
            "type": "object",
            "additionalProperties": true,
            "description": "Checklist answers. On POST merge: omitted keys unchanged; JSON null = can’t-answer; true/false overwrite."
          },
          "results": {
            "description": "If present on POST, replaces previous results; if omitted, previous results are kept.",
            "nullable": true
          },
          "field_updated_at": {
            "type": "object",
            "additionalProperties": { "type": "string" },
            "description": "Server-owned; ignored if sent by the client."
          }
        }
      },
      "AssessmentWriteBody": {
        "type": "object",
        "required": ["payload"],
        "properties": {
          "payload": { "$ref": "#/components/schemas/AssessmentPayload" }
        }
      }
    }
  },
  "security": [
    { "IngestionBearer": [] },
    { "IngestionHeader": [] }
  ],
  "paths": {
    "/api/v1/ingestion/schema": {
      "get": {
        "tags": ["Ingestion – definition"],
        "summary": "Import JSON Schema",
        "description": "Returns `schema_id` (`care-agent-import-v1`) and JSON Schema for the definition POST body.",
        "operationId": "getIngestionSchema",
        "responses": {
          "200": {
            "description": "Schema document",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/api/v1/ingestion/agent/report": {
      "get": {
        "tags": ["Ingestion – definition"],
        "summary": "Download CARE Agent Report PDF",
        "description": "Agent token only. Returns a dated, CARE-branded A4 PDF snapshot (identity, role, process, SOP, Clearances, Improvements). Same content as MCP care_download_agent_report. Not part of complete registration.",
        "operationId": "getIngestionAgentReport",
        "responses": {
          "200": {
            "description": "Agent Report PDF",
            "content": {
              "application/pdf": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "403": {
            "description": "Non-agent token",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          },
          "503": {
            "description": "PDF sidecar unavailable",
            "content": {
              "text/plain": { "schema": { "type": "string" } }
            }
          }
        }
      }
    },
    "/api/v1/ingestion/agent": {
      "get": {
        "tags": ["Ingestion – definition"],
        "summary": "Export Agent Builder instruction or import exchange payload",
        "description": "Agent token only. format=json|markdown: Agent Builder instruction. format=import: care-agent-import-v1 exchange payload including vendor_data.care role/process graphs for round-trip.",
        "operationId": "getIngestionAgentDefinition",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": { "type": "string", "enum": ["json", "markdown", "import"], "default": "json" }
          }
        ],
        "responses": {
          "200": {
            "description": "Instruction document or import exchange payload",
            "content": {
              "application/json": { "schema": { "type": "object", "additionalProperties": true } },
              "text/markdown": { "schema": { "type": "string" } }
            }
          },
          "403": {
            "description": "Non-agent token",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      },
      "post": {
        "tags": ["Ingestion – definition"],
        "summary": "Stage agent definition import",
        "description": "Validates and stages pending import (`pending_review: true` for updates). Accept/Discard in CARE Agent Management View.",
        "operationId": "postIngestionAgent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "additionalProperties": true },
              "description": "Shape described by GET /api/v1/ingestion/schema"
            }
          }
        },
        "responses": {
          "200": {
            "description": "Staged or applied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "pending_review": { "type": "boolean" },
                    "agent_id": { "type": "integer" }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Created (user/company create paths)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "pending_review": { "type": "boolean" },
                    "agent_id": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      }
    },
    "/api/v1/ingestion/assessment-catalog": {
      "get": {
        "tags": ["Ingestion – assessment catalog"],
        "summary": "List assessment packs for token agent plan",
        "description": "Agent token only. Returns the same catalog metadata an assessor needs before answering checklists (titles + fragment names). Optional `lang=en|de|zh`.",
        "operationId": "listIngestionAssessmentCatalog",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["en", "de", "zh"], "default": "en" }
          }
        ],
        "responses": {
          "200": {
            "description": "Pack list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "agent_id": { "type": "integer" },
                    "lang": { "type": "string" },
                    "packs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "assessment_key": { "type": "string" },
                          "has_export": { "type": "boolean" },
                          "title": { "type": "string" },
                          "fragments": {
                            "type": "array",
                            "items": { "type": "string", "enum": ["description", "evaluation", "assessment"] }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Agent token required",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      }
    },
    "/api/v1/ingestion/assessment-catalog/{assessment_key}": {
      "get": {
        "tags": ["Ingestion – assessment catalog"],
        "summary": "Get all pack fragments for one assessment",
        "description": "Returns description, evaluation, and assessment JSON (same files as `/assets/assessment/api/assessments/{id}/…`).",
        "operationId": "getIngestionAssessmentPack",
        "parameters": [
          {
            "name": "assessment_key",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["en", "de", "zh"], "default": "en" }
          }
        ],
        "responses": {
          "200": {
            "description": "All fragments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "assessment_key": { "type": "string" },
                    "lang": { "type": "string" },
                    "fragments": {
                      "type": "object",
                      "properties": {
                        "description": {},
                        "evaluation": {},
                        "assessment": {}
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown assessment key",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          },
          "403": {
            "description": "Agent token required or assessment not in plan",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      }
    },
    "/api/v1/ingestion/assessment-catalog/{assessment_key}/{fragment}": {
      "get": {
        "tags": ["Ingestion – assessment catalog"],
        "summary": "Get one pack fragment",
        "description": "fragment is description | evaluation | assessment.",
        "operationId": "getIngestionAssessmentPackFragment",
        "parameters": [
          {
            "name": "assessment_key",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "fragment",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "enum": ["description", "evaluation", "assessment"] }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["en", "de", "zh"], "default": "en" }
          }
        ],
        "responses": {
          "200": {
            "description": "Single fragment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "assessment_key": { "type": "string" },
                    "lang": { "type": "string" },
                    "fragment": { "type": "string" },
                    "body": {}
                  }
                }
              }
            }
          },
          "404": {
            "description": "Pack file missing",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      }
    },
    "/api/v1/ingestion/assessments": {
      "get": {
        "tags": ["Ingestion – assessments"],
        "summary": "List assessments for token agent",
        "description": "Agent token only. Lists catalog keys allowed by plan with `has_export`.",
        "operationId": "listIngestionAssessments",
        "responses": {
          "200": {
            "description": "Assessment list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "agent_id": { "type": "integer" },
                    "assessments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "assessment_key": { "type": "string" },
                          "has_export": { "type": "boolean" },
                          "updated_at": { "type": "string", "nullable": true }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Agent token required",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      }
    },
    "/api/v1/ingestion/assessments/{assessment_key}": {
      "parameters": [
        {
          "name": "assessment_key",
          "in": "path",
          "required": true,
          "schema": { "type": "string" },
          "description": "Known CARE assessment id (e.g. agentic-usecase-viability)"
        }
      ],
      "get": {
        "tags": ["Ingestion – assessments"],
        "summary": "Get assessment export",
        "operationId": "getIngestionAssessment",
        "responses": {
          "200": {
            "description": "Stored export",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "assessment_key": { "type": "string" },
                    "payload": { "$ref": "#/components/schemas/AssessmentPayload" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No export for known key",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          },
          "400": {
            "description": "Unknown assessment key",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      },
      "post": {
        "tags": ["Ingestion – assessments"],
        "summary": "Merge-upsert assessment export",
        "description": "Follows tenant merge policy (defaults: empty → immediate; existing export → pending until Accept). State merge: omit leave; null = can’t-answer; bool overwrite. Server owns field_updated_at and field audit when applied.",
        "operationId": "postIngestionAssessment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AssessmentWriteBody" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merged or staged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "pending_review": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation / mismatch",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      },
      "put": {
        "tags": ["Ingestion – assessments"],
        "summary": "Merge-upsert assessment export (alias of POST)",
        "operationId": "putIngestionAssessment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AssessmentWriteBody" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "success": { "type": "boolean" } }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Ingestion – assessments"],
        "summary": "Delete assessment export",
        "operationId": "deleteIngestionAssessment",
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "success": { "type": "boolean" } }
                }
              }
            }
          },
          "404": {
            "description": "No export",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }
            }
          }
        }
      }
    }
  }
}