{ "openapi": "3.1.0", "info": { "title": "Smallware API", "version": "1.0.0", "summary": "Create projects, deploy builds, and manage secrets on Smallware from a script or a coding agent.", "description": "Smallware hosts small business applications built with the open-source Pylon\nframework. This document describes the endpoints reachable with a bearer token:\nthe ones the `pylon` CLI calls, plus the platform endpoints a partner service\ncalls to provision organizations and projects for customers.\n\nGetting a token takes two clicks and no conversation. Sign up at https://www.usesmallware.com/signup, open https://www.usesmallware.com/dashboard/account/cli-tokens, and create one. There is no application form, no approval queue,\nand no sales call. The free tier deploys one real app on a real URL with no\ncredit card.\n\nEvery operation is `POST /api/fn/` with the arguments as a flat\nJSON object — not wrapped in an `args` key. A successful call answers 200 with\nthe return value as the entire body. A failure answers 4xx/5xx with {\"error\":\n{\"code\",\"message\"}}.\n\nScopes: see https://www.usesmallware.com/.well-known/oauth-protected-resource for the RFC 9728\nprotected-resource metadata, which carries `scopes_supported` and the two\ncredential types in their registered form.", "contact": { "name": "Smallware support", "email": "support@usesmallware.com", "url": "https://www.usesmallware.com/contact" }, "termsOfService": "https://www.usesmallware.com/terms" }, "servers": [ { "url": "https://www.usesmallware.com", "description": "Production" } ], "externalDocs": { "description": "Smallware developer resources", "url": "https://www.usesmallware.com/developers" }, "x-oauth-protected-resource": "https://www.usesmallware.com/.well-known/oauth-protected-resource", "components": { "securitySchemes": { "userApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pk..", "description": "A personal bearer token. Any signed-in user mints one in the dashboard in two clicks — no form, no approval, no sales contact. It carries the user's own role on every organization they belong to; it does not carry named scopes, and it cannot exceed what the user can already do in the dashboard. Revoke a single token without affecting the others.", "x-mint-url": "https://www.usesmallware.com/dashboard/account/cli-tokens", "x-self-serve": true }, "platformCredential": { "type": "http", "scheme": "bearer", "bearerFormat": "plat..", "description": "A server-to-server credential for a partner service that provisions organizations and projects on behalf of customers. It carries an explicit list of named scopes and is refused for anything outside them. Issued by a Smallware operator, not self-serve.", "x-self-serve": false, "x-scopes": { "org.create": "Create an organization on behalf of a customer identified by email address. The customer owns it from creation; the credential holder does not become a member and does not gain access to the organization's data.", "project.create": "Create a project inside an existing organization and provision its machine, database, and system hostname. Does not grant access to the project's data or secrets.", "deploy": "Upload a build artifact for an existing project and deploy it. Does not grant project creation, secret reads, or organization changes.", "model.resolve": "Resolve which model provider serves a given (organization, model) pair and read that organization's stored provider key. Held only by the model proxy; kept separate so a deploy credential cannot read customer provider keys." }, "x-scopes-supported-url": "https://www.usesmallware.com/.well-known/oauth-protected-resource" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } }, "Organization": { "type": "object", "required": [ "id", "slug", "name", "role" ], "properties": { "id": { "type": "string", "description": "Organization id. Pass it as `orgId` to createProjectInOrg." }, "slug": { "type": "string", "description": "URL-safe organization name, the user-facing identifier." }, "name": { "type": "string", "description": "Display name." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "The calling user's role in this organization." } } }, "ProjectListItem": { "type": "object", "required": [ "slug", "name", "orgSlug" ], "properties": { "slug": { "type": "string", "description": "Project slug. The app is served at https://.smallware.run." }, "name": { "type": "string", "description": "Display name." }, "orgSlug": { "type": [ "string", "null" ], "description": "Slug of the organization that owns the project." } } }, "Project": { "type": "object", "required": [ "id", "slug", "orgId", "region", "status" ], "properties": { "id": { "type": "string", "description": "Project id." }, "slug": { "type": "string", "description": "Project slug." }, "orgId": { "type": "string", "description": "Id of the organization that owns the project." }, "region": { "type": "string", "description": "Fly region the machine runs in, e.g. \"iad\"." }, "status": { "type": "string", "description": "Lifecycle state. \"ready\" means the app is serving; \"error\" means provisioning failed and `errorMessage` says why." }, "errorMessage": { "type": "string", "description": "Present only when `status` is \"error\"." } } } } }, "security": [ { "userApiKey": [] } ], "paths": { "/api/fn/exchangeCliAuthCode": { "post": { "operationId": "exchangeSmallwareLoginCode", "summary": "Redeem a one-time login code for an API token", "description": "Exchange the single-use code shown by `npx @pylonsync/cli login` (or minted from the dashboard's hand-off card) for the bearer token it stands for. The code is the authentication, so this is the one operation that takes no token. Codes are single-use and expire five minutes after they are minted.", "tags": [ "auth" ], "security": [], "requestBody": { "required": true, "description": "The code to redeem.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The code as printed, case-insensitive. Hyphens and spaces are ignored." } } } } } }, "responses": { "200": { "description": "The token the code stood for.", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "label", "user" ], "properties": { "token": { "type": "string", "description": "Bearer token, `pk..`. Store it; it is not recoverable." }, "label": { "type": "string", "description": "The label the token was minted under." }, "user": { "type": "object", "required": [ "id", "email" ], "description": "The account the token belongs to.", "properties": { "id": { "type": "string", "description": "User id." }, "email": { "type": "string", "description": "Account email." } } } } } } } }, "400": { "description": "The code is unknown, already redeemed, or expired (CODE_INVALID, CODE_USED, CODE_EXPIRED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/fn/listMyOrgsForCli": { "post": { "operationId": "listSmallwareOrganizations", "summary": "List the organizations the token's owner belongs to", "description": "Return every organization the calling user is a member of, with the caller's role in each. Call this first: an organization id from here is what createProjectInOrg takes, and the slug is what the CLI's `--org` flag matches.", "tags": [ "organizations" ], "requestBody": { "required": true, "description": "No arguments. Send `{}`.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Organizations, sorted by slug.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "name", "role" ], "properties": { "id": { "type": "string", "description": "Organization id. Pass it as `orgId` to createProjectInOrg." }, "slug": { "type": "string", "description": "URL-safe organization name, the user-facing identifier." }, "name": { "type": "string", "description": "Display name." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "The calling user's role in this organization." } } } } } } }, "401": { "description": "No bearer token, or the token is not valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/fn/listMyProjectsForCli": { "post": { "operationId": "listSmallwareProjects", "summary": "List the projects the token's owner can reach", "description": "Return every non-destroyed project across all of the caller's organizations, sorted by organization then project. Use it to resolve a project the user named in prose, instead of guessing a slug.", "tags": [ "projects" ], "requestBody": { "required": true, "description": "No arguments. Send `{}`.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Projects, sorted by organization then slug.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "orgSlug" ], "properties": { "slug": { "type": "string", "description": "Project slug. The app is served at https://.smallware.run." }, "name": { "type": "string", "description": "Display name." }, "orgSlug": { "type": [ "string", "null" ], "description": "Slug of the organization that owns the project." } } } } } } }, "401": { "description": "No bearer token, or the token is not valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/fn/getProjectForCli": { "post": { "operationId": "getSmallwareProject", "summary": "Look up one project by slug", "description": "Resolve a project slug to its id, organization, region, and lifecycle status. Returns only the fields the CLI needs to operate — scaling, secrets, and git configuration are deliberately withheld, so a token is a deploy-and-operate credential rather than a full read of the project.", "tags": [ "projects" ], "requestBody": { "required": true, "description": "The project to look up.", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "description": "Project slug, e.g. \"claim-intake\"." } } } } } }, "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "orgId", "region", "status" ], "properties": { "id": { "type": "string", "description": "Project id." }, "slug": { "type": "string", "description": "Project slug." }, "orgId": { "type": "string", "description": "Id of the organization that owns the project." }, "region": { "type": "string", "description": "Fly region the machine runs in, e.g. \"iad\"." }, "status": { "type": "string", "description": "Lifecycle state. \"ready\" means the app is serving; \"error\" means provisioning failed and `errorMessage` says why." }, "errorMessage": { "type": "string", "description": "Present only when `status` is \"error\"." } } } } } }, "401": { "description": "No bearer token, or the token is not valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/fn/setSecretForCli": { "post": { "operationId": "setSmallwareSecret", "summary": "Create or replace one project secret", "description": "Upsert an environment secret for a project. The value is encrypted at rest and pushed to the running machine without waiting for the next deploy. Requires the owner or admin role in the project's organization. Keys reserved by the platform are refused.", "tags": [ "secrets" ], "requestBody": { "required": true, "description": "The secret to write.", "content": { "application/json": { "schema": { "type": "object", "required": [ "projectSlug", "key", "value" ], "properties": { "projectSlug": { "type": "string", "description": "Slug of the project the secret belongs to." }, "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "Environment variable name in SCREAMING_SNAKE_CASE." }, "value": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "Secret value, 1 to 65536 bytes." } } } } } }, "responses": { "200": { "description": "The secret was written.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "key" ], "properties": { "ok": { "type": "boolean", "description": "True on success." }, "key": { "type": "string", "description": "The key that was written or removed." } } } } } }, "400": { "description": "The key is malformed (INVALID_KEY), reserved by the platform (PROTECTED_KEY), the value is out of range (INVALID_VALUE), or the plan's secret limit is reached (QUOTA_EXCEEDED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "401": { "description": "No bearer token, or the token is not valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "403": { "description": "The caller is authenticated but not permitted to do this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/fn/deleteSecretForCli": { "post": { "operationId": "deleteSmallwareSecret", "summary": "Delete one project secret", "description": "Remove an environment secret from a project and from the running machine. Requires the owner or admin role in the project's organization.", "tags": [ "secrets" ], "requestBody": { "required": true, "description": "The secret to remove.", "content": { "application/json": { "schema": { "type": "object", "required": [ "projectSlug", "key" ], "properties": { "projectSlug": { "type": "string", "description": "Slug of the project the secret belongs to." }, "key": { "type": "string", "description": "Environment variable name to remove." } } } } } }, "responses": { "200": { "description": "The secret was removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "key" ], "properties": { "ok": { "type": "boolean", "description": "True on success." }, "key": { "type": "string", "description": "The key that was written or removed." } } } } } }, "401": { "description": "No bearer token, or the token is not valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "403": { "description": "The caller is authenticated but not permitted to do this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "404": { "description": "No secret with that key on this project (NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/fn/createOrgForEmail": { "post": { "operationId": "createSmallwareOrganizationForCustomer", "summary": "Provision an organization owned by a customer", "description": "Create an organization owned by the person at `email`, who may not have a Smallware account yet — they claim it later by signing in with that address. For partner services onboarding customers; a normal user creates their own organization in the dashboard.", "tags": [ "platform" ], "security": [ { "platformCredential": [] } ], "x-required-scopes": [ "org.create" ], "requestBody": { "required": true, "description": "The customer and the organization to create.", "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "orgName" ], "properties": { "email": { "type": "string", "format": "email", "description": "The customer who will own the organization." }, "orgName": { "type": "string", "description": "Display name. The slug is derived from it and returned." }, "displayName": { "type": "string", "description": "Optional display name for the owner's account." } } } } } }, "responses": { "200": { "description": "The organization and its owner.", "content": { "application/json": { "schema": { "type": "object", "required": [ "orgId", "slug", "ownerUserId", "ownerEmail" ], "properties": { "orgId": { "type": "string", "description": "Pass this to createProjectInOrg." }, "slug": { "type": "string", "description": "Derived slug." }, "ownerUserId": { "type": "string", "description": "The owner's user id." }, "ownerEmail": { "type": "string", "description": "The owner's email address." }, "ownerExisted": { "type": "boolean", "description": "True when the address already had an account and was reused." } } } } } }, "400": { "description": "Missing email (INVALID_EMAIL) or organization name (INVALID_NAME).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "401": { "description": "No platform credential (PLATFORM_AUTH_REQUIRED), malformed (PLATFORM_KEY_MALFORMED), unrecognised (PLATFORM_KEY_INVALID), or revoked (PLATFORM_KEY_REVOKED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "403": { "description": "The credential does not carry the \"org.create\" scope (PLATFORM_SCOPE_DENIED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/fn/createProjectInOrg": { "post": { "operationId": "createSmallwareProjectForCustomer", "summary": "Create and provision a project inside an organization", "description": "Create a project in an existing organization and provision its machine, database, and system hostname at https://.smallware.run. With `gitRepo` and `githubInstallationId` set, the first build deploys from the repository and later pushes redeploy automatically. Slugs are global: retry with a different one on SLUG_TAKEN.", "tags": [ "platform" ], "security": [ { "platformCredential": [] } ], "x-required-scopes": [ "project.create" ], "requestBody": { "required": true, "description": "The project to create.", "content": { "application/json": { "schema": { "type": "object", "required": [ "orgId", "name", "slug" ], "properties": { "orgId": { "type": "string", "description": "Organization the project belongs to, from createOrgForEmail." }, "name": { "type": "string", "description": "Display name." }, "slug": { "type": "string", "description": "Globally unique slug. Becomes .smallware.run." }, "region": { "type": "string", "description": "Fly region to run in. Defaults to \"iad\"." }, "gitRepo": { "type": "string", "description": "Repository as \"owner/repo\", for git-connected deploys." }, "gitBranch": { "type": "string", "description": "Branch to deploy from. Defaults to the repo default." }, "githubInstallationId": { "type": "string", "description": "Id of the Smallware GitHub App installation on that repository." } } } } } }, "responses": { "200": { "description": "The project was created and provisioning was scheduled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "url", "deploying" ], "properties": { "id": { "type": "string", "description": "Project id." }, "slug": { "type": "string", "description": "The slug the project was created under." }, "url": { "type": "string", "format": "uri", "description": "Where the app will serve, https://.smallware.run. Provisioning is asynchronous — poll getProjectForCli until status is \"ready\"." }, "deploying": { "type": "boolean", "description": "True when a git repository was supplied and the first build was scheduled automatically." } } } } } }, "400": { "description": "The slug is taken (SLUG_TAKEN), the organization has no owner (ORG_OWNER_MISSING), or the plan's project limit is reached (QUOTA_EXCEEDED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "401": { "description": "No platform credential (PLATFORM_AUTH_REQUIRED), malformed (PLATFORM_KEY_MALFORMED), unrecognised (PLATFORM_KEY_INVALID), or revoked (PLATFORM_KEY_REVOKED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "403": { "description": "The credential does not carry the \"project.create\" scope (PLATFORM_SCOPE_DENIED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "404": { "description": "No organization with that id (ORG_NOT_FOUND).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } }, "/api/manifest": { "get": { "operationId": "getSmallwareManifest", "summary": "Describe this Pylon application", "description": "Return the running application's manifest: entities, routes, policies, and auth configuration. Unauthenticated. Useful for confirming a deploy landed and for discovering what a Pylon app exposes.", "tags": [ "platform" ], "security": [], "responses": { "200": { "description": "The manifest.", "content": { "application/json": { "schema": { "type": "object", "description": "Manifest document. `manifest_version` is 1 today; treat unknown fields as additive." } } } }, "default": { "description": "Any other failure. The body is always {\"error\":{\"code\",\"message\"}}; branch on `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code, e.g. \"AUTH_REQUIRED\", \"FORBIDDEN\", \"PROJECT_NOT_FOUND\", \"PLATFORM_SCOPE_DENIED\"." }, "message": { "type": "string", "description": "What went wrong, in one sentence." } } } } } } } } } } } }, "tags": [ { "name": "auth", "description": "Getting and managing the bearer token everything else needs." }, { "name": "organizations", "description": "Organizations the caller belongs to." }, { "name": "projects", "description": "Projects and their lifecycle state." }, { "name": "secrets", "description": "Per-project environment secrets." }, { "name": "platform", "description": "Scoped server-to-server operations for partner services, plus the public manifest." } ] }