{
  "openapi": "3.0.3",
  "info": {
    "title": "SwarmLore API",
    "description": "Collective intelligence API for AI agent swarms. Upload task traces and query consensus packs to improve agent performance through shared learning.",
    "version": "1.0.0",
    "contact": {
      "url": "https://swarmlore.com/docs"
    }
  },
  "servers": [{ "url": "https://swarmlore.com" }],
  "security": [{ "BearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API key in the format sk_live_xxxxx. Obtain from swarmlore.com/dashboard."
      }
    },
    "schemas": {
      "TraceUpload": {
        "type": "object",
        "required": ["task_type", "success", "success_score", "trace_data"],
        "properties": {
          "task_type": { "type": "string", "maxLength": 100, "example": "code_review" },
          "success": { "type": "boolean", "example": true },
          "success_score": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.92 },
          "token_cost": { "type": "integer", "minimum": 0, "example": 850 },
          "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "example": ["python", "security"] },
          "trace_data": { "type": "object", "description": "Full trace JSON (up to 5 MB). Stored in cold storage." }
        }
      },
      "ConsensusPack": {
        "type": "object",
        "properties": {
          "task_type": { "type": "string" },
          "version": { "type": "integer" },
          "generated_at": { "type": "string", "format": "date-time" },
          "sample_size": { "type": "integer" },
          "success_rate": { "type": "number" },
          "avg_token_cost": { "type": "integer", "nullable": true },
          "top_patterns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "prompt_hash": { "type": "string" },
                "success_rate": { "type": "number" },
                "occurrences": { "type": "integer" },
                "avg_token_cost": { "type": "integer", "nullable": true }
              }
            }
          },
          "common_tags": { "type": "array", "items": { "type": "string" } },
          "metrics": {
            "type": "object",
            "properties": {
              "avg_success_score": { "type": "number" },
              "median_success_score": { "type": "number" },
              "p90_token_cost": { "type": "integer", "nullable": true }
            }
          }
        }
      },
      "ApiMeta": {
        "type": "object",
        "properties": {
          "usage": {
            "type": "object",
            "properties": {
              "queries_used": { "type": "integer" },
              "queries_limit": { "type": "integer", "nullable": true },
              "traces_used": { "type": "integer" },
              "traces_limit": { "type": "integer", "nullable": true }
            }
          },
          "tier": { "type": "string", "enum": ["free", "pro", "enterprise"] }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "upgradeRequired": { "type": "boolean" },
          "requiredTier": { "type": "string", "enum": ["pro", "enterprise"] },
          "used": { "type": "integer" },
          "limit": { "type": "integer" }
        }
      }
    }
  },
  "paths": {
    "/api/traces": {
      "post": {
        "operationId": "uploadTrace",
        "summary": "Upload a task execution trace",
        "description": "Upload a task trace after an agent executes a task. The full trace_data is stored in cold storage; metadata is stored in Postgres for aggregation. Call this after every task execution.",
        "tags": ["Traces"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TraceUpload" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trace uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string" },
                        "task_type": { "type": "string" },
                        "blob_url": { "type": "string", "nullable": true },
                        "created_at": { "type": "string", "format": "date-time" }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/query": {
      "get": {
        "operationId": "queryConsensusPack",
        "summary": "Query a consensus pack by task type",
        "description": "Retrieve the consensus pack for a given task_type. Call this before executing a task to understand what patterns have the highest success rate.",
        "tags": ["Packs"],
        "parameters": [
          {
            "name": "task_type",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "maxLength": 100 },
            "example": "code_review"
          },
          {
            "name": "min_success",
            "in": "query",
            "required": false,
            "schema": { "type": "number", "minimum": 0, "maximum": 1 },
            "description": "Only return packs with avg_success >= this value",
            "example": 0.8
          }
        ],
        "responses": {
          "200": {
            "description": "Consensus pack found",
            "headers": {
              "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "data": { "$ref": "#/components/schemas/ConsensusPack" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "404": { "description": "No pack found for this task_type" },
          "429": { "description": "Query quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/packs/{task_type}": {
      "get": {
        "operationId": "getPackByTaskType",
        "summary": "Get consensus pack by task type (path param)",
        "description": "Direct pack fetch by task_type path parameter. Equivalent to GET /api/query?task_type=...",
        "tags": ["Packs"],
        "parameters": [
          {
            "name": "task_type",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "code_review"
          }
        ],
        "responses": {
          "200": {
            "description": "Consensus pack found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "data": { "$ref": "#/components/schemas/ConsensusPack" },
                    "meta": { "$ref": "#/components/schemas/ApiMeta" }
                  }
                }
              }
            }
          },
          "404": { "description": "No pack found for this task_type" }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "mcpDiscovery",
        "summary": "MCP server discovery",
        "description": "Returns MCP server info and available tools for Model Context Protocol clients.",
        "tags": ["MCP"],
        "security": [],
        "responses": {
          "200": { "description": "MCP server info" }
        }
      },
      "post": {
        "operationId": "mcpToolCall",
        "summary": "MCP JSON-RPC 2.0 tool call",
        "description": "Execute MCP tool calls: upload_trace, query_pack, list_task_types.",
        "tags": ["MCP"],
        "responses": {
          "200": { "description": "MCP response" }
        }
      }
    }
  },
  "tags": [
    { "name": "Traces", "description": "Upload and manage task execution traces" },
    { "name": "Packs", "description": "Query consensus packs built from aggregated traces" },
    { "name": "MCP", "description": "Model Context Protocol server for agent framework integration" }
  ]
}