{
  "openapi": "3.1.0",
  "info": {
    "title": "Tutorium Agent API",
    "version": "1.0.0",
    "description": "Read-only public Tutorium data for assistants and agentic search. This API never creates bookings, sends messages or exposes private verification documents.",
    "externalDocs": {
      "description": "Machine-readable public Tutorium content snapshot",
      "url": "https://tutorium.uk/agent-content.json"
    }
  },
  "servers": [
    { "url": "https://tutorium.uk/agent/v1" }
  ],
  "tags": [
    { "name": "tutors", "description": "Published Tutorium tutor information" },
    { "name": "subjects", "description": "Canonical Tutorium subject guidance" }
  ],
  "paths": {
    "/tutors/search": {
      "get": {
        "operationId": "search_tutors",
        "summary": "Find published tutors",
        "description": "Search published tutor profiles by subject, level, exam board, delivery mode, area, budget and weekday availability. Results expose public profiles only; when no public profile matches, the response includes a noPublicMatch explanation and safe next steps rather than implying availability.",
        "tags": ["tutors"],
        "x-openai-isConsequential": false,
        "x-openai-readOnlyHint": true,
        "parameters": [
          { "$ref": "#/components/parameters/Subject" },
          { "$ref": "#/components/parameters/Level" },
          { "$ref": "#/components/parameters/ExamBoard" },
          { "$ref": "#/components/parameters/Mode" },
          { "$ref": "#/components/parameters/Area" },
          { "$ref": "#/components/parameters/Budget" },
          { "$ref": "#/components/parameters/Availability" },
          { "$ref": "#/components/parameters/Limit" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        }
      }
    },
    "/tutors/{publicSlug}": {
      "get": {
        "operationId": "get_tutor_profile",
        "summary": "Read a published tutor profile",
        "tags": ["tutors"],
        "x-openai-isConsequential": false,
        "x-openai-readOnlyHint": true,
        "parameters": [{ "$ref": "#/components/parameters/PublicSlug" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" }
        }
      }
    },
    "/tutors/{publicSlug}/availability": {
      "get": {
        "operationId": "get_tutor_availability",
        "summary": "Read published recurring availability",
        "description": "Returns published recurring windows only. The response is not a booking and exact availability must be confirmed before requesting a lesson.",
        "tags": ["tutors"],
        "x-openai-isConsequential": false,
        "x-openai-readOnlyHint": true,
        "parameters": [{ "$ref": "#/components/parameters/PublicSlug" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" }
        }
      }
    },
    "/subjects/{subjectSlug}": {
      "get": {
        "operationId": "get_subject_guidance",
        "summary": "Read canonical subject guidance",
        "tags": ["subjects"],
        "x-openai-isConsequential": false,
        "x-openai-readOnlyHint": true,
        "parameters": [{ "$ref": "#/components/parameters/SubjectSlug" }],
        "responses": {
          "200": { "$ref": "#/components/responses/JsonResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Subject": { "name": "subject", "in": "query", "schema": { "type": "string" }, "description": "Subject such as maths, English, chemistry, physics or biology." },
      "Level": { "name": "level", "in": "query", "schema": { "type": "string" }, "description": "Level or qualification such as GCSE, A-level or KS3." },
      "ExamBoard": { "name": "examBoard", "in": "query", "schema": { "type": "string" }, "description": "Exam board such as AQA, Edexcel or OCR." },
      "Mode": { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["online", "in_person"] }, "description": "Published delivery mode." },
      "Area": { "name": "area", "in": "query", "schema": { "type": "string" }, "description": "Published in-person service area or location." },
      "Budget": { "name": "budget", "in": "query", "schema": { "type": "number", "minimum": 1 }, "description": "Maximum hourly rate in GBP." },
      "Availability": { "name": "availability", "in": "query", "schema": { "type": "string" }, "description": "Weekday with a published availability window." },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 12 }, "description": "Maximum number of results." },
      "PublicSlug": { "name": "publicSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The public tutor slug returned by tutor search." },
      "SubjectSlug": { "name": "subjectSlug", "in": "path", "required": true, "schema": { "type": "string", "enum": ["maths", "english", "chemistry", "physics", "biology"] } }
    },
    "responses": {
      "JsonResponse": { "description": "Structured JSON response." },
      "ErrorResponse": { "description": "Structured error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["title", "status", "detail", "apiVersion"],
        "properties": {
          "type": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "detail": { "type": "string" },
          "apiVersion": { "type": "string" }
        }
      }
    }
  }
}