{"openapi":"3.1.0","info":{"title":"BWEZE API","version":"0.1.0","description":"The AI-native developer platform for Rwanda: hosting/deploys, Postgres backends, projects, SMS, domains, cron, firewall, analytics, and billing behind one API. Authenticate with a scoped API token (see the bearerAuth scheme): it can do only what it was granted, on the resources it was given, from the addresses it allows, while it is valid, and never more than its owner's role."},"servers":[{"url":"https://api.bweze.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A BWEZE API token: bw_sk_… (secret, server-side) or bw_pk_… (publishable, read-only).\n\nEach token carries a policy, set in the dashboard (Manage workspace > API tokens) and enforced on every request:\n- permissions: resource:action pairs from deployment, backend, dns, message and terminal;\n- resources: optionally only some projects, backends or DNS zones (lists hide the rest; a scoped token cannot create new ones);\n- client IP filter: optional IPv4/IPv6 ranges, checked against the address the BWEZE edge saw;\n- validity: an optional start and expiry.\n\nA request also needs the owner's live member role to allow the action (a workspace-owned token is capped by the owner role), so a token never exceeds its owner and a demotion applies on the next request.\n\nRefusals: 401 token_policy_missing, token_not_yet_valid, token_expired; 403 token_ip_denied, token_owner_removed, token_permission_denied, key_role_denied, token_resource_denied, publishable_key_write_denied, secret_key_required. GET /v1/me returns a token's permissions, scope and expiry."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}},"SendMessage":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"Recipient in E.164, e.g. +250788123456."},"body":{"type":"string"},"template":{"type":"string","description":"Uses {{placeholders}} from data."},"data":{"type":"object","additionalProperties":true},"from":{"type":"string"},"idempotencyKey":{"type":"string"}}},"MessageResult":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","sent","delivered","failed"]},"segments":{"type":"integer"},"encoding":{"type":"string","enum":["GSM7","UCS2"]},"providerMessageId":{"type":"string"}}},"Segments":{"type":"object","properties":{"encoding":{"type":"string","enum":["GSM7","UCS2"]},"segments":{"type":"integer"},"length":{"type":"integer"}}},"Project":{"type":"object","description":"A typed deploy unit: a frontend web app or a backend data stack.","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["frontend","backend"]},"created_at":{"type":"string","format":"date-time"},"app":{"type":["object","null"],"description":"The frontend (git deploy) half, if any."},"backend":{"type":["object","null"],"description":"The backend (data stack) half, if any."}}},"CreateProject":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["frontend","backend"]}}},"CustomDomain":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["pending","verifying","verified","active","error"]},"verification_token":{"type":"string"},"last_error":{"type":["string","null"]}}},"DomainSearchResults":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"available":{"type":"boolean"},"priceMinor":{"type":["integer","null"],"description":"RWF for the first year, from the price list (GET /v1/pricing). Null when BWEZE does not sell this domain."},"currency":{"type":"string","enum":["RWF"]}}}}}},"DomainRegistration":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"price_minor":{"type":["integer","null"],"description":"RWF for the first year, taken from the wallet when it was bought. Null on purchases from before domains were charged."},"currency":{"type":"string","enum":["RWF"]},"price_usd":{"type":["string","null"],"deprecated":true,"description":"Older purchases only; no longer written."},"status":{"type":"string","enum":["requested","registered","failed"],"description":"requested: paid, waiting for the registrar or for BWEZE to register it by hand. failed: not registered; the price went back to the wallet."},"refund_transaction_id":{"type":["string","null"],"description":"Set when a failed purchase was refunded."},"last_error":{"type":["string","null"]},"registrant_id":{"type":["string","null"],"description":"The owner on record. Null on registrations made before owners were recorded."}}},"Registrant":{"type":"object","description":"The domain's owner on record (registrant). The domain is registered in this name, not BWEZE's. The registry keeps these details and may show some of them in WHOIS.","required":["name","email","street","city","countryCode"],"properties":{"name":{"type":"string","maxLength":255},"organization":{"type":"string","maxLength":255},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"+<country code>.<number>, e.g. +250.788123456. Rwandan numbers in other forms are converted."},"street":{"type":"array","items":{"type":"string","maxLength":255},"minItems":1,"maxItems":3},"city":{"type":"string","maxLength":255},"state":{"type":"string","maxLength":255},"postalCode":{"type":"string","maxLength":16},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2, e.g. RW."}}},"CronJob":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"schedule":{"type":"string","description":"5-field cron expression."},"target_url":{"type":"string","format":"uri"},"enabled":{"type":"boolean"}}},"FirewallRule":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","enum":["allow","block"]},"cidr":{"type":"string","description":"An IP or CIDR."},"note":{"type":["string","null"]}}},"Backend":{"type":"object","description":"A provisioned Postgres backend stack (auth + storage + realtime).","properties":{"id":{"type":"string"},"organization_id":{"type":"string"},"name":{"type":"string"},"url":{"type":["string","null"],"description":"The stack's public URL on *.bweze.app once deployed."}}},"BackendKeys":{"type":"object","description":"A backend's connection credentials. Requires backend:create - these grant full DB access.","properties":{"url":{"type":["string","null"]},"anonKey":{"type":["string","null"],"description":"Public anon key (anon_…)."},"serviceRoleKey":{"type":["string","null"],"description":"Full-access server key (ik_…) - server-side only."},"postgresPassword":{"type":["string","null"]}}},"TokenIdentity":{"type":"object","description":"The authenticating token: its workspace, owner and policy.","properties":{"keyName":{"type":"string","description":"The token's name."},"tokenId":{"type":"string","description":"Stable across rolls."},"organizationId":{"type":"string"},"organizationName":{"type":["string","null"]},"ownerKind":{"type":"string","enum":["user","workspace"]},"role":{"type":["string","null"],"description":"The owner's live member role; null for a workspace token."},"tier":{"type":"string","enum":["secret","publishable"]},"permissions":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Granted resource:action pairs, e.g. { \"dns\": [\"read\", \"update\"] }."},"scope":{"type":"object","description":"null for a kind means every resource of that kind in the workspace.","properties":{"projects":{"type":["array","null"],"items":{"type":"string"}},"backends":{"type":["array","null"],"items":{"type":"string"}},"zones":{"type":["array","null"],"items":{"type":"string"}}}},"expiresAt":{"type":["string","null"],"format":"date-time"}}},"DnsRecordSet":{"type":"object","required":["type"],"properties":{"name":{"type":"string","description":"Relative to the zone; @ for the apex.","default":"@"},"type":{"type":"string","enum":["A","AAAA","CNAME","TXT","MX","SRV","NS"]},"ttl":{"type":"integer","minimum":60,"maximum":86400,"default":300},"records":{"type":"array","items":{"type":"string"},"description":"Values; required to create or replace."}}},"ExecResult":{"type":"object","description":"Output of a one-shot command run inside the project's container.","properties":{"output":{"type":"string","description":"Combined stdout/stderr, capped at 256KB."},"truncated":{"type":"boolean","description":"True when output exceeded the 256KB cap and was truncated."}}},"Service":{"type":"object","description":"A deployed service. Its type is fixed when created: web (public HTTPS), private (reachable only from the workspace's other services, at internal_url), worker (no port) or cron (a command on a UTC schedule).","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["web","private","worker","cron"]},"project_id":{"type":"string","nullable":true},"repo":{"type":"string"},"branch":{"type":"string"},"url":{"type":"string","nullable":true,"description":"A web service's public URL."},"internal_url":{"type":"string","nullable":true,"description":"A private service's address, e.g. http://app-api-1a2b3c4d."},"status":{"type":"string","description":"Live state: \"running:healthy\", \"starting\", \"degraded\", \"exited\", \"scheduled\" (cron), \"not deployed\"."},"settings":{"$ref":"#/components/schemas/ServiceSettings"},"created_at":{"type":"string","format":"date-time"}}},"ServiceSettings":{"type":"object","description":"Commands run as /bin/sh -c <command> after the image's ENTRYPOINT. Commands and the port apply from the next deploy; a cron schedule and time limit apply at once.","properties":{"port":{"type":"integer","nullable":true,"description":"Web and private services only."},"start_command":{"type":"string","nullable":true,"description":"Replaces the image's CMD; a cron job's command."},"pre_deploy_command":{"type":"string","nullable":true,"description":"Runs on each new release before it goes live; a failure fails the deploy."},"cron_schedule":{"type":"string","nullable":true,"description":"Five fields, UTC. Cron jobs only."},"cron_timeout_seconds":{"type":"integer","nullable":true,"description":"60 to 43200. Cron jobs only."}}},"JobRun":{"type":"object","description":"One run of a command on a release: a pre-deploy command, a one-off job or a cron run.","properties":{"id":{"type":"string"},"purpose":{"type":"string","enum":["pre_deploy","one_off","cron"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"command":{"type":"string"},"exit_code":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"description":"Why it failed or was cancelled, e.g. \"exited with code 1\", \"skipped: the previous run was still going\"."},"release_id":{"type":"string"},"deploy_id":{"type":"string","nullable":true,"description":"A pre-deploy command's deploy."},"scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"A cron run's UTC minute."},"timeout_seconds":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"JobLogLine":{"type":"object","properties":{"id":{"type":"integer","description":"Pass the last one as ?after= to get the next lines."},"line":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/me":{"get":{"summary":"The authenticating token","description":"Any valid secret token. Returns its workspace, owner, permissions, resource scope and expiry.","operationId":"getMe","responses":{"200":{"description":"Token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenIdentity"}}}},"401":{"description":"Missing, invalid, expired or not yet valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused by the token's IP filter, or its owner left","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/dns/zones":{"get":{"summary":"List DNS zones","description":"dns:read. A zone-scoped token sees only its zones.","operationId":"listDnsZones","responses":{"200":{"description":"Zones","content":{"application/json":{"schema":{"type":"object","properties":{"zones":{"type":"array","items":{"type":"object","properties":{"zone":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}},"post":{"summary":"Add a DNS zone","description":"dns:create. Refused (token_resource_denied) for a zone-scoped token.","operationId":"createDnsZone","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["zone"],"properties":{"zone":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"}}}}}},"403":{"description":"Not granted, or the token is limited to certain zones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The zone exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/dns/zones/{zone}":{"get":{"summary":"A DNS zone and its record sets","description":"dns:read. SOA left out.","operationId":"getDnsZone","parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Zone","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Outside the token's zones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such zone in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a DNS zone","description":"dns:delete.","operationId":"deleteDnsZone","parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"403":{"description":"Outside the token's zones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such zone in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/dns/zones/{zone}/records":{"post":{"summary":"Create or replace a record set","description":"dns:update. Replaces every value of that name and type.","operationId":"putDnsRecords","parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsRecordSet"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"400":{"description":"Bad record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not granted, or outside the token's zones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a record set","description":"dns:delete. Send name and type.","operationId":"deleteDnsRecords","parameters":[{"name":"zone","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsRecordSet"}}}},"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"403":{"description":"Not granted, or outside the token's zones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pricing":{"get":{"summary":"The published price list","description":"Public, no key. `current` is the list in force; `scheduled` lists take effect later. Prices are RWF per `pricedPer`; usage counts `counts` (e.g. MiB-hours priced per GiB-hour). A price never goes up with less than 30 days' notice, and usage is priced by the list in force when it happened. `freePerMonth` applies only to a workspace whose owner verified a Rwandan mobile number; each number unlocks one workspace, for good. `plans` are the tiers (Free, Hobby, Pro, Enterprise) with the minimum and limits in force now; each list also carries its own `plans`, and a higher minimum or a lower limit gets the same 30 days' notice. `planTerms` explains how a minimum becomes usage credit.","operationId":"getPricing","security":[],"responses":{"200":{"description":"Price lists","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/messages":{"post":{"summary":"Send an SMS","operationId":"sendMessage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage"}}}},"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResult"}}}},"402":{"description":"Insufficient wallet balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Recipient opted out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/messages/preview":{"post":{"summary":"Preview segments without sending","operationId":"previewMessage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage"}}}},"responses":{"200":{"description":"Segment info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segments"}}}}}}},"/v1/domains/rw/{name}":{"get":{"summary":"Check .rw domain availability","operationId":"checkRwDomain","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Availability","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"available":{"type":["boolean","null"]}}}}}}}}},"/v1/projects":{"get":{"summary":"List projects","description":"deployment:read. A project-scoped token sees only its projects.","operationId":"listProjects","responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}}}}}},"post":{"summary":"Create a typed project","description":"deployment:create. Refused (token_resource_denied) for a project-scoped token.","operationId":"createProject","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProject"}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}}}}}}}}},"/v1/projects/{id}":{"get":{"summary":"Get a project","description":"deployment:read. 403 token_resource_denied when the project is outside the token's scope; 404 when it is not in the workspace. Every /v1/projects/{id}/… route, and /v1/cron/{id}, /v1/firewall/{id} and /v1/domains/{id}, follow the same project scope.","operationId":"getProject","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/search":{"get":{"summary":"Search domain availability and price","operationId":"searchDomains","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"A bare name (checked across popular TLDs) or a full domain."}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSearchResults"}}}}}}},"/v1/projects/{id}/domains":{"get":{"summary":"List a project's custom domains","operationId":"listProjectDomains","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Domains","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/CustomDomain"}}}}}}}}},"post":{"summary":"Connect a domain to a project","description":"Connect a domain you own (returns DNS records to add), or claim a *.bweze.app subdomain (instant).","operationId":"connectProjectDomain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"}}}}}},"responses":{"200":{"description":"Connected","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"$ref":"#/components/schemas/CustomDomain"},"vanity":{"type":"boolean"},"instructions":{"type":"object"}}}}}},"409":{"description":"Domain already attached or reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/register-domain":{"get":{"summary":"List a project's domain registrations","operationId":"listRegistrations","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Registrations, and the workspace's saved owner (used by a purchase that sends no registrant; null when none is saved)","content":{"application/json":{"schema":{"type":"object","properties":{"registrations":{"type":"array","items":{"$ref":"#/components/schemas/DomainRegistration"}},"registrant":{"oneOf":[{"$ref":"#/components/schemas/Registrant"},{"type":"null"}]}}}}}}}},"post":{"summary":"Buy a domain through BWEZE","description":"Register a domain in the buyer's name and attach it to the project. Spends money: the first year's price (RWF, from the price list; search first to see it) is taken from the workspace's wallet up front, also for a purchase BWEZE fulfils by hand (status requested), and goes back to the wallet if the domain cannot be registered (status failed). Refused with 402 when the available balance cannot cover it. `registrant` is the owner on record; it is saved, and a later purchase without it uses the workspace's saved details.","operationId":"buyDomain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"registrant":{"$ref":"#/components/schemas/Registrant"}}}}}},"responses":{"200":{"description":"Paid for and recorded (registered, requested or, if the registrar refused it, failed and refunded)","content":{"application/json":{"schema":{"type":"object","properties":{"registration":{"$ref":"#/components/schemas/DomainRegistration"}}}}}},"400":{"description":"invalid_domain, invalid_registrant, registrant_required (no registrant given and none saved), or domain_not_sold (no price for it: BWEZE sells one label under a listed suffix, e.g. name.com or name.co.rw)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_balance: the available balance cannot cover the price. Nothing was charged. Top up, then retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["insufficient_balance"]},"message":{"type":"string"},"priceMinor":{"type":"integer","description":"RWF"},"availableMinor":{"type":"integer","description":"RWF"},"docs":{"type":"string","format":"uri"}}}}}}}},"409":{"description":"domain_taken (already registered elsewhere) or domain_unavailable (already being bought through BWEZE). Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}":{"delete":{"summary":"Detach a custom domain","operationId":"deleteDomain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/verify":{"post":{"summary":"Re-check a domain's DNS and update status","operationId":"verifyDomain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"$ref":"#/components/schemas/CustomDomain"}}}}}}}}},"/v1/projects/{id}/analytics":{"get":{"summary":"Project traffic analytics","operationId":"projectAnalytics","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer"},"description":"Look-back window (default 30, max 90)."}],"responses":{"200":{"description":"Analytics","content":{"application/json":{"schema":{"type":"object","properties":{"analytics":{"type":"object"}}}}}}}}},"/v1/projects/{id}/cron":{"get":{"summary":"List a project's scheduled jobs","operationId":"listCronJobs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Jobs","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/CronJob"}}}}}}}}},"post":{"summary":"Schedule a job","operationId":"createCronJob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","schedule","target_url"],"properties":{"name":{"type":"string"},"schedule":{"type":"string"},"target_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/CronJob"}}}}}}}}},"/v1/projects/{id}/exec":{"post":{"summary":"Run a command in the project's container","description":"Runs a one-shot command inside the project's running container and returns its output. Secret key only; requires terminal:exec. 30s timeout, output capped at 256KB. Gated by the BWEZE_PUBLIC_TERMINAL_EXEC kill switch (403 disabled when off).","operationId":"execCommand","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["command"],"properties":{"command":{"type":"string","description":"The command to run (trimmed; max 8192 chars)."}}}}}},"responses":{"200":{"description":"Command output","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecResult"}}}},"403":{"description":"Public terminal exec disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"No running container - deploy first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/services":{"get":{"summary":"List a project's services","description":"deployment:read; project-scoped.","operationId":"listProjectServices","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Services","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}}}}},"/v1/services/{id}":{"get":{"summary":"Get a service","description":"deployment:read. Scoped by the service's project: 403 token_resource_denied outside the token's projects; a service in no project needs a token that covers every project.","operationId":"getService","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"$ref":"#/components/schemas/Service"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Change a service's settings","description":"deployment:update. Only the fields sent change; null or \"\" clears a command (a cron job keeps needing one). 400 invalid_port for a worker or cron job's port, invalid_cron_schedule for a bad schedule or a schedule on anything but a cron job.","operationId":"updateService","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceSettings"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"$ref":"#/components/schemas/Service"},"changed":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Invalid setting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/services/{id}/jobs":{"get":{"summary":"List a service's job runs","description":"Pre-deploy commands, one-off jobs and cron runs, newest first. A cron job also gets its schedule and next three run times (UTC). deployment:read.","operationId":"listJobRuns","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"1 to 200 (default 50)."}],"responses":{"200":{"description":"Runs","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/JobRun"}},"cron":{"type":"object","nullable":true,"properties":{"schedule":{"type":"string"},"timeout_seconds":{"type":"integer"},"next":{"type":"array","items":{"type":"string","format":"date-time"}}}}}}}}}}},"post":{"summary":"Run a command once on the service's live release","description":"A new instance with the release's image, environment variables and secrets runs the command as /bin/sh -c and is stopped at its time limit. Secret key only; requires terminal:exec. At most 3 at once per service (429 too_many_jobs); 409 not_deployed before the first deploy; 402 workspace_suspended while hosting is stopped. Billed like the service while it runs.","operationId":"runJob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["command"],"properties":{"command":{"type":"string","description":"Max 4096 chars."},"timeout_seconds":{"type":"integer","description":"60 to 43200 (default 3600)."}}}}}},"responses":{"201":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/JobRun"}}}}}},"409":{"description":"Not deployed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many jobs running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/services/{id}/jobs/{jobId}":{"get":{"summary":"Get a job run and its log lines","description":"Lines after ?after=<line id>, up to 2000, oldest first. To follow a run, call again with the last id until job.status is succeeded, failed or cancelled and no lines come back. deployment:read.","operationId":"getJobRun","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Run and lines","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/JobRun"},"logs":{"type":"array","items":{"$ref":"#/components/schemas/JobLogLine"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/services/{id}/jobs/{jobId}/cancel":{"post":{"summary":"Stop a one-off job or a cron run","description":"Its pod is killed. terminal:exec. 409 not_cancellable for a pre-deploy command, already_finished for a run that ended.","operationId":"cancelJobRun","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stopped","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/JobRun"}}}}}},"409":{"description":"Not cancellable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cron/{id}":{"patch":{"summary":"Enable or disable a scheduled job","operationId":"setCronEnabled","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}},"delete":{"summary":"Delete a scheduled job","operationId":"deleteCronJob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/v1/projects/{id}/firewall":{"get":{"summary":"List a project's IP allow/block rules","operationId":"listFirewallRules","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Rules","content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/FirewallRule"}}}}}}}}},"post":{"summary":"Add an IP allow/block rule","operationId":"createFirewallRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","cidr"],"properties":{"action":{"type":"string","enum":["allow","block"]},"cidr":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"$ref":"#/components/schemas/FirewallRule"}}}}}}}}},"/v1/firewall/{id}":{"delete":{"summary":"Delete an IP allow/block rule","operationId":"deleteFirewallRule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/v1/backends":{"get":{"summary":"List backends","description":"backend:read. A backend-scoped token sees only its backends.","operationId":"listBackends","responses":{"200":{"description":"Backends","content":{"application/json":{"schema":{"type":"object","properties":{"backends":{"type":"array","items":{"$ref":"#/components/schemas/Backend"}}}}}}}}},"post":{"summary":"Provision a backend","description":"backend:create. Creates the stack but does not start it - call /v1/backends/{id}/deploy to boot the containers. Refused (token_resource_denied) for a backend-scoped token.","operationId":"createBackend","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"2-31 chars: lowercase letters, digits, hyphens."}}}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"backend":{"$ref":"#/components/schemas/Backend"}}}}}}}}},"/v1/backends/{id}":{"get":{"summary":"Get a backend and its live status","operationId":"getBackend","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Backend","content":{"application/json":{"schema":{"type":"object","properties":{"backend":{"$ref":"#/components/schemas/Backend"},"status":{"type":"object"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a backend (destroys the stack AND its data)","description":"Safe by default: set confirm to the backend's name and force:true.","operationId":"deleteBackend","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm","force"],"properties":{"confirm":{"type":"string","description":"Must equal the backend's name."},"force":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/backends/{id}/deploy":{"post":{"summary":"Start (or restart) a backend's containers","operationId":"deployBackend","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deploying","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"object"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/backends/{id}/keys":{"get":{"summary":"Fetch a backend's connection credentials","description":"Returns URL + anon/service-role keys + postgres password. Requires backend:create.","operationId":"getBackendKeys","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"$ref":"#/components/schemas/BackendKeys"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}