{
  "openapi": "3.1.0",
  "info": {
    "title": "Q.Mind Developer API",
    "version": "1.0.0",
    "description": "Use Q.Mind's canonical Asimov marketing intelligence runtime from server-side applications. Responses are account-scoped, asynchronous, and integrity-verifiable."
  },
  "servers": [
    {
      "url": "https://qmind.qdt.ai/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    { "name": "Responses" },
    { "name": "Artifacts" },
    { "name": "Discovery" }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Inspect the API",
        "operationId": "getApi",
        "responses": {
          "200": {
            "description": "API metadata",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMetadata" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/models": {
      "get": {
        "tags": ["Discovery"],
        "summary": "List available models",
        "operationId": "listModels",
        "responses": {
          "200": { "description": "Model list" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/capabilities": {
      "get": {
        "tags": ["Discovery"],
        "summary": "List Q.Mind capabilities",
        "operationId": "listCapabilities",
        "responses": {
          "200": { "description": "Capability list" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/responses": {
      "post": {
        "tags": ["Responses"],
        "summary": "Create a Q.Mind response",
        "description": "Queues a canonical Q.Mind turn. Reuse conversation_id for follow-ups. Set processing_mode to analysis for deterministic governed analysis, or leave it as auto for intent-based routing.",
        "operationId": "createResponse",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "A unique 1–200 character key that makes retries safe.",
            "schema": { "type": "string", "maxLength": 200 }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateResponseRequest" },
              "examples": {
                "counsel": {
                  "value": {
                    "input": "For Tide, should the next growth plan prioritize penetration, premiumization, or loyalty? Explain the decision rule.",
                    "capability": "cmo-counsel"
                  }
                },
                "analysis": {
                  "value": {
                    "input": "Diagnose the growth constraints for Northstar Laundry and create a PDF report.",
                    "capability": "growth-diagnosis",
                    "processing_mode": "analysis"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Response accepted",
            "headers": {
              "Location": { "schema": { "type": "string" }, "description": "Polling URL" },
              "X-Request-Id": { "schema": { "type": "string" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "413": { "$ref": "#/components/responses/PayloadTooLarge" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/responses/{response_id}": {
      "get": {
        "tags": ["Responses"],
        "summary": "Retrieve a response",
        "operationId": "getResponse",
        "parameters": [
          { "$ref": "#/components/parameters/ResponseId" }
        ],
        "responses": {
          "200": {
            "description": "Current response state",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/responses/{response_id}/cancel": {
      "post": {
        "tags": ["Responses"],
        "summary": "Cancel a queued or running response",
        "operationId": "cancelResponse",
        "parameters": [
          { "$ref": "#/components/parameters/ResponseId" }
        ],
        "responses": {
          "200": {
            "description": "Cancelled response",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/artifacts/{artifact_id}/content": {
      "get": {
        "tags": ["Artifacts"],
        "summary": "Download a response artifact",
        "operationId": "downloadArtifact",
        "parameters": [
          {
            "name": "artifact_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Artifact bytes",
            "content": {
              "application/pdf": { "schema": { "type": "string", "contentEncoding": "binary" } },
              "application/vnd.openxmlformats-officedocument.presentationml.presentation": { "schema": { "type": "string", "contentEncoding": "binary" } },
              "application/octet-stream": { "schema": { "type": "string", "contentEncoding": "binary" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "qmind_live_*",
        "description": "Create a key in Q.Mind → Account → Developer API. Keep it on your server."
      }
    },
    "parameters": {
      "ResponseId": {
        "name": "response_id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "schemas": {
      "ApiMetadata": {
        "type": "object",
        "required": ["object", "version", "model", "contract"],
        "properties": {
          "object": { "const": "qmind.api" },
          "version": { "const": "v1" },
          "build": { "type": ["object", "null"] },
          "model": { "const": "qmind-asimov" },
          "contract": { "type": "string" },
          "contract_version": { "type": "string" },
          "links": { "type": "object" }
        }
      },
      "CreateResponseRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["input"],
        "properties": {
          "input": { "type": "string", "minLength": 1, "maxLength": 12000 },
          "project_id": { "type": "string", "format": "uuid" },
          "conversation_id": { "type": "string", "format": "uuid" },
          "processing_mode": {
            "type": "string",
            "default": "auto",
            "enum": ["auto", "conversation", "analysis"],
            "description": "Select deterministic conversational or governed analysis processing, or use automatic intent routing."
          },
          "capability": {
            "type": "string",
            "default": "cmo-counsel",
            "enum": ["cmo-counsel", "growth-diagnosis", "market-intelligence", "strategy-portfolio", "creative-activation", "decision-pressure-test", "artifact-studio", "meeting-prep"]
          }
        }
      },
      "Response": {
        "type": "object",
        "required": ["id", "object", "status", "model", "output", "artifacts", "metadata", "links"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "object": { "const": "qmind.response" },
          "status": { "type": "string", "enum": ["queued", "running", "completed", "failed", "blocked", "cancelled"] },
          "model": { "const": "qmind-asimov" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": ["string", "null"], "format": "date-time" },
          "project_id": { "type": ["string", "null"], "format": "uuid" },
          "conversation_id": { "type": ["string", "null"], "format": "uuid" },
          "capability": { "type": "string" },
          "progress": {
            "anyOf": [{ "$ref": "#/components/schemas/Progress" }, { "type": "null" }]
          },
          "output": { "type": "array", "items": { "$ref": "#/components/schemas/OutputMessage" } },
          "output_text": { "type": ["string", "null"] },
          "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } },
          "error": { "anyOf": [{ "$ref": "#/components/schemas/ErrorDetail" }, { "type": "null" }] },
          "metadata": {
            "type": "object",
            "properties": {
              "engine": { "type": ["string", "null"] },
              "canonical": { "type": ["boolean", "null"] },
              "canonical_provider": { "type": ["string", "null"] },
              "canonical_answer_sha256": { "type": ["string", "null"] },
              "canonical_integrity_verified": { "type": ["boolean", "null"] },
              "request_id": { "type": ["string", "null"] }
            }
          },
          "links": {
            "type": "object",
            "properties": {
              "self": { "type": "string" },
              "cancel": { "type": "string" }
            }
          }
        }
      },
      "OutputMessage": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "type": { "const": "message" },
          "role": { "const": "assistant" },
          "content": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": { "const": "output_text" },
                "text": { "type": "string" }
              }
            }
          }
        }
      },
      "Progress": {
        "type": "object",
        "required": ["stage", "label", "detail", "startedAt", "updatedAt"],
        "properties": {
          "stage": { "type": "string", "description": "Machine-readable workflow stage; clients must accept new values." },
          "label": { "type": "string", "description": "Short human-readable stage label." },
          "detail": { "type": "string", "description": "Current work detail suitable for status UI." },
          "brand": { "type": ["string", "null"] },
          "current": { "type": ["integer", "null"], "minimum": 0 },
          "total": { "type": ["integer", "null"], "minimum": 0 },
          "startedAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Artifact": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "object": { "const": "qmind.artifact" },
          "type": { "type": "string" },
          "title": { "type": "string" },
          "filename": { "type": ["string", "null"] },
          "content_type": { "type": ["string", "null"] },
          "bytes": { "type": ["integer", "null"] },
          "download_url": { "type": ["string", "null"] }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "properties": {
          "type": { "type": "string" },
          "code": { "type": "string" },
          "message": { "type": "string" },
          "param": { "type": ["string", "null"] }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["error"],
        "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "Conflict": {
        "description": "Resource state conflict",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": { "Retry-After": { "schema": { "type": "integer" } } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      },
      "PayloadTooLarge": {
        "description": "JSON body exceeds 1 MB",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }
      }
    }
  }
}