{
  "openapi": "3.1.0",
  "info": {
    "title": "AlgoArena API",
    "version": "1.0.0",
    "summary": "Public HTTP API for AlgoArena, the coding-education platform at https://algoarena.net.",
    "description": "Documented here are the stable public endpoints. Authentication uses Firebase ID tokens (JWTs) sent as `Authorization: Bearer <idToken>`. The /api/v1 endpoints, for reading an assessment workspace's results from your own software, use a workspace API key instead (`Authorization: Bearer aa_live_...`); see https://algoarena.net/documentation/api. The scope names describing the API's access areas are published in the RFC 9728 protected-resource metadata at https://algoarena.net/.well-known/oauth-protected-resource; which areas a token can reach is derived from the account's role and plan. Errors are JSON objects with `error`, and where applicable `code`, `message`, and `hint` fields. Unknown API paths return a JSON 404 with `code: endpoint_not_found`.",
    "contact": {
      "name": "AlgoArena",
      "url": "https://algoarena.net/contact"
    },
    "termsOfService": "https://algoarena.net/terms"
  },
  "servers": [
    {
      "url": "https://algoarena.net"
    }
  ],
  "components": {
    "securitySchemes": {
      "firebaseBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Firebase ID token: `Authorization: Bearer <idToken>`, issued by https://securetoken.google.com/algoarena-a5209 (OIDC discovery is published under that issuer). Access areas (scopes) are listed as scopes_supported in https://algoarena.net/.well-known/oauth-protected-resource and are granted by account role, not requested at authorization time."
      },
      "workspaceApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Workspace API key for the /api/v1 endpoints: `Authorization: Bearer aa_live_...`. Owners and admins make and revoke keys in the assessment workspace's Settings, API and webhooks. A key reads one workspace's results. Guide: https://algoarena.net/documentation/api"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "description": "Human-readable error summary." },
          "code": { "type": "string", "description": "Stable machine-readable error code." },
          "message": { "type": "string", "description": "What went wrong." },
          "hint": { "type": "string", "description": "What to try next." }
        }
      },
      "Health": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "const": "ok" },
          "timestamp": { "type": "string", "format": "date-time" },
          "version": { "type": "string" }
        }
      },
      "Geo": {
        "type": "object",
        "properties": {
          "country": {
            "type": ["string", "null"],
            "description": "Best-effort ISO 3166-1 alpha-2 visitor country, or null when unknown."
          }
        }
      },
      "PlatformStats": {
        "type": "object",
        "properties": {
          "submissions": { "type": ["integer", "null"] },
          "users": { "type": ["integer", "null"] },
          "lines": { "type": ["integer", "null"], "description": "Estimated lines of code written on the platform." }
        }
      },
      "ProblemSearchResult": {
        "type": "object",
        "properties": {
          "fullLibrary": { "type": "boolean", "description": "False when the search catalog is unavailable or the query is empty." },
          "problems": { "type": "array", "items": { "type": "object" } },
          "truncated": { "type": "boolean", "description": "True when more than 500 problems matched." },
          "totalMatches": { "type": "integer" }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error", "code"],
        "properties": {
          "error": { "type": "string", "description": "What went wrong, as a sentence." },
          "code": {
            "type": "string",
            "enum": ["missing_api_key", "invalid_api_key", "api_key_revoked", "workspace_deleted", "invalid_parameter", "invalid_cursor", "not_found", "rate_limited", "internal_error"]
          }
        }
      },
      "Assessment": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "const": "assessment" },
          "id": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string", "description": "draft, active or archived." },
          "mode": { "type": "string", "enum": ["hiring", "training", "hackathon"] },
          "created_at": { "type": ["string", "null"], "format": "date-time" },
          "time_limit_minutes": { "type": ["number", "null"] },
          "pass_mark_percent": { "type": ["integer", "null"], "description": "Your own pass mark, 1 to 100, or null when not set." }
        }
      },
      "SkillValue": {
        "type": "object",
        "properties": {
          "score": { "type": ["integer", "null"], "description": "0 to 100. Null when not measured, not graded yet, or on a training assessment." },
          "level": {
            "type": ["string", "null"],
            "enum": ["novice", "emerging", "average", "above_average", "expert", null],
            "description": "Training assessments only, in place of the score."
          }
        }
      },
      "Result": {
        "type": "object",
        "description": "One attempt. The same shape in every list, in GET /api/v1/results/{id} and in every webhook. Never includes code, AI chats, replays, webcam or ID photos, or notes.",
        "properties": {
          "object": { "type": "string", "const": "result" },
          "id": { "type": "string" },
          "assessment": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "title": { "type": "string" },
              "mode": { "type": "string", "enum": ["hiring", "training", "hackathon"] }
            }
          },
          "participant": {
            "type": "object",
            "properties": {
              "name": { "type": ["string", "null"] },
              "email": { "type": ["string", "null"] }
            }
          },
          "status": { "type": "string", "enum": ["in_progress", "submitted", "expired"] },
          "started_at": { "type": ["string", "null"], "format": "date-time" },
          "submitted_at": { "type": ["string", "null"], "format": "date-time" },
          "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "Last time it was submitted, graded, decided or closed." },
          "grading_status": { "type": "string", "enum": ["not_submitted", "grading", "ready", "unavailable"], "description": "Scores are null until ready." },
          "points": {
            "type": "object",
            "properties": {
              "score": { "type": ["number", "null"] },
              "max": { "type": ["number", "null"] },
              "percent": { "type": ["number", "null"] }
            }
          },
          "pass_mark": {
            "type": ["object", "null"],
            "properties": {
              "percent": { "type": "integer" },
              "result": { "type": ["string", "null"], "enum": ["passed", "failed", null] }
            }
          },
          "ai_fluency": {
            "type": "object",
            "properties": {
              "overall": { "$ref": "#/components/schemas/SkillValue" },
              "skills": {
                "type": "object",
                "properties": {
                  "problem_solving": { "$ref": "#/components/schemas/SkillValue" },
                  "planning": { "$ref": "#/components/schemas/SkillValue" },
                  "prompting": { "$ref": "#/components/schemas/SkillValue" },
                  "verification": { "$ref": "#/components/schemas/SkillValue" },
                  "agentic_workflow": { "$ref": "#/components/schemas/SkillValue" }
                }
              },
              "scores_withheld": { "type": "boolean", "description": "True on a training assessment: levels only." }
            }
          },
          "integrity": {
            "type": "object",
            "properties": {
              "status": { "type": "string", "enum": ["pending", "no_flags", "flags_for_review"] },
              "flags": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "type": { "type": "string", "enum": ["low_typing", "integrity"] },
                    "label": { "type": "string" }
                  }
                }
              }
            }
          },
          "decision": { "type": "string", "enum": ["advance", "needs_discussion", "do_not_advance", "not_decided"] },
          "report_url": { "type": "string", "format": "uri", "description": "The full report. Needs a sign-in to the workspace." }
        }
      },
      "AssessmentList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "const": "list" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Assessment" } },
          "has_more": { "type": "boolean" },
          "next_cursor": { "type": ["string", "null"] }
        }
      },
      "ResultList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "const": "list" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } },
          "has_more": { "type": "boolean", "description": "Keep paging while true. A page can hold fewer than limit results even when more exist." },
          "next_cursor": { "type": ["string", "null"] }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "description": "The body of every webhook POST. Signed: X-AlgoArena-Signature is v1= and the hex HMAC-SHA256 of X-AlgoArena-Timestamp, a dot, and the raw body, keyed with the endpoint's signing secret.",
        "properties": {
          "id": { "type": "string", "description": "The event id. The same event can arrive twice; skip ids you already handled." },
          "type": { "type": "string", "enum": ["participant.started", "participant.submitted", "result.graded", "decision.made", "webhook.test"] },
          "created_at": { "type": "string", "format": "date-time" },
          "workspace_id": { "type": "string" },
          "test": { "type": "boolean", "description": "Present and true only on webhook.test." },
          "data": {
            "type": "object",
            "properties": { "result": { "$ref": "#/components/schemas/Result" } }
          }
        }
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health check",
        "tags": ["platform"],
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/api/geo": {
      "get": {
        "operationId": "getGeo",
        "summary": "Best-effort visitor country",
        "tags": ["platform"],
        "responses": {
          "200": {
            "description": "Visitor country from edge headers, or null.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Geo" } } }
          }
        }
      }
    },
    "/api/stats/platform": {
      "get": {
        "operationId": "getPlatformStats",
        "summary": "Cached platform activity counts",
        "tags": ["platform"],
        "responses": {
          "200": {
            "description": "Aggregate counts, revalidated hourly. Fields are null when the backing store is unavailable.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformStats" } } }
          }
        }
      }
    },
    "/api/problems/search": {
      "get": {
        "operationId": "searchProblems",
        "summary": "Full-library problem search",
        "description": "Searches the public problem catalog by title, id, tags, and aliases. Returns at most 500 rows.",
        "tags": ["problems"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 1 },
            "description": "Search query. An empty query returns an empty result with fullLibrary: false."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching problems.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemSearchResult" } } }
          }
        }
      }
    },
    "/api/problems/{id}": {
      "get": {
        "operationId": "getProblem",
        "summary": "Fetch one problem by id",
        "tags": ["problems"],
        "security": [{ "firebaseBearer": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "The problem document.", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "description": "Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "No problem with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/problems/companies": {
      "get": {
        "operationId": "listProblemCompanies",
        "summary": "Public company directory for the problem filter",
        "description": "With ?list=1, returns the public directory of companies (name, slug, aggregate count). The per-problem mapping requires an entitled account.",
        "tags": ["problems"],
        "parameters": [
          {
            "name": "list",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["1"] }
          }
        ],
        "responses": {
          "200": { "description": "Company directory plus the caller's entitlement flag.", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      },
      "post": {
        "operationId": "getProblemCompanyTags",
        "summary": "Company tags for a set of problems",
        "description": "Returns which companies each problem resembles. Free accounts receive entitled: false without the per-problem mapping.",
        "tags": ["problems"],
        "security": [{ "firebaseBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["problemIds"],
                "properties": { "problemIds": { "type": "array", "items": { "type": "string" } } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Per-problem company tags where entitled.", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/api/matchmaking/queue-status": {
      "get": {
        "operationId": "getQueueStatus",
        "summary": "Caller's matchmaking queue status",
        "tags": ["matchmaking"],
        "security": [{ "firebaseBearer": [] }],
        "responses": {
          "200": { "description": "Queue membership and basic profile for the authenticated user.", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "description": "Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/challenge/create": {
      "post": {
        "operationId": "createChallenge",
        "summary": "Create a friend-challenge invite",
        "tags": ["challenges"],
        "security": [{ "firebaseBearer": [] }],
        "responses": {
          "200": { "description": "The created challenge.", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "description": "Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/challenge/{challengeId}": {
      "get": {
        "operationId": "getChallenge",
        "summary": "Look up a challenge invite",
        "description": "Public so shareable invite links resolve without signing in. Accepting a challenge still requires authentication.",
        "tags": ["challenges"],
        "parameters": [
          {
            "name": "challengeId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Challenge metadata.", "content": { "application/json": { "schema": { "type": "object" } } } },
          "404": { "description": "No challenge with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/assessments": {
      "get": {
        "operationId": "listAssessments",
        "summary": "List your workspace's assessments",
        "description": "Newest first. Deleted assessments are left out.",
        "tags": ["workspace api"],
        "security": [{ "workspaceApiKey": [] }],
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "next_cursor from the page before." }
        ],
        "responses": {
          "200": { "description": "A page of assessments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessmentList" } } } },
          "400": { "description": "A bad limit or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "401": { "description": "No key, a wrong or revoked key, or a deleted workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "429": { "description": "Over 120 requests a minute for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
        }
      }
    },
    "/api/v1/results": {
      "get": {
        "operationId": "listResults",
        "summary": "List results",
        "description": "One result per attempt. Without updated_since, the newest submission comes first and attempts still in progress come last. With updated_since, the oldest change comes first. Previews and results of deleted assessments are left out.",
        "tags": ["workspace api"],
        "security": [{ "workspaceApiKey": [] }],
        "parameters": [
          { "name": "assessment_id", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["in_progress", "submitted", "expired"] } },
          { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only results submitted, graded, decided or closed at or after this time." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "next_cursor from the page before, with the same query." }
        ],
        "responses": {
          "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultList" } } } },
          "400": { "description": "A bad query value or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "401": { "description": "No key, a wrong or revoked key, or a deleted workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "404": { "description": "assessment_id is not in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "429": { "description": "Over 120 requests a minute for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
        }
      }
    },
    "/api/v1/results/{id}": {
      "get": {
        "operationId": "getResult",
        "summary": "Get one result",
        "tags": ["workspace api"],
        "security": [{ "workspaceApiKey": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } },
          "401": { "description": "No key, a wrong or revoked key, or a deleted workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "404": { "description": "Not in your workspace, or a preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "429": { "description": "Over 120 requests a minute for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
        }
      }
    }
  },
  "webhooks": {
    "participant.started": {
      "post": {
        "summary": "Someone started an assessment",
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Reply with any 2xx within 10 seconds." } }
      }
    },
    "participant.submitted": {
      "post": {
        "summary": "Someone submitted, or their time ran out and the attempt was submitted for them",
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Reply with any 2xx within 10 seconds." } }
      }
    },
    "result.graded": {
      "post": {
        "summary": "Grading finished and the scores are final; sent again if a score changes later",
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Reply with any 2xx within 10 seconds." } }
      }
    },
    "decision.made": {
      "post": {
        "summary": "Someone on the team recorded or changed the decision",
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Reply with any 2xx within 10 seconds." } }
      }
    }
  }
}
