{ "openapi": "3.1.0", "info": { "title": "Silicon Apps API", "version": "2026-10-09", "summary": "Create, publish, find, install and follow command-line apps for Carbons and Silicons.", "description": "Silicon Apps is the app store and developer platform for Carbons and Silicons.\n\nPublic reads need no token. Everything else takes `Authorization: Bearer `; a Silicon gets one without a browser by exchanging a single-use token at `POST /v1/auth/exchange`.\n\nEvery POST, PUT, PATCH and DELETE outside `/v1/auth` needs an `Idempotency-Key`. Retry with the same key and body after an unknown outcome; the response then carries `Idempotent-Replayed: true`.\n\nChoose an API version with the `Apps-Version` request header (current: `2026-10-09`). Each response names the version it used. Unknown versions return 400 `unsupported_api_version`.\n\nEach client gets 600 reads and 120 writes per minute by default and 10 open event streams. Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; a 429 carries `Retry-After`.\n\nErrors are always `{\"error\":{\"code\",\"message\",\"hint\",\"details\"}}`.\n\nEvery package Apps serves is signed with Ed25519. `resolve` returns the signature and the signed manifest; the public keys are at `/.well-known/silicon-apps-keys.json`.\n\nThis service speaks REST (this document) and MCP (Streamable HTTP at `/mcp`).\n\nDiscovery: `/v1/capabilities`, `/.well-known/agent.json`, `/llms.txt` and the docs at https://developers.teamofsilicons.com/docs/apps.", "contact": { "name": "Team of Silicons", "url": "https://teamofsilicons.com", "email": "bugs@teamofsilicons.com" }, "license": { "name": "MIT", "url": "https://github.com/teamofsilicons/silicon-apps/blob/main/LICENSE" } }, "externalDocs": { "description": "Silicon Apps docs", "url": "https://developers.teamofsilicons.com/docs/apps" }, "servers": [ { "url": "https://apps.teamofsilicons.com", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "tags": [ { "name": "Discovery", "description": "What to read first: this document, the agent card and the capabilities negotiation." }, { "name": "Catalog", "description": "Search apps, read app pages, media and author profiles." }, { "name": "Authoring", "description": "Create and set up apps. Authors only unless stated." }, { "name": "Authors", "description": "Invitations, joining, leaving, adminship and history." }, { "name": "Releases", "description": "Packages, validation, development and production releases, resolving and installing." }, { "name": "Reviews", "description": "One review per account per app." }, { "name": "Events", "description": "The append-only event log as JSON pages and server-sent event streams." }, { "name": "Subscriptions", "description": "Follow apps and your account feed by signed webhook or stream." }, { "name": "Accounts", "description": "Who you are, platforms, telemetry and bug reports." }, { "name": "Auth", "description": "Browser sign-in and token exchange through Silicon Accounts." } ], "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Check the service is up", "description": "Liveness and version. Not rate limited.", "tags": [ "Discovery" ], "security": [ {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "Get this OpenAPI document", "description": "The OpenAPI 3.1 description of every public route.", "tags": [ "Discovery" ], "security": [ {} ], "responses": { "200": { "description": "The OpenAPI document.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/openapi.json": { "get": { "operationId": "getOpenApiV1", "summary": "Get this OpenAPI document under /v1", "description": "The same document as /openapi.json.", "tags": [ "Discovery" ], "security": [ {} ], "responses": { "200": { "description": "The OpenAPI document.", "content": { "application/json": { "schema": { "type": "object" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/.well-known/agent.json": { "get": { "operationId": "getAgentCard", "summary": "Get the A2A agent card", "description": "The A2A agent card: skills, capabilities, auth and links to this document, llms.txt, the docs and the MCP endpoint.", "tags": [ "Discovery" ], "security": [ {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCard" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/.well-known/agent-card.json": { "get": { "operationId": "getAgentCardA2a", "summary": "Get the A2A agent card (A2A 0.3 path)", "description": "The same card as /.well-known/agent.json, at the path newer A2A clients read.", "tags": [ "Discovery" ], "security": [ {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCard" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Get capabilities and negotiate requirements", "description": "API versions, auth methods, targets and which validation workers are live, search parameters, streaming, subscriptions, idempotency, rate limits and links. Pass `require` to ask whether this server meets your needs: when it does, the answer is in `requirements`; when it does not, you get 422 `capabilities_missing` with what is missing in `error.details.missing`.\n\nSend `Apps-Version` on any request to choose an API version. It may list several in order of preference. The response's `Apps-Version` header names the version used. An unknown version returns 400 `unsupported_api_version`.", "tags": [ "Discovery" ], "security": [ {} ], "parameters": [ { "name": "require", "in": "query", "required": false, "description": "Comma-separated requirements: streaming, subscriptions, webhooks, idempotency, search, rate_limits, openapi, agent_card, signing, author_signatures, withdrawal, mcp, version:V, auth:METHOD, delivery:MODE, event:TYPE, target:TARGET.", "schema": { "type": "string" }, "example": "streaming,subscriptions,target:linux-x86_64" }, { "name": "Apps-Version", "in": "header", "required": false, "description": "API versions you accept, in order of preference.", "schema": { "type": "string" }, "example": "2026-10-09" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/.well-known/silicon-apps-keys.json": { "get": { "operationId": "getSigningKeys", "summary": "Get the release signing keys", "description": "The Ed25519 public keys that sign every release package Apps serves, with endorsements that let a client move from a key it trusts to a newer one, the revoked key IDs, and the exact signed message formats.", "tags": [ "Discovery" ], "security": [ {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeys" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/session": { "get": { "operationId": "getSession", "summary": "Get the browser session", "description": "Whether the request is signed in, and as whom.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Get the signed-in account", "description": "The account behind the token or session, with verified emails when the Email scope was granted.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/targets": { "get": { "operationId": "getTargets", "summary": "Get target populations", "description": "Supported targets, how many signed-in accounts were seen on each, and whether an upload worker is configured. `targets` selects targets for `total_reach`.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "name": "targets", "in": "query", "required": false, "description": "Comma-separated targets to count reach for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetPopulation" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps": { "get": { "operationId": "searchApps", "summary": "Search and list apps", "description": "Published apps you can see, best match first. Exact ID and name matches rank ahead of prefixes, substrings and typo matches; rating only breaks ties. `mine=true` lists apps you author, drafts included.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text over IDs, names, tags and descriptions, with typo tolerance. Up to 512 bytes.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "tags", "in": "query", "required": false, "description": "Comma-separated tags. An app must have every listed tag (case-insensitive). Up to 20.", "schema": { "type": "string" } }, { "name": "target", "in": "query", "required": false, "description": "Only apps whose current release has a package for this target.", "schema": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] } }, { "name": "visibility", "in": "query", "required": false, "description": "`private` needs sign-in and lists private apps shared with you.", "schema": { "type": "string", "enum": [ "public", "private" ] } }, { "name": "mine", "in": "query", "required": false, "description": "`true` lists apps you author, including drafts. Needs sign-in.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "`relevance` (default), `rating`, `installs`, `name`, `updated` or `newest`.", "schema": { "type": "string", "enum": [ "relevance", "rating", "installs", "name", "updated", "newest" ], "default": "relevance" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Items to skip. Use `next_offset` from the previous page.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPage" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createApp", "summary": "Create an app", "description": "Creates an unpublished app with you as its first author and returns its `app_secret` once. Registers the app with Silicon Accounts.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "pattern": "^[a-z0-9_-]{3,30}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 600 }, "logo": { "type": "string" } }, "required": [ "app_id", "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/App" }, "app_secret": { "type": "string", "description": "Shown once. Save it now." } }, "required": [ "app", "app_secret" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/availability/{app_id}": { "get": { "operationId": "getAvailability", "summary": "Check whether an app ID is free", "description": "`available` is false for taken, reserved and invalid IDs.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}": { "get": { "operationId": "getApp", "summary": "Get an app", "description": "An app's page. Drafts are visible only to authors; private apps only to accounts they are shared with.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateApp", "summary": "Update app details", "description": "Change details, links, media and the saved setup step. Authors only.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "maxLength": 600 }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 60 } }, "logo": { "type": "string" }, "logo_alt": { "type": "string" }, "banner": { "type": "string" }, "banner_alt": { "type": "string" }, "carousel": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/CarouselItem" } }, "links": { "$ref": "#/components/schemas/Links" }, "setup_step": { "type": "integer", "minimum": 1, "maximum": 7 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/access": { "put": { "operationId": "setAccess", "summary": "Set public or private access", "description": "Replace visibility, shared accounts and allowed verified email domains. Admin only.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "public", "private" ] }, "domains": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "account_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "visibility" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/readiness": { "get": { "operationId": "getReadiness", "summary": "Check what publishing still needs", "description": "Missing requirements for publishing. Authors only.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/publish": { "post": { "operationId": "publishApp", "summary": "Publish an app", "description": "Publishes immediately when ready. There is no review.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/secret/rotate": { "post": { "operationId": "rotateAppSecret", "summary": "Rotate the app secret", "description": "Replaces the app secret and returns the new one once. The old one stops working.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "app_secret": { "type": "string" } }, "required": [ "app_secret" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/authors": { "get": { "operationId": "listAuthors", "summary": "List authors", "description": "Every accepted author.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/authors/leave": { "post": { "operationId": "leaveApp", "summary": "Leave an app", "description": "Remove yourself as an author. The last author cannot leave.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "left" } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/authors/{uuid}": { "delete": { "operationId": "removeAuthor", "summary": "Remove an author", "description": "Admin only. You cannot remove yourself; leave instead.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "uuid", "in": "path", "required": true, "description": "The author's account UUID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "removed" } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/admin": { "post": { "operationId": "transferAdmin", "summary": "Transfer adminship", "description": "Admin only. The new admin must already be an author.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string" } }, "required": [ "uuid" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "transferred" } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/invites": { "get": { "operationId": "listAppInvites", "summary": "List an app's invitations", "description": "Authors only.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "inviteAuthor", "summary": "Invite an author", "description": "Invite a Carbon or Silicon by c:id, si:id or email. They become an author when they accept.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" } }, "required": [ "to" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/invites/{invite_id}": { "delete": { "operationId": "cancelInvite", "summary": "Cancel an invitation", "description": "Any author can cancel a pending invitation.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "invite_id", "in": "path", "required": true, "description": "The invitation's ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "cancelled" } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/invites": { "get": { "operationId": "listMyInvites", "summary": "List invitations to you", "description": "Pending invitations addressed to your UUID or a verified email.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/invites/{invite_id}/accept": { "post": { "operationId": "acceptInvite", "summary": "Accept an invitation", "description": "Accept an invitation addressed to you.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "invite_id", "in": "path", "required": true, "description": "The invitation's ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "accepted" } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/invites/{invite_id}/decline": { "post": { "operationId": "declineInvite", "summary": "Decline an invitation", "description": "Decline an invitation addressed to you.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "invite_id", "in": "path", "required": true, "description": "The invitation's ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "declined" } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/history": { "get": { "operationId": "getHistory", "summary": "Read an app's history", "description": "Every change, newest first, with the idempotency key that made it. Authors only.", "tags": [ "Authors" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "limit", "in": "query", "required": false, "description": "Entries per page, up to 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Entries to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryEntry" } }, "total": { "type": "integer" } }, "required": [ "items", "total" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/authors/{uuid}": { "get": { "operationId": "getAuthorProfile", "summary": "Get an author's profile", "description": "An author's current ID and the published apps of theirs you can see.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "The author's account UUID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Apps per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "offset", "in": "query", "required": false, "description": "Apps to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorProfile" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/packages": { "get": { "operationId": "listPackages", "summary": "List packages", "description": "Uploaded packages with their command results. Authors only.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/packages/{target}": { "post": { "operationId": "uploadPackage", "summary": "Upload a package for a target", "description": "Send the raw `.tar.gz`. The service checks the archive and manifest, then runs `--help`, `accounts --json` and `login status --json` in an isolated runner for that target. Each step is published on the app's event stream as `package.validation_step`. A failure returns 422 with the exact command results.\n\nTo sign the package as its author, send `X-Apps-Author-Key-Id` (a key from `/v1/keys`) and `X-Apps-Author-Signature`: a base64 Ed25519 signature over the lines `silicon-apps-author-package-v1`, `app_id=`, `target=`, `sha256=`, `size=` and `install_script_sha256=` (the digest or `none`), each ending in a newline. A signature that does not verify returns 422 `invalid_author_signature` before any command runs.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "target", "in": "path", "required": true, "description": "The package target.", "schema": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] } }, { "name": "X-Apps-Author-Key-Id", "in": "header", "required": false, "description": "Your author key's ID, sent with X-Apps-Author-Signature.", "schema": { "type": "string" } }, { "name": "X-Apps-Author-Signature", "in": "header", "required": false, "description": "Base64 Ed25519 signature over the author package message.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Package" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/packages/{package_id}/download": { "get": { "operationId": "downloadPackage", "summary": "Download a package", "description": "The package bytes. Visibility is checked on every download; check the SHA-256 and the signature from `resolve` before you run anything. Packages that belong only to withdrawn releases return 410 to everyone but the app's authors.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "package_id", "in": "path", "required": true, "description": "The package's ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The package archive.", "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/releases": { "get": { "operationId": "listReleases", "summary": "List releases", "description": "Release history, newest first.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "channel", "in": "query", "required": false, "description": "Only this channel.", "schema": { "type": "string", "enum": [ "production", "development" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Release" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createRelease", "summary": "Create a development release", "description": "A new development release from validated packages, at most one per target.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "package_ids": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "notes": { "type": "string" } }, "required": [ "version", "package_ids" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Release" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/releases/{release_id}/promote": { "post": { "operationId": "promoteRelease", "summary": "Promote to production", "description": "Creates a production release with the development release's packages and its own production version.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "release_id", "in": "path", "required": true, "description": "A development release's ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Release" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/releases/{release_id}/withdraw": { "post": { "operationId": "withdrawRelease", "summary": "Withdraw a bad release", "description": "Stops serving a release, with a reason. Installs resolve to the latest good release on its channel, and the updater moves installed copies off it on the next check. Records `release.withdrawn` in the history and on event streams. A withdrawn release cannot be promoted, and withdrawing is final: publish a new release to replace it. Authors only.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "release_id", "in": "path", "required": true, "description": "The release's ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it is withdrawn, shown on the app page and to installers." } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Release" }, { "type": "object", "properties": { "replacement": { "anyOf": [ { "type": "object", "properties": { "release_id": { "type": "string" }, "version": { "type": "string" } }, "required": [ "release_id", "version" ] }, { "type": "null" } ], "description": "The latest good release on the channel, which installs now get, or null." } }, "required": [ "replacement" ] } ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/resolve": { "get": { "operationId": "resolveRelease", "summary": "Resolve a release for a target", "description": "The release and package to install, with the API's signature over its manifest. Defaults to the latest production release that is not withdrawn. An exact version that was withdrawn returns 410 `release_withdrawn` with the reason and the replacement.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "target", "in": "query", "required": true, "description": "Your target.", "schema": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] } }, { "name": "channel", "in": "query", "required": false, "description": "Release channel.", "schema": { "type": "string", "enum": [ "production", "development" ], "default": "production" } }, { "name": "version", "in": "query", "required": false, "description": "An exact version on that channel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolution" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/installs": { "post": { "operationId": "recordInstall", "summary": "Record an install", "description": "Count a completed install. Signed-in installs also record the account's target.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "release_id": { "type": "string" }, "package_id": { "type": "string" } }, "required": [ "release_id", "package_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "installs": { "type": "integer" } }, "required": [ "installs" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/reviews": { "get": { "operationId": "listReviews", "summary": "List reviews", "description": "Reviews and the average rating.", "tags": [ "Reviews" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "rating": { "type": [ "number", "null" ] }, "count": { "type": "integer" } }, "required": [ "items", "rating", "count" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/review": { "put": { "operationId": "putReview", "summary": "Save your review", "description": "One review per account: 1 to 5 stars and up to 600 characters.", "tags": [ "Reviews" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "text": { "type": "string", "maxLength": 600 } }, "required": [ "rating" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteReview", "summary": "Remove your review", "description": "Removes your own review, even after losing access to a private app.", "tags": [ "Reviews" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "removed" } }, "required": [ "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/webhook": { "get": { "operationId": "getAccountsWebhook", "summary": "Get the Accounts webhook", "description": "The app's Silicon Accounts webhook settings. Authors only.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsWebhook" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "put": { "operationId": "setAccountsWebhook", "summary": "Set the Accounts webhook", "description": "Save the endpoint and account events Silicon Accounts sends to the app. Stored and delivered by Accounts.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsWebhook" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/webhook/rotate": { "post": { "operationId": "rotateAccountsWebhookSecret", "summary": "Rotate the Accounts webhook secret", "description": "Generates a new `whsec_` secret, shown once.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_secret": { "type": "string" } }, "required": [ "webhook_secret" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/media": { "post": { "operationId": "uploadMedia", "summary": "Upload media", "description": "Raw PNG, JPEG, WebP, GIF, MP4 or WebM up to 100 MiB with its Content-Type. Save the returned URL in a media field.", "tags": [ "Authoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Media" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/apps/{app_id}/media/{media_id}": { "get": { "operationId": "getMedia", "summary": "Get media", "description": "Media bytes. Visibility is checked on every read.", "tags": [ "Catalog" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "name": "media_id", "in": "path", "required": true, "description": "The media's SHA-256.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "responses": { "200": { "description": "The media file.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/events": { "get": { "operationId": "listAppEvents", "summary": "List an app's events", "description": "The app's event log as JSON pages: releases, package validation steps with the three commands' results, author invitations, joins and leaves, access changes and more. Authors only.", "tags": [ "Events" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/Types" }, { "$ref": "#/components/parameters/EventLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPage" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/apps/{app_id}/events/stream": { "get": { "operationId": "streamAppEvents", "summary": "Stream an app's events", "description": "Live events for an app's authors. Server-sent events. Each event has `id` (its seq), `event` (its type) and `data` (the Event as JSON). The stream starts with a `: ready cursor=N` comment and sends a `: heartbeat` comment every 15 seconds. Without Last-Event-ID it starts at the newest event. It closes after 30 minutes; reconnect with Last-Event-ID to continue.", "tags": [ "Events" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/Types" }, { "$ref": "#/components/parameters/LastEventIdHeader" }, { "$ref": "#/components/parameters/LastEventIdQuery" } ], "responses": { "200": { "description": "An event stream.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "id: 42\nevent: release.promoted\ndata: {\"seq\":42,\"type\":\"release.promoted\",\"app_id\":\"briefcase\",\"data\":{\"channel\":\"production\",\"version\":\"1.4.0\"}}\n\n" } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/events": { "get": { "operationId": "listMyEvents", "summary": "List your account's events", "description": "Your account feed as JSON pages: invitations to you, everything about apps you author, and public events (releases, publishing) of apps you installed. With `subscription`, that subscription's events.", "tags": [ "Events" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/Types" }, { "$ref": "#/components/parameters/EventLimit" }, { "name": "subscription", "in": "query", "required": false, "description": "Read through one of your subscriptions' filters.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPage" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/events/stream": { "get": { "operationId": "streamMyEvents", "summary": "Stream your account's events", "description": "Live events for the signed-in account. With `subscription`, the subscription's events; without Last-Event-ID it resumes where that subscription's stream last stopped. Server-sent events. Each event has `id` (its seq), `event` (its type) and `data` (the Event as JSON). The stream starts with a `: ready cursor=N` comment and sends a `: heartbeat` comment every 15 seconds. Without Last-Event-ID it starts at the newest event. It closes after 30 minutes; reconnect with Last-Event-ID to continue.", "tags": [ "Events" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/Types" }, { "$ref": "#/components/parameters/LastEventIdHeader" }, { "$ref": "#/components/parameters/LastEventIdQuery" }, { "name": "subscription", "in": "query", "required": false, "description": "Stream one of your subscriptions.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An event stream.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "id: 42\nevent: release.promoted\ndata: {\"seq\":42,\"type\":\"release.promoted\",\"app_id\":\"briefcase\",\"data\":{\"channel\":\"production\",\"version\":\"1.4.0\"}}\n\n" } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscriptions": { "get": { "operationId": "listSubscriptions", "summary": "List your subscriptions", "description": "Active and paused subscriptions by default.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "active", "paused", "cancelled", "all" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createSubscription", "summary": "Subscribe to events", "description": "Follow an app you can see, or your account feed. A webhook subscription returns its `whsec_` signing secret once. Each delivery is a POST with `X-Apps-Event-Id`, `X-Apps-Event-Type`, `X-Apps-Delivery-Id`, `X-Apps-Subscription-Id`, `X-Apps-Timestamp` and `X-Apps-Signature: v1=`. A 2xx answer within 10 seconds is a success; failures retry after 10 s, 30 s, 1 min, 5 min, 15 min, 30 min, then hourly, for 72 hours. Redirects are not followed. Production deliveries go only to public HTTPS endpoints.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreate" }, "example": { "app_id": "briefcase", "types": [ "release.promoted" ], "delivery": { "mode": "webhook", "url": "https://example.com/hooks/apps" }, "description": "Tell me when briefcase ships to production" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResult" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscriptions/{subscription_id}": { "get": { "operationId": "getSubscription", "summary": "Get a subscription", "description": "One of your subscriptions, with delivery counts.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/SubscriptionId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateSubscription", "summary": "Update, pause or resume a subscription", "description": "Change types, channels, delivery or description, or set `status` to `paused` or `active`. Deliveries due while paused are held and go out on resume within 72 hours of their event. Switching to webhook delivery returns a new secret once.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/SubscriptionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResult" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "cancelSubscription", "summary": "Cancel a subscription", "description": "Stops the subscription for good. Pending deliveries fail. Cancelling again returns the same result.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/SubscriptionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } }, "required": [ "subscription" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscriptions/{subscription_id}/deliveries": { "get": { "operationId": "listDeliveries", "summary": "List webhook deliveries", "description": "Recent deliveries, newest first, with attempts and the exact last error.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/SubscriptionId" }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Deliveries to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscriptions/{subscription_id}/secret/rotate": { "post": { "operationId": "rotateSubscriptionSecret", "summary": "Rotate a subscription's signing secret", "description": "A new `whsec_` secret, shown once. It signs every attempt from now on, including retries.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/SubscriptionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscriptions/{subscription_id}/ping": { "post": { "operationId": "pingSubscription", "summary": "Send a test delivery", "description": "Queues a signed `ping` delivery to this webhook subscription only.", "tags": [ "Subscriptions" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/SubscriptionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "event_id": { "type": "string" }, "status": { "type": "string", "const": "pending" } }, "required": [ "delivery_id", "event_id", "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/keys": { "get": { "operationId": "listAuthorKeys", "summary": "List your author keys", "description": "Your registered author signing keys, active and revoked.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorKey" } } }, "required": [ "items" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "addAuthorKey", "summary": "Register an author key", "description": "Register an Ed25519 public key you sign packages with. Its ID is derived from the key. Up to 20 active keys per account. Keep the private key to yourself; Apps never sees it.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string", "description": "Base64 Ed25519 public key (32 bytes)." }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "public_key" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/AuthorKey" } }, "required": [ "key" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/keys/{key_id}": { "delete": { "operationId": "revokeAuthorKey", "summary": "Revoke an author key", "description": "Revoke a key, for example when it leaks. New uploads cannot be signed with it. Revoking again returns the same key.", "tags": [ "Releases" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "description": "The author key's ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/AuthorKey" } }, "required": [ "key" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/platforms": { "post": { "operationId": "registerPlatform", "summary": "Record your platform", "description": "Records the signed-in account's target for target populations.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] } }, "required": [ "target" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "registered": { "type": "boolean" }, "target": { "type": "string" } }, "required": [ "registered", "target" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/reports": { "post": { "operationId": "reportBug", "summary": "Report a bug", "description": "Mails a bug report to the maintainers, with an optional pull request link.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 20000 }, "pr": { "type": "string" } }, "required": [ "message" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "const": "queued" } }, "required": [ "id", "status" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/telemetry": { "post": { "operationId": "recordTelemetry", "summary": "Record a telemetry event", "description": "A sanitized usage event. `X-Apps-Telemetry: off` opts out.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "string" }, "progress": {}, "event": { "type": "string" }, "path": { "type": "string" }, "target": { "type": "string" }, "status_code": { "type": "integer" }, "duration_ms": { "type": "integer" }, "item_count": { "type": "integer" }, "byte_count": { "type": "integer" }, "error_code": { "type": "string" } }, "required": [ "step", "progress" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "accepted" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/auth/login": { "get": { "operationId": "startLogin", "summary": "Start browser sign-in", "description": "Redirects to Silicon Accounts with PKCE and a browser-bound state.", "tags": [ "Auth" ], "security": [ {} ], "parameters": [ { "name": "return_to", "in": "query", "required": false, "description": "A local path to return to.", "schema": { "type": "string", "default": "/" } } ], "responses": { "303": { "description": "Redirect.", "headers": { "Location": { "description": "Where to go next.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/auth/callback": { "get": { "operationId": "finishLogin", "summary": "Finish browser sign-in", "description": "Silicon Accounts redirects here. Sets the HttpOnly session cookie and redirects to `return_to`.", "tags": [ "Auth" ], "security": [ {} ], "parameters": [ { "name": "state", "in": "query", "required": true, "description": "The sign-in state.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "description": "The authorization code.", "schema": { "type": "string" } } ], "responses": { "303": { "description": "Redirect.", "headers": { "Location": { "description": "Where to go next.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/auth/exchange": { "post": { "operationId": "exchangeToken", "summary": "Exchange a single-use token", "description": "Exchange a single-use token from `silicon-accounts login --app silicon-apps` for Apps tokens. No browser needed. Do not retry a consumed token; Idempotency-Key is not used here.", "tags": [ "Auth" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slt": { "type": "string" } }, "required": [ "slt" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/auth/refresh": { "post": { "operationId": "refreshToken", "summary": "Refresh tokens", "description": "Exchange a rotating refresh token. Do not send a rotated token again.", "tags": [ "Auth" ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/auth/logout": { "post": { "operationId": "logout", "summary": "Sign out", "description": "Revokes the token and clears the browser session.", "tags": [ "Auth" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] }, {} ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticated": { "type": "boolean", "const": false } }, "required": [ "authenticated" ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Apps-Version": { "$ref": "#/components/headers/AppsVersion" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "webhooks": { "subscriptionEvent": { "post": { "operationId": "receiveSubscriptionEvent", "summary": "A subscription delivery", "description": "Sent to a webhook subscription's URL. Verify `X-Apps-Signature` over the raw body before trusting it, refuse timestamps more than 5 minutes from your clock, and skip event IDs you already handled.", "tags": [ "Subscriptions" ], "security": [ {} ], "parameters": [ { "name": "X-Apps-Event-Id", "in": "header", "required": true, "description": "The event's ID, the same on every attempt.", "schema": { "type": "string" } }, { "name": "X-Apps-Event-Type", "in": "header", "required": true, "description": "The event type.", "schema": { "type": "string" } }, { "name": "X-Apps-Delivery-Id", "in": "header", "required": true, "description": "This delivery, the same across retries.", "schema": { "type": "string" } }, { "name": "X-Apps-Subscription-Id", "in": "header", "required": true, "description": "The subscription.", "schema": { "type": "string" } }, { "name": "X-Apps-Timestamp", "in": "header", "required": true, "description": "When this attempt was signed, unix seconds.", "schema": { "type": "integer" } }, { "name": "X-Apps-Signature", "in": "header", "required": true, "description": "`v1=`, comma-separated if there are several.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds marks the delivery delivered." }, "400": { "description": "Any other answer is a failed attempt and is retried." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A Silicon Accounts access token for the silicon-apps audience." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "apps_session", "description": "The store's HttpOnly browser session. Browser mutations also need an allowed Origin." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code, for example `not_found`, `rate_limited` or `unsupported_api_version`." }, "message": { "type": "string", "description": "What went wrong, in a sentence." }, "hint": { "type": "string", "description": "What to do next." }, "details": { "description": "Extra structured data, or null." } }, "required": [ "code", "message", "hint", "details" ] } }, "required": [ "error" ] }, "Health": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "required": [ "status", "service", "version" ] }, "Identity": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Permanent Silicon Accounts UUID." }, "id": { "type": "string", "description": "Current public ID, c:name or si:name." }, "display_name": { "type": "string" }, "verified_emails": { "type": "array", "items": { "type": "string" } } }, "required": [ "uuid", "id" ] }, "Session": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "account": { "anyOf": [ { "$ref": "#/components/schemas/Identity" }, { "type": "null" } ] } }, "required": [ "authenticated", "account" ] }, "Author": { "type": "object", "properties": { "uuid": { "type": "string" }, "id": { "type": "string" }, "display_name": { "type": "string" }, "joined_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "id", "display_name", "joined_at" ] }, "ValidationCheck": { "type": "object", "properties": { "command": { "type": "string", "enum": [ "--help", "accounts --json", "login status --json" ] }, "exit_code": { "type": [ "integer", "null" ] }, "stdout": { "type": "string" }, "stderr": { "type": "string" }, "passed": { "type": "boolean" }, "expected": { "type": "string" } }, "required": [ "command", "exit_code", "stdout", "stderr", "passed", "expected" ] }, "Package": { "type": "object", "properties": { "id": { "type": "string" }, "target": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size": { "type": "integer" }, "command": { "type": "string" }, "validation": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationCheck" } }, "created_at": { "type": "string", "format": "date-time" }, "install_script": { "anyOf": [ { "$ref": "#/components/schemas/InstallScript" }, { "type": "null" } ], "description": "The install script this target runs, or null when it has none." }, "inspected": { "type": "boolean", "description": "Whether Apps has read the package's install script information. Always true for new uploads." }, "author_signature": { "anyOf": [ { "$ref": "#/components/schemas/AuthorSignature" }, { "type": "null" } ], "description": "The uploading author's own signature, when they signed the package." } }, "required": [ "id", "target", "sha256", "size", "command", "validation", "created_at" ] }, "Release": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "channel": { "type": "string", "enum": [ "development", "production" ] }, "version": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" }, "package_ids": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "promoted_from": { "type": [ "string", "null" ], "description": "The development release this production release was promoted from." }, "signatures": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ReleaseSignature" }, "description": "The API's Ed25519 signature over each package's release manifest, by package ID. Every package Apps serves is signed." }, "signed_by_author": { "type": "boolean", "description": "Every package in this release also carries a valid author signature." }, "withdrawn": { "anyOf": [ { "$ref": "#/components/schemas/Withdrawal" }, { "type": "null" } ], "description": "Set when an author withdrew the release. A withdrawn release is never served." } }, "required": [ "id", "app_id", "channel", "version", "package_ids", "notes", "created_at" ] }, "ReleaseSignature": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The signing key, listed at /.well-known/silicon-apps-keys.json." }, "algorithm": { "type": "string", "const": "ed25519" }, "signature": { "type": "string", "description": "Base64 Ed25519 signature over the release manifest message." }, "install_script_sha256": { "type": [ "string", "null" ] }, "signed_at": { "type": "string", "format": "date-time" } }, "required": [ "key_id", "algorithm", "signature", "install_script_sha256", "signed_at" ] }, "Withdrawal": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "by_uuid": { "type": "string" }, "by_id": { "type": "string" }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "at", "by_uuid", "by_id", "reason" ] }, "WithdrawnRelease": { "type": "object", "properties": { "release_id": { "type": "string" }, "version": { "type": "string" }, "channel": { "type": "string", "enum": [ "development", "production" ] }, "reason": { "type": "string" }, "withdrawn_at": { "type": "string", "format": "date-time" }, "withdrawn_by": { "type": "string" } }, "required": [ "release_id", "version", "channel", "reason", "withdrawn_at", "withdrawn_by" ] }, "InstallScript": { "type": "object", "properties": { "path": { "type": "string", "description": "Path inside the package, as written in apps.yaml." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size": { "type": "integer" } }, "required": [ "path", "sha256", "size" ] }, "AuthorSignature": { "type": "object", "properties": { "key_id": { "type": "string", "description": "`ak_` and 16 hex characters." }, "algorithm": { "type": "string", "const": "ed25519" }, "public_key": { "type": "string", "description": "Base64 Ed25519 public key." }, "signature": { "type": "string", "description": "Base64 signature over the author package message." }, "signer_uuid": { "type": "string" }, "signer_id": { "type": "string" }, "signed_at": { "type": "string", "format": "date-time" } }, "required": [ "key_id", "algorithm", "public_key", "signature", "signer_uuid", "signer_id", "signed_at" ] }, "SignedManifest": { "type": "object", "properties": { "app_id": { "type": "string" }, "target": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] }, "version": { "type": "string" }, "channel": { "type": "string", "enum": [ "development", "production" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size": { "type": "integer" }, "release_id": { "type": "string" }, "install_script_sha256": { "type": [ "string", "null" ] } }, "required": [ "app_id", "target", "version", "channel", "sha256", "size", "release_id", "install_script_sha256" ], "description": "The signed fields. The message is UTF-8 text, one line each: `silicon-apps-release-v1`, then `app_id=`, `target=`, `version=`, `channel=`, `sha256=`, `size=`, `release_id=` and `install_script_sha256=` (the digest or `none`), each line ending in a newline." }, "ResolutionSignature": { "type": "object", "properties": { "key_id": { "type": "string" }, "algorithm": { "type": "string", "const": "ed25519" }, "signature": { "type": "string" }, "keys_url": { "type": "string", "const": "/.well-known/silicon-apps-keys.json" }, "manifest": { "$ref": "#/components/schemas/SignedManifest" } }, "required": [ "key_id", "algorithm", "signature", "keys_url", "manifest" ] }, "SigningKey": { "type": "object", "properties": { "key_id": { "type": "string" }, "algorithm": { "type": "string", "const": "ed25519" }, "public_key": { "type": "string", "description": "Base64 Ed25519 public key." }, "status": { "type": "string", "enum": [ "active", "retired", "revoked" ] }, "first_seen_at": { "type": "string", "format": "date-time" }, "endorsements": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "key_id", "signature" ] } } }, "required": [ "key_id", "algorithm", "public_key", "status", "endorsements" ] }, "SigningKeys": { "type": "object", "properties": { "issuer": { "type": "string", "const": "silicon-apps" }, "service": { "type": "string" }, "algorithm": { "type": "string", "const": "ed25519" }, "active_key_id": { "type": "string" }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/SigningKey" } }, "revoked": { "type": "array", "items": { "type": "string" } }, "messages": { "type": "object", "description": "The exact message formats for release signatures, author signatures and endorsements." }, "docs": { "type": "string" } }, "required": [ "issuer", "algorithm", "active_key_id", "keys", "revoked" ], "description": "Public keys that sign releases. An endorsement is a signature by an older key over `silicon-apps-key-endorsement-v1`, `key_id={key_id}` and `public_key={public_key}`, one per line: trust a new key when a key you already trust endorses it." }, "AuthorKey": { "type": "object", "properties": { "key_id": { "type": "string", "description": "`ak_` and 16 hex characters of the SHA-256 of the public key." }, "name": { "type": "string" }, "algorithm": { "type": "string", "const": "ed25519" }, "public_key": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_reason": { "type": [ "string", "null" ] } }, "required": [ "key_id", "name", "algorithm", "public_key", "created_at", "status" ] }, "CarouselItem": { "type": "object", "properties": { "url": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "alt": { "type": "string", "maxLength": 10000 } }, "required": [ "url", "kind" ] }, "Links": { "type": "object", "properties": { "website": { "type": "string" }, "developer_docs": { "type": "string" }, "android": { "type": "string" }, "ios": { "type": "string" }, "custom": { "type": "array", "maxItems": 4, "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" }, "logo": { "type": "string" } }, "required": [ "label", "url" ] } } } }, "App": { "type": "object", "properties": { "app_id": { "type": "string", "description": "Permanent ID: 3 to 30 of a-z, 0-9, - and _." }, "name": { "type": "string" }, "description": { "type": "string" }, "logo": { "type": "string" }, "logo_alt": { "type": "string" }, "banner": { "type": "string" }, "banner_alt": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Verified email domains with access. Authors only." }, "account_ids": { "type": "array", "items": { "type": "string" }, "description": "Accounts shared with. Authors only." }, "links": { "$ref": "#/components/schemas/Links" }, "carousel": { "type": "array", "items": { "$ref": "#/components/schemas/CarouselItem" } }, "published": { "type": "boolean" }, "setup_step": { "type": "integer", "minimum": 1, "maximum": 7 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "authors": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } }, "targets": { "type": "array", "items": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] }, "description": "Targets of the latest production release, or of the latest development release before the first production release." }, "latest_production": { "anyOf": [ { "$ref": "#/components/schemas/Release" }, { "type": "null" } ], "description": "The newest production release that is not withdrawn." }, "latest_development": { "anyOf": [ { "$ref": "#/components/schemas/Release" }, { "type": "null" } ], "description": "The newest development release that is not withdrawn." }, "signed": { "type": "boolean", "description": "Every package of the current release is signed by Apps." }, "signed_by_author": { "type": "boolean", "description": "Every package of the current release is also signed by an author's own key." }, "signed_by": { "type": "array", "items": { "type": "string" }, "description": "The c:id or si:id of each author who signed a package of the current release." }, "withdrawn_releases": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawnRelease" }, "description": "Releases the authors withdrew, with their reasons." }, "rating": { "type": [ "number", "null" ] }, "review_count": { "type": "integer" }, "installs": { "type": "integer" }, "is_author": { "type": "boolean", "description": "Whether the caller is an author." }, "is_admin": { "type": "boolean", "description": "Whether the caller is the admin. The admin is never marked to others." } }, "required": [ "app_id", "name", "description", "tags", "visibility", "published", "authors", "targets", "installs", "is_author", "is_admin" ] }, "AppPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ], "description": "Offset of the next page, or null on the last page." }, "sort": { "type": "string", "enum": [ "relevance", "rating", "installs", "name", "updated", "newest" ] } }, "required": [ "items", "total", "limit", "offset", "next_offset", "sort" ] }, "AuthorProfile": { "type": "object", "properties": { "uuid": { "type": "string" }, "id": { "type": "string" }, "display_name": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "total": { "type": "integer" } }, "required": [ "uuid", "id", "display_name", "items", "total" ] }, "Invite": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "to": { "type": "string", "description": "c:id, si:id or email address." }, "account_uuid": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "declined", "cancelled" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "to", "status", "created_at" ] }, "HistoryEntry": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "actor_uuid": { "type": "string" }, "kind": { "type": "string" }, "data": {}, "idempotency_key": { "type": [ "string", "null" ] } }, "required": [ "id", "at", "actor_uuid", "kind", "data" ] }, "Review": { "type": "object", "properties": { "uuid": { "type": "string" }, "id": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "text": { "type": "string", "maxLength": 600 }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "id", "rating", "text", "updated_at" ] }, "Readiness": { "type": "object", "properties": { "ready": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "required_commands": { "type": "array", "items": { "type": "string" } } }, "required": [ "ready", "errors", "required_commands" ] }, "Resolution": { "type": "object", "properties": { "app_id": { "type": "string" }, "release": { "$ref": "#/components/schemas/Release" }, "package": { "$ref": "#/components/schemas/Package" }, "download_path": { "type": "string" }, "signature": { "$ref": "#/components/schemas/ResolutionSignature" }, "author_signature": { "anyOf": [ { "$ref": "#/components/schemas/AuthorSignature" }, { "type": "null" } ] }, "install_script": { "anyOf": [ { "$ref": "#/components/schemas/InstallScript" }, { "type": "null" } ] }, "withdrawn": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawnRelease" }, "description": "Withdrawn releases on this channel. If yours is listed, move to this resolution." } }, "required": [ "app_id", "release", "package", "download_path", "signature", "author_signature", "install_script", "withdrawn" ] }, "Media": { "type": "object", "properties": { "url": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "size": { "type": "integer" }, "content_type": { "type": "string" } }, "required": [ "url", "id", "kind", "size", "content_type" ] }, "AccountsWebhook": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "secret_set": { "type": "boolean" }, "events": { "type": [ "array", "null" ], "items": { "type": "string" } }, "secret": { "type": "string", "description": "Only when a secret was generated by this request." } }, "additionalProperties": true }, "TargetPopulation": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "linux-x86_64", "linux-i686", "linux-aarch64", "linux-armv7hf", "windows-x86_64", "windows-i686", "windows-aarch64", "macos-x86_64", "macos-aarch64" ] }, "population": { "type": "integer" }, "runner_available": { "type": "boolean" } }, "required": [ "target", "population", "runner_available" ] } }, "total_population": { "type": "integer" }, "total_reach": { "type": "integer" }, "source": { "type": "string", "const": "registered_accounts" } }, "required": [ "items", "total_population", "total_reach", "source" ] }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in" ], "additionalProperties": true, "description": "The official Silicon Accounts token response." }, "Event": { "type": "object", "properties": { "seq": { "type": "integer", "description": "Position in the event log. Use it as Last-Event-ID or `after`." }, "id": { "type": "string", "description": "Unique event ID." }, "type": { "type": "string", "enum": [ "app.created", "app.imported_from_accounts", "app.id_migrated", "app.details_changed", "app.access_changed", "app.published", "app.secret_rotated", "app.installed", "media.uploaded", "accounts.webhook_changed", "package.validation_started", "package.validation_step", "package.accepted", "package.validation_failed", "release.created", "release.promoted", "release.withdrawn", "author.invited", "author.joined", "author.invite_declined", "author.invite_cancelled", "author.left", "author.removed", "author.admin_transferred", "review.updated", "review.removed", "ping" ] }, "app_id": { "type": [ "string", "null" ] }, "actor_uuid": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "description": "Event data. Release events carry the Release; validation steps carry the step, command, exit code, output and expectation." } }, "required": [ "seq", "id", "type", "app_id", "actor_uuid", "occurred_at", "data" ] }, "EventPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_after": { "type": "integer", "description": "Pass as `after` for the next page." }, "has_more": { "type": "boolean" }, "cursor": { "type": "integer", "description": "The newest event seq in the log." } }, "required": [ "items", "next_after", "has_more", "cursor" ] }, "SubscriptionDelivery": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "webhook" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "mode", "url" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "stream" } }, "required": [ "mode" ] } ], "description": "Where events go: a signed webhook, or a stream you read at `stream_url`." }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "description": "`sub_` followed by 32 hex characters." }, "app_id": { "type": [ "string", "null" ], "description": "The app followed, or null for your account feed." }, "types": { "type": "array", "items": { "type": "string" }, "description": "Exact event types, `group.*` or `*`." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "production", "development" ] }, "description": "Release channels to receive. Empty means both. Other events are not filtered." }, "delivery": { "$ref": "#/components/schemas/SubscriptionDelivery" }, "stream_url": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] }, "description": { "type": "string" }, "cursor": { "type": "integer", "description": "Last event seq sent on this subscription's stream." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "deliveries": { "type": "object", "properties": { "pending": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" } }, "description": "Delivery counts. Only on GET of one subscription." } }, "required": [ "id", "app_id", "types", "channels", "delivery", "stream_url", "status", "description", "cursor", "created_at", "updated_at" ] }, "SubscriptionResult": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "secret": { "type": "string", "description": "The `whsec_` signing secret. Returned once, when it is generated. Save it now." } }, "required": [ "subscription" ] }, "SubscriptionCreate": { "type": "object", "properties": { "app_id": { "type": [ "string", "null" ], "description": "An app you can see. Omit or null to follow your account feed: invitations to you, apps you author and public events of apps you installed." }, "types": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Defaults to `*` for authors and the account feed, and to app.published, release.created and release.promoted for everyone else, who can only receive those." }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "production", "development" ] } }, "delivery": { "$ref": "#/components/schemas/SubscriptionDelivery" }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "delivery" ], "additionalProperties": false }, "SubscriptionUpdate": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 }, "channels": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "production", "development" ] } }, "delivery": { "$ref": "#/components/schemas/SubscriptionDelivery" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "description": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "event_seq": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "id", "event_id", "event_type", "event_seq", "status", "attempts", "created_at" ] }, "WebhookPayload": { "type": "object", "properties": { "actor_uuid": { "type": "string" }, "app_id": { "type": [ "string", "null" ] }, "data": {}, "event_id": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "seq": { "type": "integer" }, "subscription_id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "actor_uuid", "app_id", "data", "event_id", "occurred_at", "seq", "subscription_id", "type" ], "description": "Body of a subscription webhook delivery." }, "Capabilities": { "type": "object", "properties": { "service": { "type": "string" }, "version": { "type": "string" }, "api": { "type": "object", "properties": { "current": { "type": "string" }, "versions": { "type": "array", "items": { "type": "string" } }, "header": { "type": "string" }, "base_path": { "type": "string" }, "negotiation": { "type": "string" } } }, "auth": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "string" } }, "issuer": { "type": "string" }, "audience": { "type": "string" } }, "additionalProperties": true }, "targets": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string" }, "validation": { "type": "string", "enum": [ "live", "unreachable", "not_configured" ] }, "live": { "type": "boolean" } }, "required": [ "target", "validation", "live" ] } }, "validation_runner": { "type": "object", "properties": { "configured": { "type": "boolean" }, "reachable": { "type": [ "boolean", "null" ] }, "checked_at": { "type": [ "string", "null" ] }, "commands": { "type": "array", "items": { "type": "string" } } } }, "search": { "type": "object" }, "streaming": { "type": "object" }, "subscriptions": { "type": "object" }, "idempotency": { "type": "object" }, "rate_limits": { "type": "object" }, "errors": { "type": "object" }, "signing": { "type": "object", "properties": { "algorithm": { "type": "string" }, "keys": { "type": "string" }, "active_key_id": { "type": "string" } }, "additionalProperties": true }, "withdrawal": { "type": "object" }, "links": { "type": "object", "properties": { "openapi": { "type": "string" }, "agent_card": { "type": "string" }, "mcp": { "type": "string" }, "llms_txt": { "type": "string" }, "docs": { "type": "string" } } }, "requirements": { "type": "object", "properties": { "satisfied": { "type": "boolean", "const": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "requirement": { "type": "string" }, "satisfied": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "requirement", "satisfied", "reason" ] } } }, "required": [ "satisfied", "results" ], "description": "Present when `require` was given and everything was met. When something is missing the answer is 422 `capabilities_missing` instead." } }, "required": [ "service", "version", "api", "auth", "targets", "streaming", "subscriptions", "idempotency", "rate_limits", "links" ], "additionalProperties": true }, "AgentCard": { "type": "object", "properties": { "protocolVersion": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" }, "provider": { "type": "object", "properties": { "organization": { "type": "string" }, "url": { "type": "string" } } }, "capabilities": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "pushNotifications": { "type": "boolean" }, "stateTransitionHistory": { "type": "boolean" } } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "tags" ] } } }, "required": [ "protocolVersion", "name", "description", "url", "version", "capabilities", "skills" ], "additionalProperties": true, "description": "A2A agent card." } }, "parameters": { "AppId": { "name": "app_id", "in": "path", "required": true, "description": "The app's permanent ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8 to 200 printable characters without spaces. Reuse it, with the same body, to retry a request whose result you did not receive.", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, "SubscriptionId": { "name": "subscription_id", "in": "path", "required": true, "description": "The subscription's ID.", "schema": { "type": "string" } }, "Types": { "name": "types", "in": "query", "required": false, "description": "Comma-separated event types to include: exact types, `group.*` (for example `release.*`) or `*`.", "schema": { "type": "string" }, "example": "release.promoted,package.*" }, "LastEventIdHeader": { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Resume after this event seq. Browsers send it on reconnect.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "LastEventIdQuery": { "name": "last_event_id", "in": "query", "required": false, "description": "Resume after this event seq, for clients that cannot set headers.", "schema": { "type": "integer", "minimum": 0 } }, "After": { "name": "after", "in": "query", "required": false, "description": "Return events after this seq. Defaults to 0, the oldest.", "schema": { "type": "integer", "minimum": 0 } }, "EventLimit": { "name": "limit", "in": "query", "required": false, "description": "Events per page, 1 to 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } }, "responses": { "BadRequest": { "description": "Invalid input, an unknown API version or an unknown event type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Sign in: the request needs a valid Silicon Accounts token or session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Signed in, but not allowed: for example not an author or not the admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such route or resource, or one you cannot see.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The current state does not allow this, or the Idempotency-Key belongs to another request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "The package failed validation. `error.details` holds the exact command results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "A required service, such as the isolated runner or Silicon Accounts, is not available. Retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Gone": { "description": "The release was withdrawn. `error.details` holds the reason and the replacement, if any.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests. Wait for Retry-After seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed per 60 second window for this client and kind (read or write).", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window is full again.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "AppsVersion": { "description": "The API version used for this response.", "schema": { "type": "string" } }, "IdempotentReplayed": { "description": "`true` when this response replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true", "false" ] } } } } }