{
  "openapi": "3.1.0",
  "info": {
    "title": "Alkimi Public API",
    "description": "Public endpoints of alkimi.org, the agentic marketplace for programmatic media. Rate limiting: responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers for the most constrained window; a 429 response additionally carries Retry-After (seconds) and X-RateLimit-Scope naming the exhausted window.",
    "version": "1.0.0",
    "contact": { "email": "hello@alkimi.org" }
  },
  "servers": [{ "url": "https://www.alkimi.org" }],
  "paths": {
    "/api/news": {
      "get": {
        "operationId": "listNews",
        "description": "List the latest Alkimi news articles (metadata only, no article body).",
        "responses": {
          "200": {
            "description": "Latest articles, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/NewsArticle" }
                }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitContact",
        "description": "Send a contact request to the Alkimi team.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ContactPayload" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Submission accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "success": { "type": "boolean" } },
                  "required": ["success"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing fields.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          },
          "502": {
            "description": "Upstream service error — submission could not be stored.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        }
      }
    },
    "/api/chat": {
      "post": {
        "operationId": "sendChatMessage",
        "description": "Send a conversation to the Alkimi site assistant and stream back a plain-text reply.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": { "type": "string", "enum": ["user", "assistant"] },
                        "content": { "type": "string" }
                      },
                      "required": ["role", "content"]
                    }
                  }
                },
                "required": ["messages"],
                "example": { "messages": [{ "role": "user", "content": "..." }] }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Streamed plain-text reply from the assistant.",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          },
          "400": {
            "description": "Invalid or missing messages payload.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          },
          "403": {
            "description": "Request origin is not allowed.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          },
          "429": {
            "description": "Rate limited — honor the Retry-After header before retrying.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        }
      }
    },
    "/sellers.json": {
      "get": {
        "operationId": "getSellersJson",
        "description": "IAB sellers.json transparency file listing Alkimi's authorised sellers.",
        "responses": {
          "200": {
            "description": "IAB sellers.json 1.0 document (iabtechlab.com/sellers-json).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["version", "sellers"],
                  "properties": {
                    "contact_email": { "type": "string" },
                    "version": { "type": "string", "description": "sellers.json spec version, e.g. \"1.0\"." },
                    "sellers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["seller_id", "name", "seller_type"],
                        "properties": {
                          "seller_id": { "type": "string", "description": "Unique seller account identifier." },
                          "name": { "type": "string", "description": "Legal name of the seller." },
                          "domain": { "type": "string", "description": "Business domain of the seller." },
                          "seller_type": { "type": "string", "enum": ["PUBLISHER", "INTERMEDIARY", "BOTH"] }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NewsArticle": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "heading": { "type": "string" },
          "subheading": { "type": ["string", "null"] },
          "imageUrl": { "type": ["string", "null"] },
          "link": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "heading", "createdAt"]
      },
      "ContactPayload": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "job_title": { "type": "string" },
          "work_email": { "type": "string", "format": "email" },
          "priority": { "type": "string", "enum": ["high", "standard", "message"] },
          "message": { "type": "string" }
        },
        "required": ["name", "work_email", "priority"]
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details.",
        "properties": {
          "type": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "code": { "type": "string" },
          "detail": { "type": "string" },
          "resolution": { "type": "string" }
        },
        "required": ["title", "status", "code"]
      }
    }
  }
}