{
  "openapi": "3.0.3",
  "info": {
    "title": "Umney Connect AI Agent API",
    "version": "1.0.0",
    "description": "Public AI Agent API. Auth with an AI Agent token (ai:invoke). Pass third-party knowledge in context — Connect does not crawl external systems. Docs: https://umneyconnect.com/developers/ai-agent"
  },
  "servers": [
    { "url": "https://umneyconnect.com/api", "description": "Production" },
    { "url": "https://www.staging.umneyconnect.com/api", "description": "Staging" }
  ],
  "tags": [{ "name": "Runs" }],
  "components": {
    "securitySchemes": {
      "ApiKeyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "umk_live_ai_…",
        "description": "AI Agent token from Dashboard → Developers"
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "RunId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "schemas": {
      "CreateAiRun": {
        "type": "object",
        "required": ["input"],
        "properties": {
          "mode": { "type": "string", "enum": ["text"], "default": "text" },
          "input": { "type": "string", "maxLength": 4000 },
          "locale": { "type": "string", "maxLength": 10 },
          "context": {
            "type": "string",
            "maxLength": 24000,
            "description": "Third-party knowledge your backend already fetched (CRM, Nest, etc.)"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": { "type": "string" },
            "description": "Correlation IDs only; not auto-fetched"
          }
        }
      },
      "AiRun": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "mode": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "succeeded", "failed", "cancelled"]
          },
          "input": { "type": "string" },
          "locale": { "type": "string", "nullable": true },
          "context": { "type": "string", "nullable": true },
          "metadata": { "type": "object" },
          "outputText": { "type": "string", "nullable": true },
          "errorMessage": { "type": "string", "nullable": true },
          "model": { "type": "string", "nullable": true },
          "createdAt": { "type": "string" },
          "startedAt": { "type": "string", "nullable": true },
          "completedAt": { "type": "string", "nullable": true }
        }
      }
    }
  },
  "security": [{ "ApiKeyBearer": [] }, { "ApiKeyHeader": [] }],
  "paths": {
    "/v1/ai/runs": {
      "post": {
        "tags": ["Runs"],
        "summary": "Create and execute an AI run",
        "operationId": "createAiRun",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateAiRun" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run completed (synchronous MVP)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AiRun" }
              }
            }
          }
        }
      }
    },
    "/v1/ai/runs/{id}": {
      "get": {
        "tags": ["Runs"],
        "summary": "Get an AI run",
        "operationId": "getAiRun",
        "parameters": [{ "$ref": "#/components/parameters/RunId" }],
        "responses": {
          "200": {
            "description": "Run",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AiRun" }
              }
            }
          }
        }
      }
    }
  }
}