Skip to content
Sign in

Management API

SwiftFS Cloud's management API is the JSON API behind the web console: accounts, organizations, members, buckets, access keys, usage and billing. It is separate from the S3 API, which stores and serves the data itself (the S3 API).

Base URLhttps://<console host>/api/v1
FormatJSON in and out; send Content-Type: application/json
AuthenticationThe session cookie set by POST /auth/login
DescriptionOpenAPI 3.0

Programmatic access is through the S3 API

The management API authenticates browser sessions, so it suits the console and scripts that sign in as a user. To store and fetch data from your applications, use the S3 API with an access key.

Conventions

  • Errors always have the shape {"error": {"code": "not_found", "message": "…", "requestId": "…", "field": "…"}}. code is stable; message is written for people; field names the input to fix, when there is one.
  • Every response carries an X-SwiftFS-Request-ID header.
  • Amounts of money are integers in the currency's minor unit (cents, francs), with a formatted twin (totalFormatted). Rates and quantities are decimal strings, never floating point.
  • Times are RFC 3339, in UTC.
  • Requests that change something must come from an allowed origin (browsers), and are rate-limited per user. Sign-in, sign-up and password resets are rate-limited per IP address.
  • Organizations you don't belong to answer 404, whether or not they exist.

Endpoints

Public

  • GET/public/infoPublic service information (no sign-in needed)
  • GET/public/pricingThe default plan's prices, now and scheduled (what the pricing page shows) (no sign-in needed)

Account

  • POST/auth/signupCreate an account and sign in (no sign-in needed)
  • POST/auth/loginSign in (no sign-in needed)
  • POST/auth/logoutSign out (no sign-in needed)
  • POST/auth/verify-emailConfirm an email address with the token from the verification email (no sign-in needed)
  • POST/auth/resend-verificationSend a new verification email
  • POST/auth/password-reset/requestEmail a password-reset link (the response never reveals whether the account exists) (no sign-in needed)
  • POST/auth/password-reset/confirmSet a new password; every session of the user is signed out (no sign-in needed)
  • GET/meThe signed-in user and their organizations
  • PATCH/meUpdate the signed-in user's name
  • POST/invitations/acceptJoin an organization with an invitation token. The invitation must be for your verified email.

Organizations

  • POST/orgsCreate an organization (you become its owner). Requires a verified email.
  • GET/orgs/{org}An organization you belong to
  • PATCH/orgs/{org}Rename an organization (admin, owner)

Members and invitations

  • GET/orgs/{org}/membersMembers of an organization
  • PATCH/orgs/{org}/members/{userId}Change a member's role. Admins manage everyone but owners; the last owner cannot be demoted. Demotion to viewer revokes the member's access keys.
  • DELETE/orgs/{org}/members/{userId}Remove a member, or leave the organization (your own user ID). Revokes the member's access keys.
  • GET/orgs/{org}/invitationsPending invitations (admin, owner)
  • POST/orgs/{org}/invitationsInvite someone by email (admins invite any role but owner)
  • DELETE/orgs/{org}/invitations/{invitationId}Cancel a pending invitation

Buckets and objects

  • GET/orgs/{org}/bucketsBuckets with current usage
  • POST/orgs/{org}/bucketsCreate a bucket (developer and up). Bucket names are global across SwiftFS.
  • GET/orgs/{org}/buckets/{bucket}A bucket with current usage
  • DELETE/orgs/{org}/buckets/{bucket}Delete an empty bucket
  • GET/orgs/{org}/buckets/{bucket}/objectsList objects, grouped into folders at the delimiter
  • GET/orgs/{org}/buckets/{bucket}/objectAn object's details (not its data; use a presigned GET for that)
  • DELETE/orgs/{org}/buckets/{bucket}/objectDelete an object
  • POST/orgs/{org}/buckets/{bucket}/presignA short-lived URL to download (GET) or upload (PUT) an object directly against the S3 API

Access keys

  • GET/orgs/{org}/access-keysS3 access keys (admins see all; developers see their own)
  • POST/orgs/{org}/access-keysCreate an S3 access key. The secret is returned once and cannot be retrieved again.
  • DELETE/orgs/{org}/access-keys/{keyId}Revoke an access key (your own, or any with admin rights)

Usage and charges

  • GET/orgs/{org}/usageMetered usage over whole UTC hours [from, to). Default the current month.
  • GET/orgs/{org}/usage/currentWhat the organization stores right now
  • GET/orgs/{org}/usage/seriesUsage in hourly or daily UTC bins, for charts. Default the last 30 days, daily.
  • GET/orgs/{org}/pricingThe prices in effect for the organization now, and changes scheduled over the next year
  • GET/orgs/{org}/costsCharges for one UTC month, line by line. An estimate of what has accrued until the month is over and fully measured.

Billing and payments

  • GET/orgs/{org}/billingBilling details, balance due and credits (admin, owner)
  • PATCH/orgs/{org}/billingChange billing details. Invoices already issued keep the details they were issued with.
  • POST/orgs/{org}/billing/payment-methodsStart saving a card (Stripe). The browser finishes it with the client secret; the card appears once Stripe confirms.
  • DELETE/orgs/{org}/billing/payment-methods/{methodId}Remove a saved card
  • GET/orgs/{org}/invoicesIssued invoices, newest first (admin, owner)
  • GET/orgs/{org}/invoices/{invoiceId}An issued invoice with its lines (admin, owner)
  • POST/orgs/{org}/invoices/{invoiceId}/paymentsPay what the invoice still owes, with the saved card or a mobile-money prompt on the payer's phone. The outcome may arrive later; poll the invoice.

Activity

  • GET/orgs/{org}/auditSecurity-relevant events, newest first (admin, owner)

Other

  • GET/orgs/{org}/api-tokensThe organization's API tokens (never their secrets). Admins and owners.
  • POST/orgs/{org}/api-tokensCreate a read-only API token for the organization's own servers. The token is returned once.
  • DELETE/orgs/{org}/api-tokens/{tokenId}Revoke an API token. It stops working at once.
  • GET/tenantThe token's organization and whether it can store new data
  • GET/tenant/usage/currentWhat the token's organization stores right now, across all its buckets
  • GET/tenant/pricingThe prices (and allowances) in effect for the token's organization now, and changes scheduled over the next year
  • GET/tenant/costsThe token's organization's charges for one UTC month, line by line (the same figures as /orgs/{org}/costs). An estimate of what has accrued until the month is over and fully measured; credits and tax are applied on the invoice.