{"openapi":"3.1.1","info":{"title":"Cockpit API","version":"1.0.0","description":"Public website integration API: discovery, desktop license activation and app-login exchange. This is not the local mission API. For local automation read /docs/api-e-websocket; for authorized remote agents use MCP at /mcp.","contact":{"url":"https://cockpit.vep.sh/contact"}},"servers":[{"url":"/","description":"Same origin as this specification"}],"externalDocs":{"url":"https://cockpit.vep.sh/docs/api","description":"Cockpit API and MCP onboarding"},"security":[],"paths":{"/api":{"get":{"operationId":"getCockpitApi","summary":"Discover Cockpit integrations","description":"Returns official documentation, OpenAPI, MCP and registration links. No authentication required.","responses":{"200":{"description":"Integration links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discovery"}}}}}}},"/api/v1/license":{"post":{"operationId":"activateCockpitLicense","summary":"Activate or renew a desktop license","description":"Activates a device using a license key from /painel. The first activation starts the free trial. Renewal uses the same operation. Limited to 120 requests per IP per hour. This operation changes device registration and can start the trial; ask the account owner before first activation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseRequest"}}}},"responses":{"200":{"description":"Device-bound license.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/License"}}}},"400":{"description":"Invalid key format or device ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Revoked key, inactive entitlement or device limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}}}}}},"/api/v1/app-login":{"post":{"operationId":"exchangeCockpitAppLogin","summary":"Poll an approved desktop login","description":"Polls a login initiated by the desktop application. The user must approve the login in their browser. Poll every two seconds for up to ten minutes. The secret proves possession; no session cookie required. The ready key is returned only once. Limits: 400 requests per secret and 3000 per IP per hour.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppLoginRequest"}}}},"responses":{"200":{"description":"Approved login; key returned once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginReady"}}}},"202":{"description":"Waiting for approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginPending"}}}},"400":{"description":"Invalid secret format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Expired, consumed or invalid login flow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Stable error code retained for existing clients."},"code":{"type":"string","description":"Stable error code, identical to error."},"message":{"type":"string","description":"Human-readable explanation."},"resolution":{"type":"string","description":"How to resolve the error."}},"required":["error","code","message","resolution"]},"LicenseRequest":{"type":"object","properties":{"key":{"type":"string","description":"License key generated by the account owner in /painel. Never include in logs.","writeOnly":true},"deviceId":{"type":"string","description":"Stable device identifier, trimmed to 128 characters.","minLength":16},"label":{"type":"string","description":"Optional device name, trimmed to 80 characters."},"appVersion":{"type":"string","description":"Optional desktop version, trimmed to 40 characters."}},"required":["key","deviceId"]},"License":{"type":"object","properties":{"license":{"type":"string","description":"Signed Ed25519 license token for this device."},"plan":{"type":"string","description":"Effective account plan."},"expiresAt":{"type":"integer","description":"Expiry as Unix seconds."},"graceUntil":{"type":"integer","description":"Grace deadline as Unix seconds."}},"required":["license","plan","expiresAt","graceUntil"]},"AppLoginRequest":{"type":"object","properties":{"secret":{"type":"string","description":"Secret created by the desktop login flow; never generate a replacement while polling.","pattern":"^[A-Za-z0-9_-]{43}$","writeOnly":true},"label":{"type":"string","description":"Optional device label, trimmed to 40 characters."}},"required":["secret"]},"LoginPending":{"type":"object","properties":{"state":{"type":"string","const":"pending","description":"The account owner has not yet approved this login."}},"required":["state"]},"LoginReady":{"type":"object","properties":{"state":{"type":"string","const":"ready"},"key":{"type":"string","description":"New license key returned only once; store securely."}},"required":["state","key"]},"Discovery":{"type":"object","properties":{"name":{"type":"string","description":"API name."},"documentation":{"type":"string","description":"Human-readable API guide path."},"openapi":{"type":"string","description":"OpenAPI specification path."},"mcp":{"type":"string","description":"Remote MCP endpoint path."},"onboarding":{"type":"string","description":"Self-serve registration path."}},"required":["name","documentation","openapi","mcp","onboarding"]}}}}