{
  "components": {
    "schemas": {
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "IngestJob": {
        "description": "An email a retriever ingested, which the gateway has parsed and stored.\n\nThe mail-orchestrator queues it for analysis and, when asked, waits for\nthe verdict. ``message_id``, ``sender`` and ``subject`` come from the\nview for its job list, cut at 998 characters; the content stays in the\ndatabase. ``route`` is the route that chose the workflow, None when none\ndid (the default workflow runs); ``mode`` is the job's, its connection's\nand its route's.",
        "properties": {
          "email_id": {
            "format": "uuid",
            "title": "Email Id",
            "type": "string"
          },
          "message_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Message Id"
          },
          "mode": {
            "default": "observe",
            "description": "observe records what would be done, enforce does it; observe when absent",
            "enum": [
              "observe",
              "enforce"
            ],
            "title": "Mode",
            "type": "string"
          },
          "priority": {
            "default": "normal",
            "enum": [
              "low",
              "normal",
              "high"
            ],
            "title": "Priority",
            "type": "string"
          },
          "route": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Route"
          },
          "sender": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sender"
          },
          "subject": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Subject"
          },
          "timeout_ms": {
            "default": 30000,
            "maximum": 300000.0,
            "minimum": 1000.0,
            "title": "Timeout Ms",
            "type": "integer"
          },
          "wait_for_verdict": {
            "default": false,
            "title": "Wait For Verdict",
            "type": "boolean"
          },
          "workflow_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Workflow Id"
          }
        },
        "required": [
          "email_id"
        ],
        "title": "IngestJob",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      }
    },
    "securitySchemes": {
      "MetricsToken": {
        "description": "The metrics token (METRICS_TOKEN)",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Mail orchestrator: accepts emails from retriever plugins, forwarded by the api-gateway to POST /internal/ingest, and dispatches them to the analyzer orchestrator.",
    "title": "SPOT Mail Orchestrator",
    "version": "2.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/capabilities": {
      "get": {
        "operationId": "get_capabilities_capabilities_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "type": "string"
                  },
                  "title": "Response Get Capabilities Capabilities Get",
                  "type": "array"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Get Capabilities",
        "tags": [
          "Health"
        ]
      }
    },
    "/health": {
      "get": {
        "description": "Health check reporting the three downstream dependencies.\n\nThe mail-orchestrator no longer tracks a \"retrievers\" count of\nits own — installed retrievers live in spot.yaml under\n``plugins.mail_retrievers`` and the api-gateway exposes their\nstatus. This endpoint reports only what the orchestrator owns:\nRedis (job store), RabbitMQ (analysis queue), and the\nanalyzer-orchestrator (downstream workflow runner).",
        "operationId": "health_check_health_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Health Check Health Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Health Check",
        "tags": [
          "Health"
        ]
      },
      "head": {
        "description": "Health check reporting the three downstream dependencies.\n\nThe mail-orchestrator no longer tracks a \"retrievers\" count of\nits own — installed retrievers live in spot.yaml under\n``plugins.mail_retrievers`` and the api-gateway exposes their\nstatus. This endpoint reports only what the orchestrator owns:\nRedis (job store), RabbitMQ (analysis queue), and the\nanalyzer-orchestrator (downstream workflow runner).",
        "operationId": "health_check_health_head",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Health Check Health Head",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Health Check",
        "tags": [
          "Health"
        ]
      }
    },
    "/internal/ingest": {
      "post": {
        "description": "Queue one email a retriever ingested, which the api-gateway has stored.\n\nThe api-gateway sets ``X-Retriever-Id`` to the retriever its token\nbelongs to. The value is stored verbatim on the job record; nothing\nelse uses it for routing. An email that cannot be queued, or whose\nanalysis fails, is a 503 or a 502 naming why.",
        "operationId": "ingest_internal_ingest_post",
        "parameters": [
          {
            "in": "header",
            "name": "X-Retriever-Id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Retriever-Id"
            }
          },
          {
            "in": "header",
            "name": "X-Internal-API-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Internal-Api-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestJob"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Ingest Internal Ingest Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Ingest",
        "tags": [
          "Ingestion"
        ]
      }
    },
    "/internal/jobs": {
      "get": {
        "description": "Return the most recent ingestion jobs (newest first).",
        "operationId": "list_recent_jobs_internal_jobs_get",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "header",
            "name": "X-Internal-API-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Internal-Api-Key"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response List Recent Jobs Internal Jobs Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Recent Jobs",
        "tags": [
          "Ingestion"
        ]
      }
    },
    "/internal/jobs/{job_id}": {
      "get": {
        "description": "Look up a single ingestion job by id (transient — TTL applies).",
        "operationId": "get_job_internal_jobs__job_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "X-Internal-API-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Internal-Api-Key"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Get Job Internal Jobs  Job Id  Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Job",
        "tags": [
          "Ingestion"
        ]
      }
    },
    "/internal/metrics": {
      "get": {
        "description": "Return cumulative counters since the service last restarted.",
        "operationId": "get_metrics_internal_metrics_get",
        "parameters": [
          {
            "in": "header",
            "name": "X-Internal-API-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Internal-Api-Key"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "integer"
                  },
                  "title": "Response Get Metrics Internal Metrics Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Metrics",
        "tags": [
          "Ingestion"
        ]
      }
    },
    "/metrics": {
      "get": {
        "operationId": "metrics_metrics_get",
        "responses": {
          "200": {
            "content": {
              "text/plain": {}
            },
            "description": "Prometheus text format"
          },
          "401": {
            "description": "Without the metrics token"
          },
          "503": {
            "description": "Metrics are off: METRICS_TOKEN is not set"
          }
        },
        "security": [
          {
            "MetricsToken": []
          }
        ],
        "summary": "Metrics",
        "tags": [
          "Metrics"
        ]
      }
    },
    "/version": {
      "get": {
        "operationId": "get_version_version_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "title": "Response Get Version Version Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Get Version",
        "tags": [
          "Health"
        ]
      }
    }
  }
}