{
  "openapi": "3.1.0",
  "info": {
    "title": "YourBest Academy public reference API",
    "version": "0.1.0",
    "description": "Public educational references, limited read-only agent protocols, and user-authorized quote enquiries. An enquiry is not an order or payment. Private case and commerce operations are outside this catalog."
  },
  "servers": [
    {
      "url": "https://yourbest.space"
    }
  ],
  "paths": {
    "/api/academy": {
      "get": {
        "operationId": "readAcademyReferences",
        "summary": "Read the public reference catalog, or the provisioned reference feed",
        "parameters": [
          {
            "name": "op",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "catalog",
                "offer",
                "agent-resource",
                "enquiry"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reference data or current offer readiness",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Provisioned feed requires academy:read bearer credentials"
          }
        }
      },
      "post": {
        "operationId": "useAcademyReferenceProtocol",
        "summary": "Submit a quote enquiry, use read-only MCP/A2A, or register and approve a temporary machine client",
        "parameters": [
          {
            "name": "op",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "mcp",
                "a2a",
                "agent-token",
                "agent-register",
                "agent-claim",
                "enquiry"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/EnquiryRequest"
                  },
                  {
                    "$ref": "#/components/schemas/JsonRpcRequest"
                  },
                  {
                    "$ref": "#/components/schemas/AgentRegistration"
                  },
                  {
                    "$ref": "#/components/schemas/AgentClaim"
                  },
                  {
                    "$ref": "#/components/schemas/AgentTokenRequest"
                  }
                ]
              },
              "examples": {
                "enquiry": {
                  "summary": "Only when op=enquiry and the user authorized the request",
                  "value": {
                    "email": "person@example.test",
                    "profession": "coaching",
                    "stage": "practicing",
                    "country": "es",
                    "goal": "credential",
                    "message": "Please help me compare preparation requirements.",
                    "privacyAcknowledged": true,
                    "privacyVersion": "2026-11-10-enquiry-v1",
                    "submissionId": "11111111-2222-4333-8444-555555555555",
                    "website": ""
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/AgentTokenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing enquiry receipt for an identical retry, MCP/A2A response, or OAuth access token",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/EnquiryReceipt"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcResponse"
                    },
                    {
                      "$ref": "#/components/schemas/AgentAccessToken"
                    }
                  ]
                }
              }
            }
          },
          "201": {
            "description": "New enquiry receipt after private persistence, or a temporary read-only machine client",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/EnquiryReceipt"
                    },
                    {
                      "$ref": "#/components/schemas/MachineClient"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported scope"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "405": {
            "description": "Method not supported"
          },
          "403": {
            "description": "Cross-origin request denied"
          },
          "409": {
            "description": "Submission ID already belongs to different enquiry data"
          },
          "413": {
            "description": "Request body exceeds 8192 bytes for an enquiry"
          },
          "415": {
            "description": "Enquiries require application/json"
          },
          "429": {
            "description": "Enquiry rate limit exceeded; retry after 600 seconds"
          },
          "503": {
            "description": "Enquiry storage unavailable; no receipt was created"
          }
        },
        "description": "For op=enquiry send EnquiryRequest as application/json. It requires user authorization and acknowledgement of https://yourbest.space/academy/privacy.html . A successful persistence returns EnquiryReceipt: 201 for a new request, 200 for an identical retry. It does not create a paid order. Other op values use their corresponding JSON-RPC or OAuth request schemas."
      }
    }
  },
  "externalDocs": {
    "description": "Agent discovery and supported access",
    "url": "https://yourbest.space/auth.md"
  },
  "components": {
    "schemas": {
      "EnquiryRequest": {
        "description": "User-authorized quote enquiry; not an order or payment. Private receipt returned only after storage succeeds.",
        "required": [
          "email",
          "profession",
          "stage",
          "country",
          "goal",
          "privacyAcknowledged",
          "privacyVersion",
          "submissionId"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "profession": {
            "enum": [
              "coaching",
              "psychology",
              "advising"
            ],
            "type": "string"
          },
          "stage": {
            "enum": [
              "starting",
              "practicing"
            ],
            "type": "string"
          },
          "country": {
            "enum": [
              "undecided",
              "es",
              "gb",
              "us",
              "other"
            ],
            "type": "string"
          },
          "goal": {
            "enum": [
              "training",
              "credential",
              "relocation"
            ],
            "type": "string"
          },
          "message": {
            "type": "string",
            "maxLength": 2000
          },
          "privacyAcknowledged": {
            "const": true,
            "type": "boolean"
          },
          "privacyVersion": {
            "const": "2026-11-10-enquiry-v1",
            "type": "string"
          },
          "submissionId": {
            "type": "string",
            "format": "uuid"
          },
          "website": {
            "const": "",
            "type": "string"
          }
        },
        "type": "object",
        "additionalProperties": false
      },
      "EnquiryReceipt": {
        "type": "object",
        "required": [
          "received",
          "id",
          "receivedAt",
          "next"
        ],
        "properties": {
          "received": {
            "const": true
          },
          "id": {
            "type": "string",
            "pattern": "^YBL-[a-f0-9-]{36}$"
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time"
          },
          "next": {
            "type": "string"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "method": {
            "type": "string"
          },
          "id": {
            "type": [
              "integer",
              "string",
              "null"
            ]
          },
          "params": {
            "type": "object"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "integer",
              "string",
              "null"
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object"
          }
        }
      },
      "AgentRegistration": {
        "type": "object",
        "additionalProperties": false,
        "anyOf": [
          {
            "required": [
              "type"
            ]
          },
          {
            "required": [
              "client_name"
            ]
          }
        ],
        "properties": {
          "type": {
            "const": "anonymous"
          },
          "client_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "scope": {
            "const": "academy:read"
          },
          "grant_types": {
            "const": [
              "client_credentials"
            ]
          },
          "token_endpoint_auth_method": {
            "const": "client_secret_basic"
          }
        }
      },
      "AgentClaim": {
        "type": "object",
        "required": [
          "client_id",
          "client_secret"
        ],
        "properties": {
          "client_id": {
            "type": "string"
          },
          "client_secret": {
            "type": "string"
          }
        }
      },
      "AgentTokenRequest": {
        "type": "object",
        "required": [
          "grant_type"
        ],
        "properties": {
          "grant_type": {
            "const": "client_credentials"
          },
          "scope": {
            "const": "academy:read"
          },
          "resource": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "MachineClient": {
        "type": "object",
        "required": [
          "client_id",
          "client_secret",
          "scope"
        ],
        "properties": {
          "client_id": {
            "type": "string"
          },
          "client_secret": {
            "type": "string"
          },
          "scope": {
            "const": "academy:read"
          }
        }
      },
      "AgentAccessToken": {
        "type": "object",
        "required": [
          "access_token",
          "token_type",
          "expires_in",
          "scope"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "token_type": {
            "const": "Bearer"
          },
          "expires_in": {
            "type": "integer"
          },
          "scope": {
            "const": "academy:read"
          }
        }
      }
    }
  }
}