{
  "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 two website utilities 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/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. Values longer than 120 characters are truncated in the image.",
            "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" }
          }
        ],
        "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" }
              }
            }
          }
        }
      }
    }
  },
  "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": {
      "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" }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Website utilities",
      "description": "Unauthenticated helpers used by the public marketing site."
    }
  ]
}