{
  "openapi": "3.1.0",
  "info": {
    "title": "dledex creators API",
    "version": "1.0.0",
    "summary": "Look up, list and verify a daily browser game on dledex, and get its optional score badge.",
    "description": "dledex (https://dledex.com) is a free directory of daily browser games like Wordle. A game's creator, or a tool working for them, can look a game up, submit it for listing, prove the site is theirs with an HTML meta tag or a file, and copy the optional score badge. Listing is free. Every submission goes through the same review. Verification needs no account; a creator who signs in later and claims the game gets its numbers and can answer comments (https://dledex.com/creators). The badge is optional: nothing on dledex depends on it, and nothing is given for it. Step-by-step guide: https://dledex.com/creators.md",
    "contact": { "url": "https://dledex.com/creators" }
  },
  "servers": [{ "url": "https://dledex.com" }],
  "paths": {
    "/api/lookup": {
      "get": {
        "operationId": "lookupGame",
        "summary": "Is this game listed?",
        "description": "Finds a game by the URL it is played at. Listed: its dledex page and the badge snippets. Pending: submitted and in review. Not listed: not found (sameSite lists other dledex games on that site). Limit: 20 requests a minute per IP.",
        "parameters": [{ "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "example": "https://example.com/my-daily-game" }],
        "responses": {
          "200": {
            "description": "The game's status on dledex.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lookup" } } }
          },
          "400": { "$ref": "#/components/responses/Invalid" },
          "429": { "$ref": "#/components/responses/Limited" }
        }
      }
    },
    "/api/agent/submit": {
      "post": {
        "operationId": "submitGame",
        "summary": "Submit a game for listing",
        "description": "The game's URL is all it takes: the review finds the name, category and description on the page, checks that it is a daily game that loads, and looks for duplicates; most games are added within a few days. Limits: 3 a minute per IP, 3 a day per site, 100 a day in all.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlBody" } } } },
        "responses": {
          "201": { "description": "Received; the review has started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Submitted" } } } },
          "200": { "description": "Already submitted (duplicate: true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Submitted" } } } },
          "400": { "$ref": "#/components/responses/Invalid" },
          "429": { "$ref": "#/components/responses/Limited" }
        }
      }
    },
    "/api/submissions/{id}": {
      "get": {
        "operationId": "submissionStatus",
        "summary": "Where a submission stands",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": {
            "description": "in_review, approved (live after the next update), listed, duplicate, rejected or closed; slug once known.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["in_review", "approved", "listed", "duplicate", "rejected", "closed"] }, "slug": { "type": ["string", "null"] } } } } }
          },
          "404": { "description": "Unknown id." }
        }
      }
    },
    "/api/verify/start": {
      "post": {
        "operationId": "startVerification",
        "summary": "Get the site's verification code",
        "description": "For a site with a listed or submitted game. Put the meta tag in the <head> of the site's start page (or of the game's page), or the code alone in /.well-known/dledex.txt, then call /api/verify/check. The same code is returned on every call. Limit: 20 requests a minute per IP.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlBody" } } } },
        "responses": {
          "200": { "description": "The code and where it goes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyStart" } } } },
          "400": { "$ref": "#/components/responses/Invalid" },
          "404": { "description": "unknown_site: no game of this site is listed or submitted yet." },
          "429": { "$ref": "#/components/responses/Limited" }
        }
      }
    },
    "/api/verify/check": {
      "post": {
        "operationId": "checkVerification",
        "summary": "Check for the code on the site",
        "description": "Looks for the code on the site's start page, the given page and /.well-known/dledex.txt. Verified, the site's listed games count as verified by their creator from the next update on (twice a day). A site can be checked once every 15 seconds.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlBody" } } } },
        "responses": {
          "200": { "description": "verified: true or false.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "host": { "type": "string" }, "games": { "type": "array", "items": { "type": "string" } } } } } } },
          "404": { "description": "not_started: call /api/verify/start first." },
          "429": { "$ref": "#/components/responses/Limited" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UrlBody": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "description": "Where the game is played, e.g. https://example.com/my-daily-game" } } },
      "Lookup": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "status": { "type": "string", "enum": ["listed", "pending", "not_listed"] },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "page": { "type": "string", "description": "The game's page on dledex." },
          "verified": { "type": "boolean", "description": "Verified by its creator (an account's claim or the site's code)." },
          "review": { "type": "string", "description": "Pending only: in_review or approved." },
          "badge": {
            "type": "object",
            "description": "Optional score badge, live from dledex: an image in a plain link to the game's page. Nothing on dledex depends on it.",
            "properties": { "optional": { "type": "boolean" }, "image": { "type": "string" }, "html": { "type": "string" }, "styles": { "type": "object", "additionalProperties": { "type": "string" } } }
          },
          "sameSite": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "page": { "type": "string" } } } }
        }
      },
      "Submitted": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "duplicate": { "type": "boolean" }, "status": { "type": "string" }, "statusUrl": { "type": "string" } } },
      "VerifyStart": {
        "type": "object",
        "properties": {
          "host": { "type": "string" },
          "token": { "type": "string" },
          "verified": { "type": "boolean" },
          "meta": { "type": "string", "description": "<meta name=\"dledex-verification\" content=\"…\">" },
          "file": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } } },
          "check": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "body": { "type": "object" } } }
        }
      }
    },
    "responses": {
      "Invalid": { "description": "invalid: not a full public http(s) URL." },
      "Limited": { "description": "rate_limited, site_limit or daily_limit: try again later." }
    }
  }
}
