{
  "openapi": "3.1.0",
  "info": {
    "title": "List Coder API",
    "version": "2.2.0",
    "description": "Official API for List Coder — the free AI-powered IDE with autonomous coding agents, Tab autocomplete, Composer multi-file editing, offline AI models, MCP server and CLI. Agents use this API to automate downloads, feedback, downloads verification, model listing and code generation workflows. All endpoints are typed, have unique operationIds and structured responses compatible with LLM function calling.\n\nVersioning: URL path versioning (/api/v1/, /api/v2/). Current stable is v1. Unversioned /api is deprecated and maps to v1 with `Deprecation: true` and `Sunset` headers. See `servers` and `x-deprecation-policy`.\n\nRate limiting: All /api responses include `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `Retry-After` on 429 (see response headers). Limits: 100 req/min per IP, documented at https://docs.list-coder.com/api/rate-limits.",
    "contact": {
      "name": "List Coder Support",
      "url": "https://list-coder.com/support",
      "email": "List-Enterprise@outlook.com"
    },
    "license": {
      "name": "Proprietary — free for personal and commercial use",
      "url": "https://list-coder.com/terms"
    },
    "termsOfService": "https://list-coder.com/terms",
    "x-versioning": {
      "strategy": "url-path",
      "current": "v1",
      "supported": ["v1"],
      "header": "API-Version"
    },
    "x-deprecation-policy": {
      "unversioned": "Deprecated since 2026-08-01, Sunset Sat, 31 Dec 2028 23:59:59 GMT — use /api/v1. Responses include Deprecation and Sunset headers.",
      "docs": "https://docs.list-coder.com/api/versioning"
    }
  },
  "servers": [
    { "url": "https://list-coder.com/api/v1", "description": "Production API v1 — versioned (recommended)" },
    { "url": "https://list-coder.com/api", "description": "Unversioned — deprecated, use /api/v1 (maps to v1 with Deprecation header)" },
    { "url": "https://docs.list-coder.com/api/v1", "description": "Docs API mirror v1" }
  ],
  "tags": [
    { "name": "health", "description": "Service health and discovery" },
    { "name": "download", "description": "List Coder binary downloads — IDE, Omni, CLI" },
    { "name": "models", "description": "Open-source models and leaderboard" },
    { "name": "feedback", "description": "Product feedback and support messages" },
    { "name": "auth", "description": "Authentication via GitHub and Google OAuth 2.0" },
    { "name": "composer", "description": "Composer multi-file editing session (agent)" },
    { "name": "tab", "description": "Tab autocomplete code completion" }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns service health, version and uptime. Use to verify API availability before other calls. Supports API-Version header versioning.",
        "tags": ["health"],
        "security": [],
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "API version, e.g. v1",
            "schema": { "type": "string", "enum": ["v1", "v2"], "example": "v1" }
          }
        ],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "headers": {
              "API-Version": { "description": "Effective API version", "schema": { "type": "string" } },
              "RateLimit-Limit": { "description": "Max requests per window", "schema": { "type": "integer" } },
              "RateLimit-Remaining": { "description": "Remaining requests", "schema": { "type": "integer" } },
              "RateLimit-Reset": { "description": "Seconds until reset", "schema": { "type": "integer" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "version", "uptime"],
                  "properties": {
                    "ok": { "type": "boolean", "example": true },
                    "version": { "type": "string", "example": "2.2.0" },
                    "uptime": { "type": "number", "description": "Uptime seconds", "example": 12345 }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": { "description": "Seconds to wait before retry", "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/download": {
      "get": {
        "operationId": "listDownloads",
        "summary": "List available downloads",
        "description": "Lists available List Coder builds grouped by product (ide, omni, cli) with version, platform, file size and direct GitHub release URL. No auth required. Scopes: read:downloads (when using OAuth).",
        "tags": ["download"],
        "security": [{ "oAuth2": ["read:downloads"] }, { "bearerAuth": [] }, {}],
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": false,
            "description": "Filter by product id",
            "schema": { "type": "string", "enum": ["ide", "omni", "cli"], "example": "omni" }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Filter by platform",
            "schema": { "type": "string", "enum": ["windows", "macos", "linux", "all"], "example": "windows" }
          },
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "schema": { "type": "string", "enum": ["v1"] },
            "description": "API version"
          }
        ],
        "responses": {
          "200": {
            "description": "List of downloads",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer" } },
              "RateLimit-Remaining": { "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } },
              "API-Version": { "schema": { "type": "string" } },
              "Deprecation": { "description": "True if unversioned endpoint", "schema": { "type": "string" } },
              "Sunset": { "description": "Deprecation sunset date for unversioned", "schema": { "type": "string" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["products"],
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ProductDownloads" }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": { "Retry-After": { "schema": { "type": "integer" } } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/download/{product}/{asset}": {
      "get": {
        "operationId": "getDownloadAsset",
        "summary": "Resolve a specific download asset",
        "description": "Resolves a single build asset to its direct download URL and verifies the GitHub release exists. Use for automated installs. Scope: read:downloads.",
        "tags": ["download"],
        "security": [{ "oAuth2": ["read:downloads"] }, {}],
        "parameters": [
          { "name": "product", "in": "path", "required": true, "schema": { "type": "string", "enum": ["ide", "omni", "cli"] }, "description": "Product id" },
          { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "example": "windows-x64" }, "description": "Asset key" }
        ],
        "responses": {
          "200": {
            "description": "Asset resolved",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer" } },
              "RateLimit-Remaining": { "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadAsset" } } }
          },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List open-source models",
        "description": "Lists List Cloud open-source models (e.g. List-3.0-Ultra-Coder-Brain 229B) with HF link. Scope: read:models.",
        "tags": ["models"],
        "security": [{ "oAuth2": ["read:models"] }, {}],
        "responses": {
          "200": {
            "description": "List of models",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer" } },
              "RateLimit-Remaining": { "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["models"],
                  "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }
                }
              }
            }
          },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/feedback": {
      "post": {
        "operationId": "submitFeedback",
        "summary": "Submit product feedback",
        "description": "Submits feedback. Rate limited. Scope: write:feedback (OAuth) or no auth but email required. On 429 includes Retry-After.",
        "tags": ["feedback"],
        "security": [{ "oAuth2": ["write:feedback"] }, {}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "subject", "message"],
                "properties": {
                  "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Ada Lovelace" },
                  "email": { "type": "string", "format": "email", "example": "ada@example.com" },
                  "subject": { "type": "string", "minLength": 1, "maxLength": 200, "example": "CLI install fails on Fedora" },
                  "message": { "type": "string", "minLength": 1, "maxLength": 5000, "example": "Steps to reproduce..." }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stored",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer" } },
              "RateLimit-Remaining": { "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } }
            },
            "content": { "application/json": { "schema": { "type": "object", "required": ["id", "ok"], "properties": { "id": { "type": "string" }, "ok": { "type": "boolean", "example": true } } } } }
          },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/auth/github": {
      "get": {
        "operationId": "startGitHubAuth",
        "summary": "Start GitHub OAuth",
        "description": "Redirects to GitHub OAuth. Supports OAuth 2.0 with PKCE (code_challenge) and scopes: openid, profile, email, read:downloads, etc. Discovery at /.well-known/oauth-authorization-server. Use source=cli|desktop for headless.",
        "tags": ["auth"],
        "security": [],
        "parameters": [
          { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": ["web", "cli", "desktop"] } },
          { "name": "callbackPort", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{4,5}$" } },
          { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "example": "openid profile email read:downloads" }, "description": "Space-delimited OAuth scopes" },
          { "name": "code_challenge", "in": "query", "required": false, "schema": { "type": "string" }, "description": "PKCE challenge" }
        ],
        "responses": {
          "302": { "description": "Redirect to GitHub authorize" },
          "400": { "description": "Invalid params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/auth/token": {
      "post": {
        "operationId": "exchangeToken",
        "summary": "Exchange code for token (OAuth 2.0)",
        "description": "OAuth 2.0 token endpoint. Exchanges authorization code (with PKCE) for access/id tokens. See /.well-known/oauth-authorization-server. Scopes: openid, profile, email, read:*, write:*.",
        "tags": ["auth"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["grant_type", "code"],
                "properties": {
                  "grant_type": { "type": "string", "enum": ["authorization_code", "refresh_token", "client_credentials"] },
                  "code": { "type": "string" },
                  "redirect_uri": { "type": "string", "format": "uri" },
                  "client_id": { "type": "string" },
                  "code_verifier": { "type": "string", "description": "PKCE verifier" },
                  "scope": { "type": "string", "example": "openid profile email" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tokens",
            "headers": { "RateLimit-Limit": { "schema": { "type": "integer" } } },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["access_token", "token_type", "expires_in"],
                  "properties": {
                    "access_token": { "type": "string" },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "expires_in": { "type": "integer", "example": 3600 },
                    "refresh_token": { "type": "string" },
                    "scope": { "type": "string", "example": "openid profile email read:downloads" },
                    "id_token": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/composer/session": {
      "post": {
        "operationId": "createComposerSession",
        "summary": "Create a Composer multi-file session",
        "description": "Creates a Composer session. Requires write:composer scope. Auth via OAuth2 or Bearer JWT. Mirrors /composer.",
        "tags": ["composer"],
        "security": [{ "oAuth2": ["write:composer"] }, { "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt", "files"],
                "properties": {
                  "prompt": { "type": "string", "example": "Refactor auth to use httpOnly cookies" },
                  "files": { "type": "array", "items": { "type": "string" } },
                  "mode": { "type": "string", "enum": ["edit", "plan"], "default": "edit" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session created",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer" } },
              "RateLimit-Remaining": { "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } }
            },
            "content": { "application/json": { "schema": { "type": "object", "required": ["sessionId", "status"], "properties": { "sessionId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["queued", "running"] }, "workspace": { "type": "string" } } } } }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/tab/complete": {
      "post": {
        "operationId": "tabComplete",
        "summary": "Tab autocomplete",
        "description": "Context-aware Tab completion. Requires read:tab scope. Give prefix/suffix/language; get edit + latency. Same engine as /tab.",
        "tags": ["tab"],
        "security": [{ "oAuth2": ["read:tab"] }, { "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["language", "prefix", "suffix"],
                "properties": {
                  "language": { "type": "string", "example": "typescript" },
                  "prefix": { "type": "string", "example": "function sum(a, b) {\n  " },
                  "suffix": { "type": "string", "example": "\n}" },
                  "filePath": { "type": "string", "example": "src/math.ts" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completion",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "integer" } },
              "RateLimit-Remaining": { "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } }
            },
            "content": { "application/json": { "schema": { "type": "object", "required": ["completion", "latencyMs"], "properties": { "completion": { "type": "string", "example": "return a + b;" }, "latencyMs": { "type": "integer", "example": 47 }, "model": { "type": "string", "example": "List-3.0-Ultra-Coder-Brain" } } } } }
          },
          "400": { "description": "Invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Firebase ID token via Authorization: Bearer <token> — legacy, prefer oAuth2"
      },
      "oAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 with named scopes for least-privilege. Discovery at /.well-known/oauth-authorization-server. Scopes: read:*, write:*, openid, profile, email.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://list-coder.com/auth/authorize",
            "tokenUrl": "https://list-coder.com/auth/token",
            "scopes": {
              "openid": "OpenID Connect — get ID token",
              "profile": "User profile (name)",
              "email": "User email",
              "read:downloads": "List available downloads",
              "read:models": "List open-source models",
              "read:health": "Health check",
              "write:feedback": "Submit feedback",
              "write:composer": "Create Composer sessions",
              "read:tab": "Use Tab autocomplete"
            }
          },
          "clientCredentials": {
            "tokenUrl": "https://list-coder.com/auth/token",
            "scopes": {
              "read:downloads": "List available downloads",
              "read:models": "List open-source models",
              "read:health": "Health check",
              "write:feedback": "Submit feedback"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string", "example": "not_found" },
          "message": { "type": "string", "example": "Product 'foo' not found" },
          "hint": { "type": "string", "example": "See /sitemap.xml or /llms.txt" }
        }
      },
      "ProductDownloads": {
        "type": "object",
        "required": ["id", "name", "assets"],
        "properties": {
          "id": { "type": "string", "enum": ["ide", "omni", "cli"], "example": "omni" },
          "name": { "type": "string", "example": "List Coder Omni" },
          "version": { "type": "string", "example": "2.2.0" },
          "assets": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadAsset" } }
        }
      },
      "DownloadAsset": {
        "type": "object",
        "required": ["key", "name", "url", "platform"],
        "properties": {
          "key": { "type": "string", "example": "windows-x64" },
          "name": { "type": "string", "example": "Windows (x64) .exe" },
          "url": { "type": "string", "format": "uri", "example": "https://github.com/legitey01/list-coder-omni-releases/releases/download/v2.2.0/List-Coder-Omni-2.2.0-win-x64.exe" },
          "platform": { "type": "string", "enum": ["windows", "macos", "linux"], "example": "windows" },
          "size": { "type": "integer", "example": 98765432 },
          "sha256": { "type": "string", "example": "e3b0c44298fc1c149afbf4c8996fb924..." }
        }
      },
      "Model": {
        "type": "object",
        "required": ["name", "provider", "params", "url"],
        "properties": {
          "name": { "type": "string", "example": "List-3.0-Ultra-Coder-Brain" },
          "provider": { "type": "string", "example": "List Cloud" },
          "params": { "type": "string", "example": "229B" },
          "description": { "type": "string", "example": "Flagship 229B model" },
          "url": { "type": "string", "format": "uri", "example": "https://huggingface.co/List-cloud/List-3.0-Ultra-Coder-Brain" }
        }
      }
    }
  }
}