{
  "openapi": "3.1.0",
  "info": {
    "title": "Barestate website API",
    "version": "1.0.0",
    "summary": "Public endpoints on barestate.xyz: send a message to the Barestate team and read the Oh My Sol benchmark figures.",
    "description": "The public API of the barestate.xyz site Worker. `POST /api/contact` sends a message to the Barestate team by email. `GET /api/benchmarks` returns the Oh My Sol benchmark figures shown on https://barestate.xyz/oh-my-sol as JSON. No authentication or API key is needed. Oh My Sol account endpoints under /oms/api belong to a separate gateway and are not described here.",
    "contact": {
      "name": "Barestate",
      "url": "https://barestate.xyz/contact"
    }
  },
  "servers": [
    {
      "url": "https://barestate.xyz",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Oh My Sol documentation",
    "url": "https://barestate.xyz/docs"
  },
  "tags": [
    {
      "name": "Contact",
      "description": "Reach the Barestate team."
    },
    {
      "name": "Benchmarks",
      "description": "Oh My Sol benchmark results."
    }
  ],
  "paths": {
    "/api/contact": {
      "post": {
        "operationId": "sendContactMessage",
        "security": [],
        "tags": [
          "Contact"
        ],
        "summary": "Send a message to the Barestate team",
        "description": "Delivers a plain-text message to the Barestate team by email, with the sender's address as Reply-To. Accepts JSON or a URL-encoded form; the body may be at most 16 KB. Requests that send an `Origin` header must come from https://barestate.xyz, and requests that send `Sec-Fetch-Site` must have it set to `same-origin`. Limited to about five requests per minute per client. When the site has Cloudflare Turnstile enabled, `turnstileToken` is required. JSON requests get JSON responses. URL-encoded requests always get a 303 redirect: to `/contact?sent=1#sent` on success, or to `/contact?error=<code>` on failure.",
        "requestBody": {
          "required": true,
          "description": "The message. `website` is a honeypot: leave it out or empty; a non-empty value is accepted with 200 and silently dropped.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactRequest"
              },
              "example": {
                "name": "Ada Lovelace",
                "email": "ada@example.com",
                "message": "I would like to talk about Oh My Sol for our team."
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The message was accepted for delivery (JSON requests).",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactAccepted"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "303": {
            "description": "Form submissions (application/x-www-form-urlencoded) are redirected back to the contact page with the outcome.",
            "headers": {
              "Location": {
                "description": "`/contact?sent=1#sent` on success, `/contact?error=<code>` on failure, where `<code>` is one of the error codes.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "/contact?sent=1#sent",
                    "/contact?error=INVALID_REQUEST"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "INVALID_REQUEST: the body is missing, over 16 KB, not valid JSON or form data, fails validation, or the request came from another origin.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Provide a name, email address and a message of 10 to 5000 characters."
                  }
                }
              }
            }
          },
          "403": {
            "description": "TURNSTILE_FAILED: Turnstile is enabled and the token is missing or invalid.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "TURNSTILE_FAILED",
                    "message": "Complete the security check again."
                  }
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: only POST is accepted.",
            "headers": {
              "Allow": {
                "description": "Always `POST`.",
                "schema": {
                  "type": "string",
                  "const": "POST"
                }
              },
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "METHOD_NOT_ALLOWED",
                    "message": "Use POST for contact requests."
                  }
                }
              }
            }
          },
          "429": {
            "description": "RATE_LIMITED: too many messages from this client. Try again in a minute.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Too many messages. Try again later."
                  }
                }
              }
            }
          },
          "503": {
            "description": "EMAIL_UNAVAILABLE: email delivery or rate limiting is unavailable. Try again later.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "EMAIL_UNAVAILABLE",
                    "message": "Contact is unavailable. Try again later."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/benchmarks": {
      "get": {
        "operationId": "getBenchmarks",
        "security": [],
        "tags": [
          "Benchmarks"
        ],
        "summary": "Get the Oh My Sol benchmark figures",
        "description": "Returns the benchmark results published on https://barestate.xyz/oh-my-sol: pass rates, matched runs and input tokens per solved task on eight fresh Solana tasks for four models, and Solana Bench scores against Codex CLI and Claude Code. Read-only, public, CORS-enabled for any origin, and cacheable for an hour. The `fields` object in the response explains each figure and its unit. Methodology: https://barestate.xyz/docs/benchmarks/methodology.",
        "responses": {
          "200": {
            "description": "The benchmark figures.",
            "headers": {
              "Cache-Control": {
                "description": "`public, max-age=3600`.",
                "schema": {
                  "type": "string"
                }
              },
              "Access-Control-Allow-Origin": {
                "description": "Always `*`.",
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Benchmarks"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: only GET, HEAD and OPTIONS are accepted.",
            "headers": {
              "Allow": {
                "description": "`GET, HEAD, OPTIONS`.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "NoStore": {
        "description": "Always `no-store`.",
        "schema": {
          "type": "string",
          "const": "no-store"
        }
      }
    },
    "schemas": {
      "ContactRequest": {
        "type": "object",
        "description": "A message for the Barestate team.",
        "required": [
          "name",
          "email",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Sender's name. Must contain a non-space character and no control characters."
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 320,
            "description": "Sender's email address, used as Reply-To."
          },
          "message": {
            "type": "string",
            "minLength": 10,
            "maxLength": 5000,
            "description": "The message, plain text. Tabs and line breaks are allowed; other control characters are not."
          },
          "website": {
            "type": "string",
            "maxLength": 0,
            "description": "Honeypot. Leave out or send an empty string."
          },
          "turnstileToken": {
            "type": "string",
            "maxLength": 2048,
            "description": "Cloudflare Turnstile token. Required only when the site has Turnstile enabled."
          }
        },
        "additionalProperties": true
      },
      "ContactAccepted": {
        "type": "object",
        "description": "The message was accepted.",
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true,
            "description": "Always true."
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "An error with a stable code and a human-readable message.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "description": "What went wrong.",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "INVALID_REQUEST",
                  "METHOD_NOT_ALLOWED",
                  "RATE_LIMITED",
                  "TURNSTILE_FAILED",
                  "EMAIL_UNAVAILABLE"
                ],
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation, safe to show to a person."
              }
            }
          }
        }
      },
      "HarnessResult": {
        "type": "object",
        "description": "One harness's results for one model on the fresh tasks.",
        "required": [
          "runs",
          "passes",
          "passRatePercent",
          "inputTokensPerSolvedTask"
        ],
        "properties": {
          "runs": {
            "type": "integer",
            "minimum": 0,
            "description": "Runs of the eight tasks.",
            "x-unit": "runs"
          },
          "passes": {
            "type": "integer",
            "minimum": 0,
            "description": "Runs that passed the hidden check.",
            "x-unit": "runs"
          },
          "passRatePercent": {
            "type": "number",
            "description": "passes / runs × 100, one decimal.",
            "x-unit": "percent"
          },
          "inputTokensPerSolvedTask": {
            "type": "integer",
            "minimum": 0,
            "description": "Total input tokens (fresh, cache reads and cache writes) over all runs, divided by passes. Lower is better.",
            "x-unit": "tokens"
          }
        }
      },
      "FreshTaskModel": {
        "type": "object",
        "description": "OMS against the model's own lab harness, same model.",
        "required": [
          "model",
          "modelId",
          "comparisonHarness",
          "oms",
          "comparison",
          "matchedRuns",
          "inputTokensPerSolvedTaskDifferencePercent"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model name, for example GPT-6.1 Sol."
          },
          "modelId": {
            "type": "string",
            "description": "Model identifier used in the benchmark pack."
          },
          "comparisonHarness": {
            "type": "string",
            "description": "The model's own lab harness: Codex CLI or Claude Code."
          },
          "oms": {
            "$ref": "#/components/schemas/HarnessResult"
          },
          "comparison": {
            "$ref": "#/components/schemas/HarnessResult"
          },
          "matchedRuns": {
            "type": "object",
            "description": "Runs paired by task, run and batch, keeping only pairs where exactly one harness passed.",
            "required": [
              "omsOnlyPassed",
              "comparisonOnlyPassed",
              "signTestP"
            ],
            "properties": {
              "omsOnlyPassed": {
                "type": "integer",
                "minimum": 0,
                "description": "Pairs where only OMS passed.",
                "x-unit": "run pairs"
              },
              "comparisonOnlyPassed": {
                "type": "integer",
                "minimum": 0,
                "description": "Pairs where only the comparison harness passed.",
                "x-unit": "run pairs"
              },
              "signTestP": {
                "type": "number",
                "description": "Two-sided sign test p-value.",
                "x-unit": "p-value"
              }
            }
          },
          "inputTokensPerSolvedTaskDifferencePercent": {
            "type": "integer",
            "description": "Percent difference in input tokens per solved task, OMS against the comparison harness. Negative means OMS used fewer.",
            "x-unit": "percent"
          }
        }
      },
      "BenchScores": {
        "type": "object",
        "description": "Solana Bench scores for one harness in one environment.",
        "required": [
          "model",
          "runs",
          "meanScore",
          "medianScore",
          "minScore",
          "maxScore",
          "scores"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model the harness ran."
          },
          "runs": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of runs.",
            "x-unit": "runs"
          },
          "meanScore": {
            "type": "number",
            "description": "Mean score, one decimal. Higher is better.",
            "x-unit": "points"
          },
          "medianScore": {
            "type": "number",
            "description": "Median score.",
            "x-unit": "points"
          },
          "minScore": {
            "type": "integer",
            "minimum": 0,
            "description": "Lowest run score.",
            "x-unit": "points"
          },
          "maxScore": {
            "type": "integer",
            "minimum": 0,
            "description": "Highest run score.",
            "x-unit": "points"
          },
          "scores": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Per-run scores: distinct Solana instructions executed successfully on a mainnet fork.",
            "x-unit": "points"
          }
        }
      },
      "BenchEnvironment": {
        "type": "object",
        "description": "One Solana Bench environment.",
        "required": [
          "oms",
          "codexCli",
          "claudeCode",
          "permutationTestP"
        ],
        "properties": {
          "oms": {
            "$ref": "#/components/schemas/BenchScores"
          },
          "codexCli": {
            "$ref": "#/components/schemas/BenchScores"
          },
          "claudeCode": {
            "$ref": "#/components/schemas/BenchScores"
          },
          "permutationTestP": {
            "type": "number",
            "description": "Permutation test on the difference of means, OMS against Codex CLI.",
            "x-unit": "p-value"
          }
        }
      },
      "TokenUse": {
        "type": "object",
        "description": "Input token use in the Solana Bench basic environment.",
        "required": [
          "perRun",
          "perPoint"
        ],
        "properties": {
          "perRun": {
            "type": "integer",
            "minimum": 0,
            "description": "Mean total input tokens per run (fresh + cache), runs with complete token records.",
            "x-unit": "tokens"
          },
          "perPoint": {
            "type": "integer",
            "minimum": 0,
            "description": "Mean input tokens per run divided by mean score. Lower is better.",
            "x-unit": "tokens per point"
          }
        }
      },
      "FieldNote": {
        "type": "object",
        "required": [
          "unit",
          "description"
        ],
        "properties": {
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "Unit of the field, or null for objects."
          },
          "description": {
            "type": "string",
            "description": "What the field measures."
          }
        }
      },
      "Benchmarks": {
        "type": "object",
        "description": "Oh My Sol benchmark figures, as published on https://barestate.xyz/oh-my-sol.",
        "required": [
          "product",
          "description",
          "source",
          "documentation",
          "methodology",
          "freshTasks",
          "solanaBench",
          "fields"
        ],
        "properties": {
          "product": {
            "type": "string",
            "description": "Product the figures are for."
          },
          "description": {
            "type": "string",
            "description": "One-line summary of the data."
          },
          "source": {
            "type": "string",
            "format": "uri",
            "description": "Page where the figures are published."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "Benchmark documentation."
          },
          "methodology": {
            "type": "string",
            "format": "uri",
            "description": "How the tasks were built and how pass or fail was decided."
          },
          "freshTasks": {
            "type": "object",
            "description": "Pass rates on eight offline tasks that need Solana facts newer than the models' training data.",
            "required": [
              "description",
              "taskCount",
              "models"
            ],
            "properties": {
              "description": {
                "type": "string",
                "description": "What the fresh tasks measure."
              },
              "taskCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Number of distinct tasks.",
                "x-unit": "tasks"
              },
              "models": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FreshTaskModel"
                },
                "description": "One entry per model."
              }
            }
          },
          "solanaBench": {
            "type": "object",
            "description": "Solana Bench results for the round-16 OMS build.",
            "required": [
              "description",
              "environments",
              "basicInputTokens"
            ],
            "properties": {
              "description": {
                "type": "string",
                "description": "What Solana Bench measures and how the runs were set up."
              },
              "environments": {
                "type": "object",
                "required": [
                  "basic",
                  "swap"
                ],
                "properties": {
                  "basic": {
                    "$ref": "#/components/schemas/BenchEnvironment"
                  },
                  "swap": {
                    "$ref": "#/components/schemas/BenchEnvironment"
                  }
                },
                "description": "Results per environment."
              },
              "basicInputTokens": {
                "type": "object",
                "required": [
                  "oms",
                  "codexCli"
                ],
                "properties": {
                  "oms": {
                    "$ref": "#/components/schemas/TokenUse"
                  },
                  "codexCli": {
                    "$ref": "#/components/schemas/TokenUse"
                  }
                },
                "description": "Input token use, basic environment."
              }
            }
          },
          "fields": {
            "type": "object",
            "description": "Glossary: a unit and description for each figure, keyed by its path in this response.",
            "additionalProperties": {
              "$ref": "#/components/schemas/FieldNote"
            }
          }
        }
      }
    }
  }
}