{
  "openapi": "3.1.0",
  "info": {
    "title": "agent-swarm.dev Website Utility API",
    "version": "2026-08-21",
    "description": "The small, unauthenticated API used by the agent-swarm.dev marketing site. This specification covers the website utilities and the read-only public content API served by this domain. Product runtime deployments expose separate, deployment-specific interfaces documented in the source repository. Version lifecycle and deprecation signals are documented at https://www.agent-swarm.dev/api-versioning.md.",
    "contact": {
      "name": "Desplega Labs",
      "email": "contact@desplega.sh",
      "url": "https://www.agent-swarm.dev"
    },
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://www.agent-swarm.dev",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Website utility API versioning and deprecation policy",
    "url": "https://www.agent-swarm.dev/api-versioning.md"
  },
  "x-versioning-policy": {
    "strategy": "date-based-request-header",
    "requestHeader": "API-Version",
    "deprecationHeader": "Deprecation",
    "sunsetHeader": "Sunset",
    "policyUrl": "https://www.agent-swarm.dev/api-versioning.md"
  },
  "security": [],
  "paths": {
    "/api": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "List the website API operations",
        "description": "Returns a JSON index of the website utility and public content operations, with links to this OpenAPI description, the public content MCP server, the versioning policy, and the separate Agent Swarm runtime API reference.",
        "tags": ["Website utilities"],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersion" }
        ],
        "responses": {
          "200": {
            "description": "Website API index",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiIndex" }
              }
            }
          },
          "400": {
            "description": "RFC 9457 problem detail",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        }
      }
    },
    "/api/geo": {
      "get": {
        "operationId": "getConsentRegion",
        "summary": "Resolve whether cookie consent is required",
        "description": "Returns the request country reported by the hosting edge and whether the site should require cookie consent. An unknown country uses the privacy-safe default of requiring consent.",
        "tags": ["Website utilities"],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersion" }
        ],
        "responses": {
          "200": {
            "description": "Consent-region decision",
            "headers": {
              "Cache-Control": {
                "description": "The response is request-specific and must not be cached.",
                "schema": { "type": "string", "const": "no-store" }
              },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ConsentRegion" },
                "examples": {
                  "knownCountry": {
                    "value": { "country": "ES", "consentRequired": true }
                  },
                  "unknownCountry": {
                    "value": { "country": null, "consentRequired": true }
                  }
                }
              }
            }
          },
          "400": {
            "description": "RFC 9457 problem detail",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          },
          "500": {
            "description": "RFC 9457 problem detail",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        }
      }
    },
    "/api/og": {
      "get": {
        "operationId": "generateOpenGraphImage",
        "summary": "Generate an agent-swarm.dev social preview image",
        "description": "Renders a 1200 by 630 PNG used by the website's Open Graph and social metadata.",
        "tags": ["Website utilities"],
        "parameters": [
          { "$ref": "#/components/parameters/ApiVersion" },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "description": "Primary image heading. Defaults to agent-swarm.dev.",
            "schema": { "type": "string", "default": "agent-swarm.dev" }
          },
          {
            "name": "subtitle",
            "in": "query",
            "required": false,
            "description": "Optional supporting copy. Long values are cut at a word boundary, after about 100 to 150 characters (fewer when the title is long).",
            "schema": { "type": "string", "default": "" }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Use article to show the Blog label. Other values use the default page presentation.",
            "schema": { "type": "string", "enum": ["page", "article"], "default": "page" }
          },
          {
            "name": "style",
            "in": "query",
            "required": false,
            "description": "Card color. dark is zinc-950 with amber accents. amber is the homepage hero color.",
            "schema": { "type": "string", "enum": ["dark", "amber"], "default": "dark" }
          },
          {
            "name": "mascot",
            "in": "query",
            "required": false,
            "description": "The crew mascot on the right of the card. Defaults to writer for articles and lead for pages.",
            "schema": { "type": "string", "enum": ["lead", "coder", "reviewer", "researcher", "tester", "writer", "night"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Generated social preview image",
            "headers": {
              "API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": {
              "image/png": {
                "schema": { "type": "string", "contentEncoding": "binary" }
              }
            }
          },
          "400": {
            "description": "RFC 9457 problem detail",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          },
          "500": {
            "description": "RFC 9457 problem detail",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        }
      }
    },
    "/api/v1/pages": {
      "get": {
        "operationId": "listPages",
        "summary": "List public site pages",
        "description": "Lists every public agent-swarm.dev page with its title and canonical and markdown URLs, sorted by path. Cursor-paginated: pass nextCursor back as cursor until it is null.",
        "tags": [
          "Public content"
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque nextCursor from the previous response. Omit for the first page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items, 1 to 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageList"
                }
              }
            }
          },
          "400": {
            "description": "RFC 9457 problem detail: invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/page": {
      "get": {
        "operationId": "getPage",
        "summary": "Get one public page as markdown",
        "description": "Returns the markdown mirror of one public page, by site path or full agent-swarm.dev URL.",
        "tags": [
          "Public content"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "Site path such as /pricing, or a full agent-swarm.dev URL.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page with its markdown body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentPageWithBody"
                }
              }
            }
          },
          "400": {
            "description": "RFC 9457 problem detail: invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "RFC 9457 problem detail: no public page at that path",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "searchSite",
        "summary": "Search public site content",
        "description": "Full-text search over the public agent-swarm.dev pages: product pages, pricing, blog posts, case studies, examples, comparisons, integrations, security, and developer pages.",
        "tags": [
          "Public content"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search text: at most 200 characters and 10 distinct terms.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items, 1 to 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResults"
                }
              }
            }
          },
          "400": {
            "description": "RFC 9457 problem detail: invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/docs/search": {
      "get": {
        "operationId": "searchDocs",
        "summary": "Search the Agent Swarm documentation index",
        "description": "Searches the llms.txt index of docs.agent-swarm.dev and returns matching documentation pages. The index is cached for up to an hour.",
        "tags": [
          "Public content"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search text: at most 200 characters and 10 distinct terms.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of items, 1 to 50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked documentation pages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocsSearchResults"
                }
              }
            }
          },
          "400": {
            "description": "RFC 9457 problem detail: invalid query parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "502": {
            "description": "RFC 9457 problem detail: the documentation index could not be fetched",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/install": {
      "get": {
        "operationId": "getInstallInstructions",
        "summary": "Get Agent Swarm install instructions",
        "description": "Returns the official CLI command, the operator skill install command, and the self-hosting links.",
        "tags": [
          "Public content"
        ],
        "responses": {
          "200": {
            "description": "Install instructions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstallInstructions"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ApiVersion": {
        "name": "API-Version",
        "in": "header",
        "required": false,
        "description": "Optional date-based website utility API version. Omit the header to use the current version.",
        "schema": { "type": "string", "const": "2026-08-21", "default": "2026-08-21" }
      }
    },
    "headers": {
      "ApiVersion": {
        "description": "Date-based version of the website utility API that handled the request.",
        "schema": { "type": "string", "const": "2026-08-21" }
      }
    },
    "schemas": {
      "ApiIndex": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "description", "openapi", "versioningPolicy", "runtimeApiReference", "operations"],
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "openapi": { "type": "string", "format": "uri" },
          "versioningPolicy": { "type": "string", "format": "uri" },
          "mcp": {
            "type": "string",
            "format": "uri",
            "description": "Streamable HTTP MCP server with the same read-only public content as tools."
          },
          "runtimeApiReference": {
            "type": "string",
            "format": "uri",
            "description": "REST API reference for self-hosted Agent Swarm deployments."
          },
          "operations": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["operationId", "method", "path", "summary"],
              "properties": {
                "operationId": { "type": "string" },
                "method": { "type": "string", "enum": ["GET"] },
                "path": { "type": "string" },
                "summary": { "type": "string" }
              }
            }
          }
        }
      },
      "ConsentRegion": {
        "type": "object",
        "additionalProperties": false,
        "required": ["country", "consentRequired"],
        "properties": {
          "country": {
            "description": "Uppercase ISO 3166-1 alpha-2 country code, or null when the edge supplied no country.",
            "type": ["string", "null"],
            "pattern": "^[A-Z]{2}$"
          },
          "consentRequired": {
            "type": "boolean",
            "description": "Whether the site should wait for explicit analytics consent."
          }
        }
      },
      "Problem": {
        "type": "object",
        "additionalProperties": false,
        "required": ["type", "title", "status", "detail", "code", "resolution"],
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer", "minimum": 400, "maximum": 599 },
          "detail": { "type": "string" },
          "code": { "type": "string" },
          "resolution": { "type": "string" },
          "instance": { "type": "string" }
        }
      },
      "ContentPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "path",
          "title",
          "description",
          "url",
          "markdownUrl"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "Site path, for example /pricing."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ContentPageWithBody": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "path",
          "title",
          "description",
          "url",
          "markdownUrl",
          "markdown"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "Site path, for example /pricing."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "markdown": {
            "type": "string",
            "description": "Markdown mirror of the page."
          }
        }
      },
      "PageList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "nextCursor",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContentPage"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as cursor to get the next page; null on the last page."
          },
          "total": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "SearchResults": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query",
          "results"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "path",
                "title",
                "description",
                "url",
                "markdownUrl",
                "snippet",
                "score"
              ],
              "properties": {
                "path": {
                  "type": "string",
                  "description": "Site path, for example /pricing."
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "markdownUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "snippet": {
                  "type": "string"
                },
                "score": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      },
      "DocsSearchResults": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query",
          "results"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title",
                "description",
                "url",
                "score"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "score": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      },
      "InstallInstructions": {
        "type": "object",
        "required": [
          "product",
          "cli",
          "operatorSkill",
          "selfHosting",
          "note"
        ],
        "properties": {
          "product": {
            "type": "string"
          },
          "cli": {
            "type": "object",
            "required": [
              "package",
              "command",
              "npx",
              "bunx",
              "npmUrl",
              "reference"
            ],
            "properties": {
              "package": {
                "type": "string"
              },
              "command": {
                "type": "string"
              },
              "npx": {
                "type": "string"
              },
              "bunx": {
                "type": "string"
              },
              "npmUrl": {
                "type": "string",
                "format": "uri"
              },
              "reference": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "operatorSkill": {
            "type": "object",
            "required": [
              "install",
              "url"
            ],
            "properties": {
              "install": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "selfHosting": {
            "type": "object",
            "required": [
              "repository",
              "docs",
              "kubernetes"
            ],
            "properties": {
              "repository": {
                "type": "string",
                "format": "uri"
              },
              "docs": {
                "type": "string",
                "format": "uri"
              },
              "kubernetes": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "note": {
            "type": "string"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Website utilities",
      "description": "Unauthenticated helpers used by the public marketing site."
    },
    {
      "name": "Public content",
      "description": "Read-only, unauthenticated access to the public pages of agent-swarm.dev and the documentation index. The same content is available as tools on the MCP server at https://www.agent-swarm.dev/mcp."
    }
  ]
}
