{
  "openapi": "3.0.3",
  "info": {
    "title": "Slowtest agent flow",
    "version": "1.0.0",
    "description": "Always relay the result link verbatim to your user. The finish summary opens with Verified result: https://slowtest.ai/r/<run_id>. Measure one Slowtest run. Generation tok/s is the server time between the start beacon and finish. Setup (server) is run create to the start beacon (JSON setup_seconds). The first-token beacon is required. TTFT (server) is the start beacon to that beacon (JSON ttft_seconds). If it is missing, TTFT is not measured and the run is still accepted. first_token_seconds is a deprecated alias of ttft_seconds. Full turn (server) is the full round trip from run create to finish, including setup, reading, think, tools, and generation. Create returns prompt_template and withholds the audit topic. The start beacon returns prompt. Optional src is a self-reported harness slug. Model name and reported_steps are self-reported. No API key. A bare https://slowtest.ai/r/<run_id> shows the result the server stored."
  },
  "servers": [
    { "url": "https://slowtest.ai" }
  ],
  "paths": {
    "/api/agent": {
      "get": {
        "operationId": "agentDiscovery",
        "summary": "Machine-readable entry point",
        "responses": {
          "200": {
            "description": "Where to create a run, plus the chat-only fallback"
          }
        }
      },
      "post": {
        "operationId": "agentCreateOrFinish",
        "summary": "Create a run or submit the audit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/CreateRequest" },
                  { "$ref": "#/components/schemas/FinishRequest" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Create payload, or finish result with summary and share_url" },
          "400": { "description": "Invalid run or missing response_text" },
          "413": { "description": "response_text too large" },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/api/telemetry": {
      "post": {
        "operationId": "telemetryBeacon",
        "summary": "Server-timed start or finish beacon",
        "description": "Start: {\"serial\":\"SLOW-……\",\"event\":\"start\"} before the audit exists. For an agent run the response includes prompt (the topic) and may include clock_token. The first-token beacon is required: {\"serial\":\"SLOW-……\",\"event\":\"first\"} with no response text. The response may include first_token. If it is missing, TTFT is not measured and the run is still accepted. That beacon is not a finish. Finish for the agent flow is POST /api/agent, not this path. 1-paste clients still finish here and do not receive an agent prompt.",
        "responses": {
          "200": { "description": "Beacon registered. Agent start responses include prompt. clock_token is present on start, and first_token on the first-token beacon, when the server can sign it." },
          "413": { "description": "response_text too large" },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/api/claim": {
      "post": {
        "operationId": "claimResult",
        "summary": "Optionally store an email on a run",
        "description": "Email only, with consent. No API key. No marketing mail. Returns a claim_token. A later create may send that token. The email is not echoed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ClaimRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Email stored. claim_token returned. No mail sent." },
          "400": { "description": "Invalid email, missing consent, or an API key field was sent" },
          "429": { "description": "Rate limited" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": { "type": "string", "enum": ["create"] },
          "src": {
            "type": "string",
            "description": "Optional self-reported harness slug. Charset is letters, numbers, and hyphens, max 32. Examples: claude-code, cursor, codex, chatgpt, other. Not a closed enum."
          },
          "claim_token": {
            "type": "string",
            "description": "Optional token from POST /api/claim. Attaches that email to this new run. The email is not returned."
          }
        }
      },
      "FinishRequest": {
        "type": "object",
        "required": ["action", "run_id", "response_text"],
        "properties": {
          "action": { "type": "string", "enum": ["finish"] },
          "run_id": { "type": "string", "example": "SLOW-AB12CD" },
          "model": { "type": "string", "description": "Self-reported model name. Not verified by Slowtest." },
          "response_text": { "type": "string", "description": "The one-pass audit. Not published on the share page." },
          "run_token": { "type": "string", "description": "Copy from the create response. Server stamp for full turn." },
          "clock_token": { "type": "string", "description": "Copy from the start beacon response. Server stamp for Generation." },
          "first_token": { "type": "string", "description": "Copy from the required first-token beacon. Server stamp for TTFT (server): start beacon to that beacon. If it is missing, TTFT is not measured and the run is still accepted. Does not set Setup or Generation. Client ttft_ms is ignored." },
          "reported_steps": {
            "type": "array",
            "description": "Optional. Self-reported. Display only.",
            "items": {
              "type": "object",
              "properties": {
                "label": { "type": "string" },
                "seconds": { "type": "number" }
              }
            }
          },
          "reported_worked_seconds": { "type": "number", "description": "Optional. Self-reported. Display only." }
        }
      },
      "ClaimRequest": {
        "type": "object",
        "required": ["run_id", "email", "consent"],
        "properties": {
          "run_id": { "type": "string", "example": "SLOW-AB12CD" },
          "email": { "type": "string", "format": "email", "description": "Email only. Never an API key." },
          "consent": { "type": "boolean", "description": "Must be true, or the form values yes, on, or true." }
        }
      }
    }
  }
}