{
  "openapi": "3.1.0",
  "info": {
    "title": "MCUPort Account API",
    "version": "1.0.0",
    "summary": "Account and licensing API for your own scripts and AI agents. Does not talk to any microcontroller.",
    "description": "Every endpoint authenticates with a per-customer API key (`Authorization: Bearer mcup_sk_...`) created at https://mcuport.com/account#agent-access. A key acts AS the account: it sees only that account's own data (email, Pro entitlement, license keys). Rate limit: 300 calls per key per hour. The same jobs are available as MCP tools at https://mcuport.com/mcp and from the `mcuport` CLI (`npx mcuport --help`). Setup guide: https://mcuport.com/docs/agents. This API has no checkout or webhook endpoint by design: buying Pro always happens in a browser at https://mcuport.com/pricing. The DEVICE MCP server (list_boards, flash_firmware, GPIO/I2C/SPI, ...) is a separate local stdio process; GET /api/v1/version returns its latest version and install instructions.",
    "termsOfService": "https://mcuport.com/terms",
    "contact": { "name": "MCUPort support", "email": "support@mcuport.com", "url": "https://mcuport.com/terms" }
  },
  "servers": [{ "url": "https://mcuport.com" }],
  "security": [{ "apiKey": [] }],
  "tags": [
    { "name": "account", "description": "Identity and entitlement for the account this key belongs to." },
    { "name": "license", "description": "Verify a Pro license key." },
    { "name": "version", "description": "Latest device MCP server version and install instructions." }
  ],
  "paths": {
    "/api/v1/me": {
      "get": {
        "tags": ["account"],
        "operationId": "getMe",
        "summary": "Who this key belongs to, Pro status, and recent agent calls",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/entitlement": {
      "get": {
        "tags": ["account"],
        "operationId": "getEntitlement",
        "summary": "Full Pro entitlement / license detail for this account",
        "description": "Whether Pro is active, every source that granted it, and every license key on the account with its active/revoked status. Includes upgradeUrl when Pro is not active and checkout is currently enabled; never starts a purchase.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlement" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/license/verify": {
      "post": {
        "tags": ["license"],
        "operationId": "verifyLicenseKey",
        "summary": "Verify any MCUPort Pro license key",
        "description": "Checks whether a key is minted, not revoked, and owned by a live account. Works for any key, not only this caller's own.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["key"], "properties": { "key": { "type": "string", "example": "MCUP-...." } } } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": ["key", "valid"], "properties": { "key": { "type": "string" }, "valid": { "type": "boolean" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/version": {
      "get": {
        "tags": ["version"],
        "operationId": "getLatestVersion",
        "summary": "Latest desktop (device-side) MCP server version and install instructions",
        "description": "This endpoint and the account API never talk to a board. It only reports the current server/package.json version and how to install/register it.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestVersion" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "mcup_sk_<40 hex>",
        "description": "Create and revoke keys at https://mcuport.com/account#agent-access."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, unknown or revoked key. Carries `WWW-Authenticate: Bearer realm=\"mcuport\"`.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "BadRequest": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "300 calls per key per hour exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "docs": { "type": "string" }, "createKeyAt": { "type": "string" } } },
      "Me": {
        "type": "object",
        "required": ["email", "accountCreatedAt", "pro", "key"],
        "properties": {
          "email": { "type": "string" },
          "accountCreatedAt": { "type": "string" },
          "pro": { "type": "boolean" },
          "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": ["read", "write"] } } } },
          "recentCalls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "action": { "type": "string" },
                "ok": { "type": "boolean" },
                "duration_ms": { "type": "integer" },
                "created_at": { "type": "string" }
              }
            }
          }
        }
      },
      "Entitlement": {
        "type": "object",
        "required": ["pro", "sources", "checkedAt", "licenses"],
        "properties": {
          "pro": { "type": "boolean" },
          "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": ["stripe", "apple", "google"] }, "grantedAt": { "type": "string" }, "environment": { "type": ["string", "null"] } } } },
          "checkedAt": { "type": "string" },
          "licenses": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "status": { "type": "string", "enum": ["active", "revoked"] }, "createdAt": { "type": "string" } } } },
          "upgradeUrl": { "type": ["string", "null"] }
        }
      },
      "LatestVersion": {
        "type": "object",
        "required": ["product", "version", "transport", "install", "docs"],
        "properties": {
          "product": { "type": "string" },
          "version": { "type": "string" },
          "transport": { "type": "string", "enum": ["stdio"] },
          "install": { "type": "object", "properties": { "npm": { "type": "string" }, "sourceBuild": { "type": "string" }, "claudeCodeCommand": { "type": "string" } } },
          "docs": { "type": "string" },
          "note": { "type": "string" }
        }
      }
    }
  }
}