{
  "openapi": "3.1.0",
  "info": {
    "title": "Sophia Stack X content API",
    "version": "1",
    "description": "Read and write a Sophia Stack X site's content from other apps. Every request carries a site token made under the site's API tokens screen (Authorization: Bearer sxt_...). A token belongs to one site and holds scopes: read, write and mcp. Entries created here are drafts; a person or agent publishes them. @author Thomas G. and Sophia, SOPHIA XT LLC (sophiaxt.com)",
    "license": {"name": "SOPHIA XT license", "url": "https://sophiastack.sophiaxt.com/license"}
  },
  "servers": [{"url": "/api/v1", "description": "This site"}],
  "security": [{"siteToken": []}],
  "paths": {
    "/site": {
      "get": {
        "operationId": "getSite",
        "summary": "The site: name, languages, and every collection with its fields",
        "description": "Start here. Each collection lists its fields with their types, so a client knows what data an entry can hold. Needs the read scope.",
        "responses": {
          "200": {"description": "The site", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Site"}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"}
        }
      }
    },
    "/content/{collection}": {
      "get": {
        "operationId": "listEntries",
        "summary": "Live entries of a collection, newest or ordered as the collection sorts",
        "description": "Only published, due entries. Picture and file fields come back as objects with a url. Needs the read scope.",
        "parameters": [
          {"$ref": "#/components/parameters/collection"},
          {"$ref": "#/components/parameters/lang"},
          {"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1, "default": 1}},
          {"name": "per_page", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100}, "description": "Defaults to the collection's own page size."},
          {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Search the title and text."}
        ],
        "responses": {
          "200": {"description": "A page of entries", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EntryList"}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      },
      "post": {
        "operationId": "createDraft",
        "summary": "Create a draft entry",
        "description": "The data is checked against the collection's fields (see getSite). Values that fail are dropped and listed in problems; the draft is still created. Nothing goes live until someone publishes. Needs the write scope.",
        "parameters": [{"$ref": "#/components/parameters/collection"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/NewEntry"}}}
        },
        "responses": {
          "201": {"description": "The draft was created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Created"}}}},
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/content/{collection}/{alias}": {
      "get": {
        "operationId": "getEntry",
        "summary": "One live entry by its alias",
        "parameters": [
          {"$ref": "#/components/parameters/collection"},
          {"name": "alias", "in": "path", "required": true, "schema": {"type": "string"}, "description": "The entry's address part, like spring-menu."},
          {"$ref": "#/components/parameters/lang"}
        ],
        "responses": {
          "200": {"description": "The entry", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Entry"}}, "required": ["data"]}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"},
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/menus/{key}": {
      "get": {
        "operationId": "getMenu",
        "summary": "A menu as a tree, for building navigation in another front end",
        "parameters": [
          {"name": "key", "in": "path", "required": true, "schema": {"type": "string"}, "description": "main or footer, or a menu the site added."},
          {"$ref": "#/components/parameters/lang"}
        ],
        "responses": {
          "200": {"description": "The menu", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/MenuItem"}}}, "required": ["data"]}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"}
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "MCP over HTTP: one JSON-RPC message in, one out",
        "description": "The same tools as `sophia mcp`, limited to this token's site; tools that reach the server's own files are hidden. Start with initialize, then tools/list. Needs the mcp scope.",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JsonRpcRequest"}}}},
        "responses": {
          "200": {"description": "The JSON-RPC response", "content": {"application/json": {"schema": {"type": "object"}}}},
          "202": {"description": "A notification was accepted (no response body)"},
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "siteToken": {"type": "http", "scheme": "bearer", "bearerFormat": "sxt_...", "description": "A site token from the site's API tokens screen. Its scopes decide what it may do."}
    },
    "parameters": {
      "collection": {"name": "collection", "in": "path", "required": true, "schema": {"type": "string"}, "description": "A collection key from getSite, like page, article or product."},
      "lang": {"name": "lang", "in": "query", "schema": {"type": "string"}, "description": "A language code the site has. Defaults to its main language."}
    },
    "responses": {
      "BadRequest": {"description": "The request was not in the expected form", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "Unauthorized": {"description": "No token, or a token this site does not know", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "Forbidden": {"description": "The token lacks the scope this needs", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
      "NotFound": {"description": "No such collection or entry", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
    },
    "schemas": {
      "Error": {"type": "object", "properties": {"error": {"type": "string"}}},
      "Field": {
        "type": "object",
        "description": "One field of a collection. type is one of text, textarea, richtext, number, toggle, select, date, datetime, url, email, color, image, file, item, list, json.",
        "properties": {
          "name": {"type": "string"}, "label": {"type": "string"}, "type": {"type": "string"},
          "required": {"type": "boolean"}, "max": {"type": "number"}, "options": {"type": "array", "items": {}},
          "fields": {"type": "array", "items": {"$ref": "#/components/schemas/Field"}, "description": "For list fields: the fields of each row."}
        },
        "required": ["name", "type"]
      },
      "Collection": {
        "type": "object",
        "properties": {
          "key": {"type": "string"}, "label": {"type": "string"}, "extension": {"type": "string"},
          "builder": {"type": "boolean", "description": "True when entries are built from page-builder blocks."},
          "fields": {"type": "array", "items": {"$ref": "#/components/schemas/Field"}}
        },
        "required": ["key", "fields"]
      },
      "Site": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "default_lang": {"type": "string"},
          "languages": {"type": "array", "items": {"type": "object", "properties": {"code": {"type": "string"}, "name": {"type": "string"}}}},
          "collections": {"type": "array", "items": {"$ref": "#/components/schemas/Collection"}}
        },
        "required": ["name", "collections"]
      },
      "Media": {
        "type": "object",
        "description": "A picture or file. Pictures also carry their smaller sizes.",
        "properties": {"id": {"type": "integer"}, "url": {"type": "string"}, "alt": {"type": "string"}, "width": {"type": "integer"}, "height": {"type": "integer"}, "mime": {"type": "string"}}
      },
      "Entry": {
        "type": "object",
        "properties": {
          "id": {"type": "integer"},
          "collection": {"type": "string"},
          "lang": {"type": "string"},
          "alias": {"type": "string"},
          "title": {"type": "string"},
          "data": {"type": "object", "additionalProperties": true, "description": "The collection's fields. Picture and file fields are Media objects."},
          "published_at": {"type": "string"},
          "updated_at": {"type": "string"},
          "url": {"type": ["string", "null"], "description": "The entry's address on the site, when a menu or list routes to it."},
          "translation_group": {"type": "string", "description": "Shared by an entry's translations."}
        },
        "required": ["id", "collection", "lang", "alias", "title", "data"]
      },
      "EntryList": {
        "type": "object",
        "properties": {
          "data": {"type": "array", "items": {"$ref": "#/components/schemas/Entry"}},
          "page": {"type": "integer"}, "per_page": {"type": "integer"}, "total": {"type": "integer"}
        },
        "required": ["data", "page", "per_page", "total"]
      },
      "NewEntry": {
        "type": "object",
        "properties": {
          "title": {"type": "string", "maxLength": 300},
          "alias": {"type": "string", "description": "Optional; made from the title when empty."},
          "lang": {"type": "string"},
          "data": {"type": "object", "additionalProperties": true}
        },
        "required": ["title"]
      },
      "Created": {
        "type": "object",
        "properties": {
          "id": {"type": "integer"},
          "state": {"type": "string", "const": "draft"},
          "problems": {"type": "array", "items": {"type": "string"}, "description": "Values that were dropped and why."}
        },
        "required": ["id", "state", "problems"]
      },
      "MenuItem": {
        "type": "object",
        "properties": {"title": {"type": "string"}, "url": {"type": "string"}, "kind": {"type": "string"}, "children": {"type": "array", "items": {"$ref": "#/components/schemas/MenuItem"}}}
      },
      "JsonRpcRequest": {
        "type": "object",
        "properties": {"jsonrpc": {"type": "string", "const": "2.0"}, "id": {}, "method": {"type": "string"}, "params": {"type": "object"}},
        "required": ["jsonrpc", "method"]
      }
    }
  }
}
