{"openapi":"3.1.0","info":{"title":"Swyftstack API","version":"1.0.0","description":"Manage PostgreSQL databases, object storage, and backups programmatically. Authenticate with an API key (Authorization: Bearer sk_live_…) or connect an AI client with the browser device-login flow. All requests are org-scoped and every action is audited.","contact":{"name":"Swyftstack support","url":"https://swyftstack.com/support"}},"servers":[{"url":"https://swyftstack.com/v1","description":"Production"},{"url":"https://swyftstack.com/api/v1","description":"Production (equivalent alias)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Device","description":"Device Authorization Grant (RFC 8628) — connect without pasting a key."},{"name":"Projects","description":"Projects — the container databases and buckets live in."},{"name":"Databases","description":"PostgreSQL databases."},{"name":"Network & security","description":"IP allow-list, Row-Level Security, SSL."},{"name":"Backups","description":"Manual + automatic backups."},{"name":"Imports","description":"Import an external database."},{"name":"Storage","description":"Object-storage buckets + files."},{"name":"Account","description":"Usage, limits, billing, API keys, audit logs."},{"name":"Agent","description":"AI-optimized status + recommendations."}],"paths":{"/device/authorize":{"post":{"tags":["Device"],"summary":"Start a device login","security":[],"description":"Begin a Device Authorization Grant. Returns a device_code (poll with it) and a user_code (the human enters it at /device).","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string"},"scope_preset":{"type":"string","enum":["read_only","developer","full_access"]}}}}}},"responses":{"200":{"description":"Device + user codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}}}}},"/device/token":{"post":{"tags":["Device"],"summary":"Poll for the device login result","security":[],"description":"Poll with the device_code. Returns authorization_pending / slow_down / access_denied / expired_token until approved, then the minted api_key exactly once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string"}}}}}},"responses":{"200":{"description":"The minted API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"400":{"description":"Still pending / denied / expired"}}}},"/projects":{"get":{"tags":["Projects"],"summary":"List projects","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Projects"],"summary":"Create a project","description":"Create the container databases and buckets are created inside. Requires account:read plus database:create OR storage:create. Counts against the plan's project limit.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}}}},"/projects/{id}":{"get":{"tags":["Projects"],"summary":"Get a project","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Project id (proj_…).","schema":{"type":"string"}}]}},"/databases":{"get":{"tags":["Databases"],"summary":"List databases","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Databases"],"summary":"Create a database","description":"Requires an API key with scope(s): database:create.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["project","name"],"properties":{"project":{"type":"string"},"name":{"type":"string"},"db_user":{"type":"string"},"password":{"type":"string"}}}}}}}},"/databases/{id}":{"get":{"tags":["Databases"],"summary":"Get a database","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]},"delete":{"tags":["Databases"],"summary":"Delete a database (destructive)","description":"Requires an API key with scope(s): database:delete.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/restart":{"post":{"tags":["Databases"],"summary":"Restart a database","description":"Requires an API key with scope(s): database:update.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/pause":{"post":{"tags":["Databases"],"summary":"Pause a database","description":"Requires an API key with scope(s): database:update.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/resume":{"post":{"tags":["Databases"],"summary":"Resume a paused database","description":"Requires an API key with scope(s): database:update.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/metrics":{"get":{"tags":["Databases"],"summary":"Database metrics","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}},{"name":"hours","in":"query","description":"Look-back window in hours.","schema":{"type":"integer"}}]}},"/databases/{id}/rotate-password":{"post":{"tags":["Databases"],"summary":"Rotate the password","description":"Requires an API key with scope(s): database:update.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/connection":{"get":{"tags":["Databases"],"summary":"Get connection details","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/ssl":{"get":{"tags":["Network & security"],"summary":"Get SSL/TLS status","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]},"put":{"tags":["Network & security"],"summary":"Require or stop requiring TLS","description":"Set this database's sslmode. `require` refuses a plaintext fallback; `prefer` allows it. Update your DATABASE_URL to sslmode=require BEFORE enabling. Open connections are unaffected; new ones fail if the client cannot negotiate TLS. Reversible at any time.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ssl_mode":{"type":"string","enum":["require","prefer"]},"require":{"type":"boolean","description":"Shorthand for ssl_mode."}}}}}}}},"/databases/{id}/allowlist":{"get":{"tags":["Network & security"],"summary":"Get the IP allow-list","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]},"put":{"tags":["Network & security"],"summary":"Replace the IP allow-list","description":"Requires an API key with scope(s): database:update.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"string"}}}}}}}}},"/databases/{id}/rls":{"get":{"tags":["Network & security"],"summary":"Row-Level Security overview","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]},"post":{"tags":["Network & security"],"summary":"Enable/disable RLS on a table","description":"Requires an API key with scope(s): database:update.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["table","enabled"],"properties":{"table":{"type":"string"},"schema":{"type":"string"},"enabled":{"type":"boolean"},"force":{"type":"boolean"}}}}}}}},"/databases/{id}/backups":{"get":{"tags":["Backups"],"summary":"List backups","description":"Requires an API key with scope(s): backup:list.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]},"post":{"tags":["Backups"],"summary":"Trigger a manual backup","description":"Requires an API key with scope(s): backup:create.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/backups/{backupId}":{"get":{"tags":["Backups"],"summary":"Get a backup","description":"Requires an API key with scope(s): backup:list.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}},{"name":"backupId","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Backups"],"summary":"Delete a backup (destructive)","description":"Requires an API key with scope(s): backup:delete.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}},{"name":"backupId","in":"path","required":true,"schema":{"type":"string"}}]}},"/databases/{id}/backups/{backupId}/restore":{"post":{"tags":["Backups"],"summary":"Restore from a backup","description":"Requires an API key with scope(s): backup:restore.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}},{"name":"backupId","in":"path","required":true,"schema":{"type":"string"}}]}},"/databases/{id}/backups/{backupId}/pin":{"post":{"tags":["Backups"],"summary":"Pin/unpin a backup","description":"Requires an API key with scope(s): backup:create.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}},{"name":"backupId","in":"path","required":true,"schema":{"type":"string"}}]}},"/databases/{id}/export":{"get":{"tags":["Backups"],"summary":"Latest downloadable export","description":"Requires an API key with scope(s): backup:download.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/recovery":{"get":{"tags":["Backups"],"summary":"Point-in-time recovery status","description":"Requires an API key with scope(s): backup:list.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}]}},"/databases/{id}/recovery/restore-request":{"post":{"tags":["Backups"],"summary":"Request a point-in-time restore","description":"Requires an API key with scope(s): backup:restore.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Database id (e.g. db_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_time":{"type":"string","format":"date-time"},"reason":{"type":"string"}}}}}}}},"/imports":{"get":{"tags":["Imports"],"summary":"List imports","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Imports"],"summary":"Import an external database","description":"Requires an API key with scope(s): database:create.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["project","name","source_url"],"properties":{"project":{"type":"string"},"name":{"type":"string"},"source_url":{"type":"string"},"same_credentials":{"type":"boolean"},"username":{"type":"string"},"password":{"type":"string"}}}}}}}},"/imports/{importId}":{"get":{"tags":["Imports"],"summary":"Get import status","description":"Requires an API key with scope(s): database:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"importId","in":"path","required":true,"schema":{"type":"string"}}]}},"/buckets":{"get":{"tags":["Storage"],"summary":"List buckets","description":"Requires an API key with scope(s): storage:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Storage"],"summary":"Create a bucket","description":"Requires an API key with scope(s): storage:create.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["project","name"],"properties":{"project":{"type":"string"},"name":{"type":"string"},"public":{"type":"boolean"}}}}}}}},"/buckets/{id}":{"get":{"tags":["Storage"],"summary":"Get a bucket","description":"Requires an API key with scope(s): storage:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Bucket id (e.g. bucket_…).","schema":{"type":"string"}}]},"delete":{"tags":["Storage"],"summary":"Delete a bucket (destructive)","description":"Requires an API key with scope(s): storage:delete.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Bucket id (e.g. bucket_…).","schema":{"type":"string"}}]}},"/buckets/{id}/objects":{"get":{"tags":["Storage"],"summary":"List objects","description":"Requires an API key with scope(s): storage:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Bucket id (e.g. bucket_…).","schema":{"type":"string"}},{"name":"prefix","in":"query","schema":{"type":"string"}}]},"post":{"tags":["Storage"],"summary":"Upload an object","description":"Upload one object. Send the raw bytes with the file's own Content-Type, or a JSON envelope { content, content_type, encoding } with Content-Type: application/json. `?content_type=` overrides both; with neither, the type is inferred from the key's file extension.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Bucket id (e.g. bucket_…).","schema":{"type":"string"}},{"name":"key","in":"query","required":true,"description":"Object key/path, e.g. images/logo.png.","schema":{"type":"string"}},{"name":"content_type","in":"query","description":"Explicit MIME type for the stored object. Wins over every other signal.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"File contents (UTF-8 text, or base64 when encoding=base64)."},"content_type":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"}}}}}}}},"/buckets/{id}/objects/{key}":{"delete":{"tags":["Storage"],"summary":"Delete one object (destructive)","description":"Requires an API key with scope(s): storage:delete.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Bucket id (e.g. bucket_…).","schema":{"type":"string"}},{"name":"key","in":"path","required":true,"description":"Object key. Slashes are kept as path segments.","schema":{"type":"string"}}]}},"/buckets/{id}/visibility":{"put":{"tags":["Storage"],"summary":"Make a bucket public or private","description":"Requires an API key with scope(s): storage:update.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Bucket id (e.g. bucket_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["public"],"properties":{"public":{"type":"boolean"}}}}}}}},"/buckets/{id}/public-url":{"post":{"tags":["Storage"],"summary":"Get an object's public URL","description":"Requires an API key with scope(s): storage:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Bucket id (e.g. bucket_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}}}}}},"/account/usage":{"get":{"tags":["Account"],"summary":"Usage vs plan limits","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/account/limits":{"get":{"tags":["Account"],"summary":"Plan limits + features","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/account/billing":{"get":{"tags":["Account"],"summary":"Billing + trial state","description":"Requires an API key with scope(s): billing:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/account/api-keys":{"get":{"tags":["Account"],"summary":"List API keys","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/account/audit-logs":{"get":{"tags":["Account"],"summary":"API + agent activity log","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/agent/status":{"get":{"tags":["Agent"],"summary":"AI-optimized account snapshot","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/agent/recommendations":{"get":{"tags":["Agent"],"summary":"Actionable recommendations","description":"Requires an API key with scope(s): account:read.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_…","description":"Your Swyftstack API key. Create one under Settings → API keys, or connect an AI client with device login (no key to paste)."}},"schemas":{"DataEnvelope":{"type":"object","properties":{"data":{},"meta":{"type":"object"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Scopes":{"type":"string","enum":["database:create","database:read","database:update","database:delete","storage:create","storage:read","storage:update","storage:delete","backup:create","backup:restore","backup:delete","backup:download","backup:list","account:read","billing:read","team:read"]}},"responses":{"Unauthorized":{"description":"Missing/invalid/expired/revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Key lacks the scope, or a destructive op without dangerous enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource absent or not in the key's org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests. Three nested ceilings apply to every request: 1000/minute per API key per project (requests with no project in scope share one bucket of the same size for the key), 3000/minute per API key across all projects, and 6000/minute per organization across all keys. Expensive operations have tighter per-key limits on top. Retry after the window in `Retry-After` / `X-RateLimit-Reset`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed in the window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}