{ "openapi": "3.1.0", "info": { "title": "AAS Archive API", "version": "1", "description": "The Archive's data as JSON, read from the same database as the pages. Reading is free and needs an account: make a token on your account page. Every request is recorded with the account, the token, what was asked and when." }, "servers": [ { "url": "/", "description": "https://ai-assisted-speedruns.org" } ], "components": { "securitySchemes": { "apiToken": { "type": "http", "scheme": "bearer", "description": "A token made on your account page under Settings, sent as `Authorization: Bearer `. Reading is free and needs an account; every request is recorded with the account, the token, what was asked and when, and kept for 90 days." }, "loginToken": { "type": "http", "scheme": "bearer", "description": "The access token of `aas login` (OAuth 2.1 with PKCE on a loopback address). Only the tooling holds one." }, "ticketSecret": { "type": "http", "scheme": "Ticket", "description": "For a ticket asked for without an account: `Authorization: Ticket `, the control secret returned with the ticket." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } } }, "Model": { "type": "object", "description": "A model as the runtime reported it.", "properties": { "model": { "type": "string", "description": "the full model id" }, "parts": { "type": [ "object", "null" ], "description": "name, variant, version, snapshot when the id has them" }, "effort": { "type": [ "string", "null" ] }, "contextWindow": { "type": [ "integer", "null" ] }, "maxOutputTokens": { "type": [ "integer", "null" ] }, "provider": { "type": [ "string", "null" ] } } }, "Plugin": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "ai": { "type": "boolean", "description": "for the runtime: whether a model played (the plugin's hash is one the Archive trusts)" }, "cliVersions": { "type": "array", "items": { "type": "string" } } } }, "GameRef": { "type": "object", "properties": { "slug": { "type": [ "string", "null" ], "description": "the game's address on this site" }, "id": { "type": [ "string", "null" ], "description": "its id in the tooling" }, "name": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] } } }, "Category": { "type": "object", "description": "The seven axes of the specification's §3, game apart.", "properties": { "goal": { "type": [ "string", "null" ] }, "goalLabel": { "type": [ "string", "null" ] }, "build": { "type": [ "string", "null" ] }, "observation": { "type": [ "string", "null" ] }, "input": { "type": [ "string", "null" ] }, "timing": { "type": [ "string", "null" ] }, "human": { "type": [ "string", "null" ] } } }, "Agent": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" }, "description": "the models that answered" }, "requested": { "oneOf": [ { "$ref": "#/components/schemas/Model" }, { "type": "null" } ], "description": "the model that was asked for, where it differs" }, "runtime": { "oneOf": [ { "$ref": "#/components/schemas/Plugin" }, { "type": "null" } ], "description": "the runtime plugin, with ai: whether a model played" }, "harness": { "type": [ "object", "null" ], "description": "the harness name and version" }, "tokens": { "type": [ "object", "null" ], "description": "tokens total, input and output, as the runtime reported them" } } }, "Times": { "type": "object", "description": "Seconds, from the bundle's own timeline; never recalculated here.", "properties": { "igt": { "type": [ "number", "null" ], "description": "in-game time" }, "rta": { "type": [ "number", "null" ], "description": "real time" }, "thinking": { "type": [ "number", "null" ], "description": "real time minus playback time" }, "toolCalls": { "type": [ "integer", "null" ] }, "playbacks": { "type": [ "integer", "null" ] }, "segments": { "type": [ "integer", "null" ] }, "toGoal": { "type": [ "number", "null" ] } } }, "Dates": { "type": "object", "properties": { "started": { "type": [ "string", "null" ] }, "completed": { "type": [ "string", "null" ] }, "ended": { "type": [ "string", "null" ] }, "submitted": { "type": [ "string", "null" ] }, "published": { "type": [ "string", "null" ] }, "zone": { "type": [ "string", "null" ] } } }, "Mod": { "type": "object", "description": "a mod that was loaded", "properties": { "name": { "type": "string" }, "version": { "type": [ "string", "null" ] } } }, "RunSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "the address the run is published under; may change between revisions" }, "uid": { "type": [ "string", "null" ], "description": "the run's identity, written once when the run was configured" }, "revision": { "type": [ "integer", "null" ], "description": "which publication of the run this is" }, "url": { "type": "string", "description": "the run's page on this site" }, "game": { "$ref": "#/components/schemas/GameRef" }, "category": { "$ref": "#/components/schemas/Category" }, "agent": { "$ref": "#/components/schemas/Agent" }, "mods": { "type": "array", "items": { "$ref": "#/components/schemas/Mod" } }, "times": { "$ref": "#/components/schemas/Times" }, "reachedGoal": { "type": "boolean", "description": "whether the run reached its declared goal; a run that did not is not ranked" }, "place": { "type": [ "integer", "null" ], "description": "its place in its category, when the list is ranked" }, "example": { "type": "boolean", "description": "published to show what an entry looks like, not as a submitted run" }, "title": { "type": [ "string", "null" ], "description": "the Archive's own title for the run, where a reviewer gave one" }, "operator": { "type": [ "string", "null" ], "description": "the name on the account that submitted it" }, "dates": { "$ref": "#/components/schemas/Dates" }, "versions": { "type": "object", "description": "bundle and schema versions" } } }, "RunDetail": { "allOf": [ { "$ref": "#/components/schemas/RunSummary" }, { "type": "object", "properties": { "game": { "allOf": [ { "$ref": "#/components/schemas/GameRef" }, { "type": "object", "properties": { "settings": { "type": "object" }, "mods": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "sha256": { "type": [ "string", "null" ] } } } } } } ] }, "agent": { "allOf": [ { "$ref": "#/components/schemas/Agent" }, { "type": "object", "properties": { "plugins": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Plugin" } }, "tools": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } } } } } ] }, "category": { "allOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "object", "properties": { "goalFinal": { "type": [ "boolean", "null" ], "description": "whether the goal is the game's own end" }, "humanNotes": { "type": [ "string", "null" ] } } } ] }, "seed": { "type": [ "string", "null" ] }, "fingerprint": { "type": [ "string", "null" ], "description": "sha256 of the run's own log; binds a recording" }, "recording": { "type": "object", "description": "the recording as the bundle states it (SPEC §6)", "properties": { "seconds": { "type": [ "number", "null" ] }, "segmentSeconds": { "type": "array", "items": { "type": "number" } }, "cutVideo": { "type": [ "number", "null" ] }, "playbackWall": { "type": [ "number", "null" ] }, "completedRta": { "type": [ "number", "null" ] }, "videos": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "each video with its length and the code or line that binds it" } } }, "recordings": { "type": "array", "items": { "type": "object", "description": "where the recording is published, as the submitter said and a reviewer approved", "properties": { "url": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "host": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "confirmedAt": { "type": [ "string", "null" ] } } } }, "acceptance": { "type": [ "object", "null" ], "description": "on whose word the run is in the Archive", "properties": { "at": { "type": [ "string", "null" ] }, "by": { "type": [ "string", "null" ] }, "override": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "missing": { "type": "array", "items": { "type": "string" } } } }, "note": { "type": [ "string", "null" ] }, "recordCounts": { "type": [ "object", "null" ] }, "forum": { "type": [ "object", "null" ], "properties": { "topic": { "type": "string" } } }, "goals": { "type": "array" }, "ends": { "type": "array" }, "sections": { "type": "array" }, "attempts": { "type": "array" }, "chapters": { "type": "array" }, "events": { "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer" }, "at": { "type": "number" }, "time": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "data": { "type": "object" } } } }, "checks": { "type": "array", "description": "the tooling's check, point by point" }, "signature": { "type": "object", "properties": { "signed": { "type": "boolean" }, "valid": { "type": [ "boolean", "null" ] }, "fingerprint": { "type": [ "string", "null" ] }, "account": { "type": [ "string", "null" ] } } }, "files": { "type": "array" }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "revision": { "type": "integer" }, "published": { "type": "string" }, "current": { "type": "boolean" } } } }, "bundle": { "type": [ "string", "null" ], "description": "the zip under /bundles/" }, "log": { "type": "string" } } } ] }, "Game": { "type": "object", "properties": { "slug": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "runs": { "type": "integer" }, "goals": { "type": "array", "items": { "type": "object", "properties": { "goal": { "type": "string" }, "label": { "type": [ "string", "null" ] } } } }, "platforms": { "type": "array", "items": { "type": "string" } }, "versions": { "type": "array", "items": { "type": "string" } }, "models": { "type": "array", "items": { "type": "string" } }, "latest": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, "CategoryCount": { "allOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "object", "properties": { "game": { "type": "string" }, "runs": { "type": "integer" }, "reached": { "type": "integer" } } } ] }, "LogRecord": { "type": "object", "properties": { "sequence": { "type": "integer", "description": "the record's place in the log" }, "at": { "type": [ "number", "null" ], "description": "seconds from the start of the recording" }, "kind": { "type": "string", "enum": [ "message", "tool_call", "tool_result", "event" ] }, "role": { "type": [ "string", "null" ], "description": "who spoke" }, "tool": { "type": [ "string", "null" ], "description": "for a call and its result: the tool" }, "call": { "type": [ "string", "null" ], "description": "the call a result belongs to" }, "event": { "type": [ "string", "null" ], "description": "for an event: its name" }, "data": { "type": [ "object", "null" ], "description": "for an event: what the harness attached" }, "body": { "type": [ "string", "null" ], "description": "what was said, the code that ran, or what came back, as the published log has it" } } }, "SearchHit": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/RunSummary" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer" }, "at": { "type": [ "number", "null" ] }, "kind": { "type": "string" }, "section": { "type": [ "string", "null" ] } } }, "description": "every match in that run; the record itself is in the run's log" } } }, "Stats": { "type": "object", "properties": { "totals": { "type": "object", "description": "runs, games, reached, models, runtimes, rta, igt, thinking, toolCalls, tokens" }, "games": { "type": "array", "items": { "type": "object" } }, "models": { "type": "array", "items": { "type": "object" } }, "runtimes": { "type": "array", "items": { "type": "object" } }, "sections": { "type": "array", "items": { "type": "object" } } } }, "Endpoint": { "type": "object", "properties": { "path": { "type": "string" }, "returns": { "type": "string" }, "params": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "about": { "type": "string" } } } } } } } }, "paths": { "/api/v1/": { "get": { "summary": "the list of endpoints, and how to get a token", "description": "Returns the list of endpoints, and how to get a token. Example: `/api/v1/`.", "x-example": "/api/v1/", "parameters": [], "security": [], "responses": { "200": { "description": "the list of endpoints, and how to get a token", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer" }, "documentation": { "type": "string" }, "openapi": { "type": "string" }, "authentication": { "type": "string" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } } } } }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/games": { "get": { "summary": "every game with runs", "description": "Returns every game with runs. Example: `/api/v1/games`.", "x-example": "/api/v1/games", "parameters": [], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "every game with runs", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Game" } } } } } } }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/games/{game}": { "get": { "summary": "one game and its categories", "description": "Returns one game and its categories. Example: `/api/v1/games/slay-the-spire`.", "x-example": "/api/v1/games/slay-the-spire", "parameters": [ { "name": "game", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "one game and its categories", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Game" }, { "type": "object", "properties": { "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryCount" } } } } ] } } } } } }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/categories": { "get": { "summary": "every category that holds runs", "description": "Returns every category that holds runs. Example: `/api/v1/categories?game=slay-the-spire`.", "x-example": "/api/v1/categories?game=slay-the-spire", "parameters": [ { "name": "game", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a game's slug, such as slay-the-spire" }, { "name": "goal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a goal id, such as act3" } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "every category that holds runs", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryCount" } } } } } } }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs": { "get": { "summary": "runs, newest first; with a game and a goal, grouped by category and ranked within it", "description": "Returns runs, newest first; with a game and a goal, grouped by category and ranked within it. Example: `/api/v1/runs?game=slay-the-spire&goal=act3&limit=10`.", "x-example": "/api/v1/runs?game=slay-the-spire&goal=act3&limit=10", "parameters": [ { "name": "game", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a game's slug" }, { "name": "goal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a goal id" }, { "name": "observation", "in": "query", "required": false, "schema": { "type": "string" }, "description": "an axis value (specification §3)" }, { "name": "input", "in": "query", "required": false, "schema": { "type": "string" }, "description": "an axis value (specification §3)" }, { "name": "timing", "in": "query", "required": false, "schema": { "type": "string" }, "description": "an axis value (specification §3)" }, { "name": "human", "in": "query", "required": false, "schema": { "type": "string" }, "description": "an axis value (specification §3)" }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a full model id" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a part of the model id" }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a part of the model id" }, { "name": "model_version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a part of the model id" }, { "name": "snapshot", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a part of the model id" }, { "name": "effort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "as the runtime reported it" }, { "name": "context", "in": "query", "required": false, "schema": { "type": "string" }, "description": "the context window, as the runtime reported it" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "as the runtime reported it" }, { "name": "runtime", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a runtime plugin id" }, { "name": "cli", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a runtime CLI version" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a game version" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "runs per page, at most 100; 50 when left out" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page, with the same other parameters" } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "runs, newest first; with a game and a goal, grouped by category and ranked within it", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RunSummary" }, "description": "the runs of this page" }, "total": { "type": "integer", "description": "how many runs match" }, "next_cursor": { "type": [ "string", "null" ], "description": "pass it as cursor for the next page; null on the last page" } } } } } }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{run}": { "get": { "summary": "one run whole", "description": "Returns one run whole. Example: `/api/v1/runs/sts-claude-code-01`.", "x-example": "/api/v1/runs/sts-claude-code-01", "parameters": [ { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "one run whole", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunDetail" } } } } } }, "301": { "description": "The run is published under another address now; error.location names it." }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/runs/{run}/log": { "get": { "summary": "the run's log, record by record, in order", "description": "Returns the run's log, record by record, in order. Example: `/api/v1/runs/sts-claude-code-01/log?limit=100`.", "x-example": "/api/v1/runs/sts-claude-code-01/log?limit=100", "parameters": [ { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "records per page, at most 100; 100 when left out" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page, with the same other parameters" } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "the run's log, record by record, in order", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LogRecord" } }, "next_cursor": { "type": [ "string", "null" ], "description": "pass it as cursor for the next page; null on the last page" } } } } } }, "301": { "description": "The run is published under another address now; error.location names it." }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/search": { "get": { "summary": "the runs whose log matched, best first", "description": "Returns the runs whose log matched, best first. Example: `/api/v1/search?q=boss&game=slay-the-spire`.", "x-example": "/api/v1/search?q=boss&game=slay-the-spire", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "the words: \"exact phrase\", -leave out, prefix*; and conditions on game-state values: current_hp<10, floor>=5, screen_type=MAP, or with the path, game_state.current_hp<10" }, { "name": "game", "in": "query", "required": false, "schema": { "type": "string" }, "description": "as for runs" }, { "name": "goal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "as for runs" }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string" }, "description": "as for runs" }, { "name": "what", "in": "query", "required": false, "schema": { "type": "string" }, "description": "said, prompt, code, returned or event" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "runs per page, at most 20" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page, with the same other parameters" } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "the runs whose log matched, best first", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "description": "the query as read" }, "total": { "type": "integer", "description": "how many matches" }, "runs": { "type": "integer", "description": "in how many runs" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } }, "next_cursor": { "type": [ "string", "null" ], "description": "pass it as cursor for the next page; null on the last page" } } } } } }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stats": { "get": { "summary": "what the Archive holds in numbers", "description": "Returns what the Archive holds in numbers. Example: `/api/v1/stats?game=portal`.", "x-example": "/api/v1/stats?game=portal", "parameters": [ { "name": "game", "in": "query", "required": false, "schema": { "type": "string" }, "description": "a game's slug; tool calls per section need one" } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "what the Archive holds in numbers", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "requests allowed per 5 minutes per token" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "seconds until the window resets" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "game": { "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Stats" } } } } } }, "400": { "description": "A parameter or cursor that cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No token, or a revoked one: make one on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such game, run or endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Anything but GET: the API only reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tickets": { "post": { "summary": "a ticket for a run about to be recorded", "description": "Signed in with `aas login` the ticket is the account's; without, it is held by the control secret in the answer until the run is submitted.", "security": [ { "loginToken": [] }, {} ], "responses": { "200": { "description": "the ticket, when it was issued, when it lapses, and the Archive's signature" }, "429": { "description": "Over the limit for this token; Retry-After says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tickets/{ticket}": { "get": { "summary": "the state of a ticket", "parameters": [ { "name": "ticket", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "loginToken": [] }, { "ticketSecret": [] } ], "responses": { "200": { "description": "the ticket's heads and receipts" }, "404": { "description": "no such ticket for you" } } }, "delete": { "summary": "delete a ticket no run was submitted with", "parameters": [ { "name": "ticket", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "loginToken": [] }, { "ticketSecret": [] } ], "responses": { "200": { "description": "deleted" }, "404": { "description": "no such ticket for you" } } } }, "/api/v1/tickets/{ticket}/heads": { "post": { "summary": "a hash of the logs as they stand, signed by the Archive with the time", "parameters": [ { "name": "ticket", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "loginToken": [] }, { "ticketSecret": [] } ], "responses": { "200": { "description": "done; for heads, the receipt" }, "404": { "description": "no such ticket for you" }, "409": { "description": "the ticket has lapsed" } } } }, "/api/v1/tickets/{ticket}/extend": { "post": { "summary": "start the ticket's period again", "parameters": [ { "name": "ticket", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "loginToken": [] }, { "ticketSecret": [] } ], "responses": { "200": { "description": "done; for heads, the receipt" }, "404": { "description": "no such ticket for you" }, "409": { "description": "the ticket has lapsed" } } } }, "/api/v1/tickets/{ticket}/revoke": { "post": { "summary": "the ticket takes no more heads", "parameters": [ { "name": "ticket", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "loginToken": [] }, { "ticketSecret": [] } ], "responses": { "200": { "description": "done; for heads, the receipt" }, "404": { "description": "no such ticket for you" }, "409": { "description": "the ticket has lapsed" } } } }, "/api/v1/bundles": { "post": { "summary": "the upload zip of a run", "description": "`aas upload -upload.zip`: the zip as `aas publish` made it, with `X-Filename` naming it. Checked as the upload page checks it; a person still decides.", "security": [ { "loginToken": [] } ], "requestBody": { "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "received: `status` review, the submission's number, the proof's status and the reasons a reviewer will see" }, "401": { "description": "sign in with aas login" }, "422": { "description": "refused, with `code` and `reasons`" } } } } } }