API reference

Generated from openapi.yaml (OpenAPI 3.1.0), which you can load into any OpenAPI tool or client generator. Client calls go to https://auth.wizgu.com/api/v2.

App Sign-in Account Identities Sessions Remote Config Push Files Data Admin Admin users Admin tokens Admin points Admin Remote Config Admin push Admin files Admin data Discovery

App

The calling app's public profile.

get /api/v2/app The app's public profile
Auth: App key
Responses
  • 200 The app.
    • data object
      • name string
      • require_verified_email boolean
      • deep_link_url string or null
      • branding object
        • logo_url string or null
        • primary_color string or null
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Sign-in

Email and password, Google, Apple, email codes, tokens and sign-out.

post /api/v2/auth/sign-up Create an account with email and password
Auth: App key

Creates the user in this app's pool and signs them in. Limit 10 a minute per IP.

Body (application/json)
  • email* string (email)
  • password* string · At least 8 characters.
  • first_name string
  • last_name string
Responses
  • 201 Tokens and the user.
    • data object
      • access_token string · A JWT; send as Authorization: Bearer ….
      • token_type "Bearer"
      • expires_in integer · Seconds until the access token expires.
      • refresh_token string · Keep in secure storage; send only to /auth/token/refresh.
      • user object
        • uid string · The user's public id (a lowercase ULID).
        • email string
        • email_verified boolean
        • first_name string or null
        • last_name string or null
        • photo_url string or null
        • created_at string (date-time)
  • 403 app/user-limit-reached: the app takes no new accounts
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 409 auth/email-already-in-use
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 422 auth/weak-password or validation/failed
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/sign-in Sign in with email and password
Auth: App key

Limits 10 a minute per email and IP, 30 a minute per IP.

Body (application/json)
  • email* string (email)
  • password* string
Responses
  • 200 Tokens and the user.
    • data object
      • access_token string · A JWT; send as Authorization: Bearer ….
      • token_type "Bearer"
      • expires_in integer · Seconds until the access token expires.
      • refresh_token string · Keep in secure storage; send only to /auth/token/refresh.
      • user object
        • uid string · The user's public id (a lowercase ULID).
        • email string
        • email_verified boolean
        • first_name string or null
        • last_name string or null
        • photo_url string or null
        • created_at string (date-time)
  • 401 auth/invalid-credential, the same for an unknown email and a wrong password
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 403 auth/user-disabled
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/google Sign in with Google
Auth: App key

Verifies the ID token from Google's sign-in SDK against the app's Google client IDs. Signs in, links to a verified account with the same email, or creates a verified account.

Body (application/json)
  • id_token* string
  • nonce string · The nonce given to Google's SDK, if any.
Responses
  • 200 Tokens, the user, and whether the account was just created.
    • data object
      • access_token string · A JWT; send as Authorization: Bearer ….
      • token_type "Bearer"
      • expires_in integer · Seconds until the access token expires.
      • refresh_token string · Keep in secure storage; send only to /auth/token/refresh.
      • user object
        • uid string · The user's public id (a lowercase ULID).
        • email string
        • email_verified boolean
        • first_name string or null
        • last_name string or null
        • photo_url string or null
        • created_at string (date-time)
      • is_new_user boolean
  • 403 auth/provider-not-enabled, auth/unverified-email, auth/user-disabled, app/user-limit-reached (a new account)
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 409 auth/account-exists-with-different-credential
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 503 unavailable: Google couldn't be reached
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/apple Sign in with Apple
Auth: App key

Verifies the identity token from Sign in with Apple. Send the authorization_code too, so the Apple refresh token can be revoked when the account is deleted (App Store requirement). Apple gives the user's name only on the first sign-in: pass it here.

Body (application/json)
  • identity_token* string
  • nonce string · The raw nonce whose SHA-256 was given to Apple.
  • authorization_code string
  • first_name string
  • last_name string
Responses
  • 200 Tokens, the user, and whether the account was just created.
    • data object
      • access_token string · A JWT; send as Authorization: Bearer ….
      • token_type "Bearer"
      • expires_in integer · Seconds until the access token expires.
      • refresh_token string · Keep in secure storage; send only to /auth/token/refresh.
      • user object
        • uid string · The user's public id (a lowercase ULID).
        • email string
        • email_verified boolean
        • first_name string or null
        • last_name string or null
        • photo_url string or null
        • created_at string (date-time)
      • is_new_user boolean
  • 403 auth/provider-not-enabled, auth/unverified-email, auth/user-disabled, app/user-limit-reached (a new account)
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 409 auth/account-exists-with-different-credential
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 503 unavailable
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/email-code/send Email a sign-in code (passwordless)
Auth: App key

Emails a 6-digit code, and a magic link when the app has a deep-link URL. The answer is the same for every email. Limits 10 a minute per IP, 5 an hour per email.

Body (application/json)
  • email* string (email)
Responses
  • 200 A code was emailed (or the answer is the same as if it had been).
    • data object
      • expires_in integer · Seconds the code stays valid.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/email-code/verify Sign in with an emailed code
Auth: App key

Creates the account when the email is new in this app. The email counts as verified.

Body (application/json)
  • email* string (email)
  • code* string
  • first_name string · For a new account.
  • last_name string · For a new account.
Responses
  • 200 Tokens, the user, and whether the account was just created.
    • data object
      • access_token string · A JWT; send as Authorization: Bearer ….
      • token_type "Bearer"
      • expires_in integer · Seconds until the access token expires.
      • refresh_token string · Keep in secure storage; send only to /auth/token/refresh.
      • user object
        • uid string · The user's public id (a lowercase ULID).
        • email string
        • email_verified boolean
        • first_name string or null
        • last_name string or null
        • photo_url string or null
        • created_at string (date-time)
      • is_new_user boolean
  • 400 auth/invalid-code, auth/code-expired
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 403 app/user-limit-reached (a new account)
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/token/refresh Get new tokens with the refresh token
Auth: App key

The old refresh token is used up: store the new one. Sending a used refresh token again after 30 seconds counts as theft and ends the session. Limit 30 a minute per IP.

Body (application/json)
  • refresh_token* string
Responses
  • 200 New tokens.
    • data object
      • access_token string · A JWT; send as Authorization: Bearer ….
      • token_type "Bearer"
      • expires_in integer · Seconds until the access token expires.
      • refresh_token string · Keep in secure storage; send only to /auth/token/refresh.
  • 401 auth/refresh-token-revoked: sign in again
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/token/from-v1 Trade a v1 token for v2 tokens
Auth: App key

For apps moving from API v1: a valid v1 token of this app becomes a v2 session, so the user stays signed in. The v1 token stops working. The session keeps the v1 sign-in time, so sensitive actions ask for the password once. Limit 30 a minute per IP.

Body (application/json)
  • v1_token* string · The token v1 /login returned.
Responses
  • 200 Tokens and the user.
    • data object
      • access_token string · A JWT; send as Authorization: Bearer ….
      • token_type "Bearer"
      • expires_in integer · Seconds until the access token expires.
      • refresh_token string · Keep in secure storage; send only to /auth/token/refresh.
      • user object
        • uid string · The user's public id (a lowercase ULID).
        • email string
        • email_verified boolean
        • first_name string or null
        • last_name string or null
        • photo_url string or null
        • created_at string (date-time)
  • 401 auth/invalid-token: expired, signed out or not this app's; sign in again
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 403 auth/user-disabled
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/password/forgot Email a password-reset code
Auth: App key

The same answer whether or not the email has an account. Limits 5 a minute per IP, 10 an hour per email.

Body (application/json)
  • email* string (email)
Responses
  • 200 A code was emailed (or the answer is the same as if it had been).
    • data object
      • expires_in integer · Seconds the code stays valid.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/password/reset Set a new password with the emailed code
Auth: App key

Ends every session of the account. Limit 5 a minute per IP.

Body (application/json)
  • email* string (email)
  • code* string
  • password* string
Responses
  • 204 The password was changed.
  • 400 auth/invalid-code, auth/code-expired
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 422 auth/weak-password
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/reauthenticate Confirm the password again for a sensitive action
Auth: App key and access token

Renews the sign-in time and returns a new access token (the refresh token stays). Call it when an action answers auth/requires-recent-login. Limit 5 a minute per user.

Body (application/json)
  • password* string
Responses
  • 200 A new access token.
    • data object
      • access_token string
      • token_type "Bearer"
      • expires_in integer
  • 400 auth/invalid-credential
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/sign-out Sign out this device
Auth: App key and access token
Responses
  • 204 The session ended.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/sign-out-all Sign out every device of the user in this app
Auth: App key and access token
Responses
  • 204 Every session ended.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Account

The signed-in user's profile, email, password, photo and deletion.

post /api/v2/auth/email/verification/send Email a code that verifies the user's address
Auth: App key and access token

Limits 3 a minute and 10 an hour per user.

Responses
  • 200 A code was emailed (or the answer is the same as if it had been).
    • data object
      • expires_in integer · Seconds the code stays valid.
  • 409 auth/email-already-verified
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/auth/email/verification/confirm Verify the address with the emailed code
Auth: App key and access token

The next access token (after a refresh) has email_verified true.

Body (application/json)
  • code* string
Responses
  • 200 The user.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
  • 400 auth/invalid-code, auth/code-expired
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/me The signed-in user
Auth: App key and access token
Responses
  • 200 The user.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
patch /api/v2/me Change the name or the profile photo
Auth: App key and access token
Body (application/json)
  • first_name string or null
  • last_name string or null
  • photo_file_id string or null · One of the user's own image files; null removes the photo.
Responses
  • 200 The user.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/me Delete the account
Auth: App key and access token

Needs a recent sign-in. Every session ends and the email can sign up again.

Body (application/json)
  • reason string
Responses
  • 204 The account was deleted.
  • 403 auth/requires-recent-login
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/me/email Start changing the email address
Auth: App key and access token

Needs a recent sign-in. Emails a code to the new address.

Body (application/json)
  • email* string (email)
Responses
  • 200 A code was emailed (or the answer is the same as if it had been).
    • data object
      • expires_in integer · Seconds the code stays valid.
  • 403 auth/requires-recent-login
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 409 auth/email-already-in-use
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/me/email/confirm Switch to the new address with its code
Auth: App key and access token
Body (application/json)
  • email* string (email)
  • code* string
Responses
  • 200 The user.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
  • 400 auth/invalid-code, auth/code-expired
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
put /api/v2/me/password Change the password
Auth: App key and access token

The user's other sessions end; this one stays. Limit 5 a minute per user.

Body (application/json)
  • current_password* string
  • password* string
Responses
  • 204 The password was changed.
  • 400 auth/invalid-credential
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 422 auth/weak-password
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/me/photo Upload a profile photo
Auth: App key and access token

A public JPEG, PNG, WebP or GIF within the app's file limits. It replaces the previous photo and shows as photo_url and as the picture claim of new access tokens.

Body (multipart/form-data)
  • photo* string (binary)
Responses
  • 200 The user.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
  • 413 storage/file-too-large, storage/quota-exceeded
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 415 storage/type-not-allowed
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/me/photo Remove the profile photo
Auth: App key and access token
Responses
  • 200 The user.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/me/loyalty Member ID, points and tier
Auth: App key and access token

What v1 /login and /me carried in user. Tiers: silver below 3,000 points, gold below 10,000, platinum from 10,000.

Responses
  • 200 The loyalty status.
    • data object
      • member_id string · The app's member_id_prefix Remote Config parameter and the account number.
      • points integer
      • tier string: silver, gold, platinum
      • next_tier object or null · Null at the top tier.
        • tier string: gold, platinum
        • points_needed integer
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/me/loyalty/history Points added and taken away
Auth: App key and access token
Parameters
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of entries, newest first.
    • data array of object
      • points integer · Negative when points were taken away.
      • description string or null
      • created_at string (date-time)
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Identities

The sign-in methods linked to the user.

get /api/v2/me/identities The user's sign-in methods
Auth: App key and access token
Responses
  • 200 The linked methods.
    • data array of object
      • provider string: password, google, apple
      • email string or null
      • linked_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/me/identities/{provider} Link a sign-in method
Auth: App key and access token

Needs a recent sign-in. The body depends on the provider.

Parameters
provider* path string: password, google, apple
Body (application/json)
  • password string · For password.
  • id_token string · For google.
  • identity_token string · For apple.
  • nonce string · For google and apple.
  • authorization_code string · For apple.
Responses
  • 201 The new identity.
    • data object
      • provider string: password, google, apple
      • email string or null
      • linked_at string (date-time)
  • 409 auth/provider-already-linked, auth/credential-already-in-use
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/me/identities/{provider} Unlink a sign-in method
Auth: App key and access token

Needs a recent sign-in.

Parameters
provider* path string: password, google, apple
Responses
  • 204 Unlinked.
  • 409 auth/last-sign-in-method
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Sessions

The devices the user is signed in on.

get /api/v2/me/sessions The devices the user is signed in on
Auth: App key and access token
Parameters
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of sessions.
    • data array of object
      • id string
      • current boolean
      • provider string
      • signed_in_at string (date-time)
      • auth_time string (date-time)
      • last_used_at string or null (date-time)
      • ip_address string or null
      • user_agent string or null
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/me/sessions/{session} Sign out one device
Auth: App key and access token
Parameters
session* path string
Responses
  • 204 The session ended.
  • 404 An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Remote Config

Parameter values for this caller.

get /api/v2/config Remote Config values for this caller
Auth: App key; access token optional

A bearer token is optional; if sent it must be valid, and it unlocks tier, claim and percentage conditions. Send the ETag back as If-None-Match to get 304 when nothing changed, and wait min_fetch_interval seconds between fetches.

Parameters
platform query string
app_version query string
language query string Else Accept-Language.
instance_id query string 8–128 characters. Buckets percentage rollouts before sign-in.
If-None-Match header string
Responses
  • 200 The values.
    • data object
      • version integer
      • min_fetch_interval integer · Seconds.
      • parameters object · Parameter name → value (string, number, boolean, or a string holding JSON).
  • 304 Nothing changed since that ETag.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Push

Push-token registration and topics.

post /api/v2/push/devices Register the device's push token
Auth: App key; access token optional

With an access token the device is linked to the user until that sign-in ends; without one it is anonymous. Register again after sign-in, sign-out and token changes. The token is never returned.

Body (application/json)
  • provider* string: fcm, apns
  • platform* string: ios, android, web
  • token* string
  • app_version string
  • language string
  • device_id string · From an earlier registration, when the token changed.
Responses
  • 200 The device.
    • data object
      • id string
      • provider string: fcm, apns
      • platform string: ios, android, web
      • app_version string or null
      • language string or null
      • signed_in boolean
      • topics array of string
      • created_at string (date-time)
      • last_seen_at string or null (date-time)
  • 201 The device.
    • data object
      • id string
      • provider string: fcm, apns
      • platform string: ios, android, web
      • app_version string or null
      • language string or null
      • signed_in boolean
      • topics array of string
      • created_at string (date-time)
      • last_seen_at string or null (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/push/devices/{id} The device
Auth: App key
Parameters
id* path string
Responses
  • 200 The device.
    • data object
      • id string
      • provider string: fcm, apns
      • platform string: ios, android, web
      • app_version string or null
      • language string or null
      • signed_in boolean
      • topics array of string
      • created_at string (date-time)
      • last_seen_at string or null (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/push/devices/{id} Forget the device
Auth: App key
Parameters
id* path string
Responses
  • 204 Forgotten.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
put /api/v2/push/devices/{id}/topics/{topic} Follow a topic
Auth: App key

At most 200 topics per device.

Parameters
id* path string
topic* path string
Responses
  • 204 Following.
  • 422 push/too-many-topics
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/push/devices/{id}/topics/{topic} Unfollow a topic
Auth: App key
Parameters
id* path string
topic* path string
Responses
  • 204 Not following.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Files

The user's files.

get /api/v2/files The user's files
Auth: App key and access token
Parameters
folder query string
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of files, with the user's storage figures.
    • data array of object
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
    • meta object
      • next_cursor string or null
      • used_bytes integer
      • quota_bytes integer
      • max_file_bytes integer
      • max_direct_upload_bytes integer or null · Null without S3 storage.
      • allowed_types array of string
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/files Upload a file
Auth: App key and access token

The type is read from the content. The app's size, type and quota limits apply.

Body (multipart/form-data)
  • file* string (binary)
  • name string
  • folder string
  • visibility string: private, public
Responses
  • 201 The file.
    • data object
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
  • 413 storage/file-too-large, storage/quota-exceeded
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 415 storage/type-not-allowed
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/files/uploads Start a direct upload of a large file (S3 storage only)
Auth: App key and access token

PUT the bytes to upload.url with upload.headers, then call /files/{id}/complete.

Body (application/json)
  • name* string
  • mime_type* string
  • size* integer
  • folder string
  • visibility string: private, public
Responses
  • 201 The pending file and where to upload it.
    • data object
      • file object
        • id string
        • name string
        • folder string or null
        • mime_type string · Read from the content.
        • size integer
        • checksum object or null
          • sha256 string
        • visibility string: private, public
        • public_url string or null · Public files only.
        • status string: pending, ready
        • created_at string (date-time)
      • upload object
        • method "PUT"
        • url string
        • headers object
        • expires_at string (date-time)
  • 409 storage/direct-upload-unavailable
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/files/{id} One file
Auth: App key and access token
Parameters
id* path string
Responses
  • 200 The file.
    • data object
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
patch /api/v2/files/{id} Rename or change visibility
Auth: App key and access token
Parameters
id* path string
Body (application/json)
  • name string
  • visibility string: private, public
Responses
  • 200 The file.
    • data object
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/files/{id} Delete the file
Auth: App key and access token
Parameters
id* path string
Responses
  • 204 Deleted.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/files/{id}/complete Finish a direct upload
Auth: App key and access token

Checks the object's size and type; a file that breaks the limits is deleted.

Parameters
id* path string
Responses
  • 200 The file.
    • data object
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
  • 409 storage/upload-missing
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/files/{id}/url A 10-minute download link
Auth: App key and access token
Parameters
id* path string
Responses
  • 200 A link that works without credentials until it expires.
    • data object
      • url string
      • expires_at string (date-time)
  • 409 storage/upload-pending
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/files/{file}/content Download through a signed link
Auth: None

The link /files/{id}/url gives when files are stored on this server. It needs no app key or token, only its signature.

Parameters
file* path string
expires* query integer
signature* query string
Responses
  • 200 The file's bytes.
  • 403 The link expired or was changed.
get /api/v2/public-files/{file} A public file's stable URL
Auth: None

Redirects to a fresh download link. Needs no app key or token. Private files answer 404.

Parameters
file* path string
Responses
  • 302 Redirect to the file.
  • 404 An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Data

JSON documents in the app's collections.

get /api/v2/data/{collection} List documents
Auth: App key; access token optional

Newest first. Who sees what follows the collection's access mode: everything (public_read; authenticated_read when signed in), only your own (owner_only), nothing (server_only, 403).

Parameters
collection* path string
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of documents.
    • data array of object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/data/{collection} Create a document with a new id
Auth: App key and access token
Parameters
collection* path string
Body (application/json)
  • fields* object · A JSON object, at most 1 MiB and 64 levels deep.
Responses
  • 201 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • 413 data/document-too-large
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/data/{collection}/query Query documents
Auth: App key; access token optional

Over the documents you may read. Values match only fields of the same kind ("5" is not 5), strings compare case-sensitively, != skips documents without the field. With order_by, documents without a value of that type are left out; without it, newest first.

Parameters
collection* path string
Body (application/json)
  • where array of array of any · Filters that must all match: [field, operator, value], for example ["price", ">=", 10].
  • order_by object
    • field* string
    • direction string: asc, desc
    • type string: string, number
  • limit integer
  • cursor string
Responses
  • 200 A page of documents.
    • data array of object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/data/{collection}/{id} Get a document
Auth: App key; access token optional

404 when it doesn't exist or you may not read it.

Parameters
collection* path string
id* path string
Responses
  • 200 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
put /api/v2/data/{collection}/{id} Create or replace a document
Auth: App key and access token

You can only replace your own documents.

Parameters
collection* path string
id* path string
If-Match header string The ETag of the version you read, such as "3": write only over that version.
If-None-Match header "*" *: only create.
Body (application/json)
  • fields* object · A JSON object, at most 1 MiB and 64 levels deep.
Responses
  • 200 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • 201 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • 412 data/version-mismatch, data/already-exists
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
patch /api/v2/data/{collection}/{id} Merge fields into a document
Auth: App key and access token

Nested objects merge key by key; anything else replaces.

Parameters
collection* path string
id* path string
If-Match header string The ETag of the version you read, such as "3": write only over that version.
Body (application/json)
  • fields* object · A JSON object, at most 1 MiB and 64 levels deep.
Responses
  • 200 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • 412 data/version-mismatch
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/data/{collection}/{id} Delete a document
Auth: App key and access token
Parameters
collection* path string
id* path string
If-Match header string The ETag of the version you read, such as "3": write only over that version.
Responses
  • 204 Deleted.
  • 412 data/version-mismatch
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin

The server key and its app.

get /api/v2/admin/app The key's app and scopes
Auth: Server key
Responses
  • 200 The app and the key.
    • data object
      • app object
        • name string
        • key string (uuid)
      • server_key object
        • name string
        • prefix string
        • scopes array of string
  • 401 server/invalid-key
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin users

Manage the app's users from your backend.

get /api/v2/admin/users List users
Auth: Server key, scope users.read
Parameters
search query string Part of the email or name, any case.
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of users, newest first.
    • data array of object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
      • disabled boolean
      • claims object
      • providers array of string: password, google, apple
      • last_login_at string or null (date-time)
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/admin/users Create a user
Auth: Server key, scope users.write
Body (application/json)
  • email* string (email)
  • password string
  • first_name string
  • last_name string
  • email_verified boolean
  • disabled boolean
Responses
  • 201 The user, as the backend sees it.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
      • disabled boolean
      • claims object
      • providers array of string: password, google, apple
      • last_login_at string or null (date-time)
  • 403 app/user-limit-reached
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 409 auth/email-already-in-use
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • 422 auth/weak-password
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/users/{uid} Get a user
Auth: Server key, scope users.read
Parameters
uid* path string
Responses
  • 200 The user, as the backend sees it.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
      • disabled boolean
      • claims object
      • providers array of string: password, google, apple
      • last_login_at string or null (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
patch /api/v2/admin/users/{uid} Update a user
Auth: Server key, scope users.write

A new password or disabled true signs the user out everywhere.

Parameters
uid* path string
Body (application/json)
  • email string (email)
  • password string
  • first_name string or null
  • last_name string or null
  • email_verified boolean
  • disabled boolean
Responses
  • 200 The user, as the backend sees it.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
      • disabled boolean
      • claims object
      • providers array of string: password, google, apple
      • last_login_at string or null (date-time)
  • 409 auth/email-already-in-use
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/admin/users/{uid} Delete a user
Auth: Server key, scope users.write
Parameters
uid* path string
Responses
  • 204 Deleted.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/admin/users/{uid}/revoke-sessions Sign the user out everywhere
Auth: Server key, scope users.write
Parameters
uid* path string
Responses
  • 204 Every session ended.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
put /api/v2/admin/users/{uid}/claims Replace the custom claims
Auth: Server key, scope users.write

They reach the user's next access token. At most 1000 bytes; {} clears them.

Parameters
uid* path string
Body (application/json)
  • claims* object
Responses
  • 200 The user, as the backend sees it.
    • data object
      • uid string · The user's public id (a lowercase ULID).
      • email string
      • email_verified boolean
      • first_name string or null
      • last_name string or null
      • photo_url string or null
      • created_at string (date-time)
      • disabled boolean
      • claims object
      • providers array of string: password, google, apple
      • last_login_at string or null (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin tokens

Check access tokens (introspection).

post /api/v2/admin/tokens/verify Check an access token
Auth: Server key, scope tokens.verify

Always 200. Unlike offline verification, it also sees signed-out sessions and disabled users.

Body (application/json)
  • token* string
Responses
  • 200 Whether the token is active, and its claims.
    • data object
      • active boolean
      • reason string · When inactive: an auth/… code.
      • uid string
      • sid string
      • email string or null
      • email_verified boolean
      • provider string or null
      • claims object
      • auth_time integer or null
      • iat integer
      • exp integer
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin points

Loyalty points.

post /api/v2/admin/users/{uid}/points Award points
Auth: Server key, scope points.write
Parameters
uid* path string
Body (application/json)
  • points* integer · Not zero; negative takes points away.
  • description string
Responses
  • 201 The entry and the new balance.
    • data object
      • points integer
      • description string or null
      • created_at string (date-time)
      • balance integer
      • tier string: silver, gold, platinum
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin Remote Config

Publish and roll back templates.

get /api/v2/admin/remote-config The live template
Auth: Server key, scope config.read

The ETag is the version ("0" before the first publish).

Responses
  • 200 A version with its template; the ETag is the version.
    • data object
      • version integer
      • description string or null
      • rollback_of integer or null
      • published_at string or null (date-time)
      • published_by object or null
        • type string: user, server_key
        • name string
      • template object · Conditions in priority order and typed parameters. See the Remote Config guide.
        • conditions array of object
          • name* string
          • rules* array of object
        • parameters object
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/remote-config/versions List versions
Auth: Server key, scope config.read

Newest first, without templates. The last 300 are kept.

Parameters
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of versions.
    • data array of object
      • version integer
      • description string or null
      • rollback_of integer or null
      • published_at string or null (date-time)
      • published_by object or null
        • type string: user, server_key
        • name string
      • template object · Conditions in priority order and typed parameters. See the Remote Config guide.
        • conditions array of object
          • name* string
          • rules* array of object
        • parameters object
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/admin/remote-config/versions Publish a template
Auth: Server key, scope config.write

Send If-Match: "<version you edited>" to avoid overwriting someone else's publish.

Parameters
If-Match header string The ETag of the version you read, such as "3": write only over that version.
Body (application/json)
  • template* object · Conditions in priority order and typed parameters. See the Remote Config guide.
    • conditions array of object
      • name* string
      • rules* array of object
        • field* string: platform, app_version, language, tier, claim, percent
        • values array of string
        • op string: ==, !=, <, <=, >, >=
        • value string
        • name string · The claim, for claim.
        • seed string · For percent.
        • from number · For percent.
        • to number · For percent.
    • parameters object
  • description string
Responses
  • 201 A version with its template; the ETag is the version.
    • data object
      • version integer
      • description string or null
      • rollback_of integer or null
      • published_at string or null (date-time)
      • published_by object or null
        • type string: user, server_key
        • name string
      • template object · Conditions in priority order and typed parameters. See the Remote Config guide.
        • conditions array of object
          • name* string
          • rules* array of object
        • parameters object
  • 412 remote-config/version-mismatch
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/remote-config/versions/{version} One version with its template
Auth: Server key, scope config.read
Parameters
version* path integer
Responses
  • 200 A version with its template; the ETag is the version.
    • data object
      • version integer
      • description string or null
      • rollback_of integer or null
      • published_at string or null (date-time)
      • published_by object or null
        • type string: user, server_key
        • name string
      • template object · Conditions in priority order and typed parameters. See the Remote Config guide.
        • conditions array of object
          • name* string
          • rules* array of object
        • parameters object
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/admin/remote-config/versions/{version}/rollback Publish an old version again
Auth: Server key, scope config.write

Creates a new version with rollback_of.

Parameters
version* path integer
Responses
  • 201 A version with its template; the ETag is the version.
    • data object
      • version integer
      • description string or null
      • rollback_of integer or null
      • published_at string or null (date-time)
      • published_by object or null
        • type string: user, server_key
        • name string
      • template object · Conditions in priority order and typed parameters. See the Remote Config guide.
        • conditions array of object
          • name* string
          • rules* array of object
        • parameters object
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin push

Send push notifications.

post /api/v2/admin/push/send Send a push notification
Auth: Server key, scope push.send

Sent from the queue; failures are retried twice and dead tokens are disabled.

Body (application/json)
  • target* one of
    One of:
    • type* "users"
    • uids* array of string
    or:
    • type* "device"
    • device_id* string
    or:
    • type* "topic"
    • topic* string
    or:
    • type* "all"
  • title string
  • body string
  • image string (uri) · https only.
  • data object · Up to 50 string values.
  • badge integer
  • sound string
Responses
  • 202 The message and its delivery counts.
    • data object
      • id string
      • target object
      • title string or null
      • body string or null
      • image string or null
      • data object or null
      • badge integer or null
      • sound string or null
      • status string: queued, sending, done
      • counts object
        • devices integer
        • sent integer
        • failed integer
        • invalid_token integer
      • created_at string (date-time)
      • completed_at string or null (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/push/messages/{id} A message and its delivery counts
Auth: Server key, scope push.send
Parameters
id* path string
Responses
  • 200 The message and its delivery counts.
    • data object
      • id string
      • target object
      • title string or null
      • body string or null
      • image string or null
      • data object or null
      • badge integer or null
      • sound string or null
      • status string: queued, sending, done
      • counts object
        • devices integer
        • sent integer
        • failed integer
        • invalid_token integer
      • created_at string (date-time)
      • completed_at string or null (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin files

Every file of the app.

get /api/v2/admin/files List every file of the app
Auth: Server key, scope files.read
Parameters
uid query string One user's files.
owner query string: app app: only the app's own files.
folder query string
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of files, newest first.
    • data array of object
      • uid string or null · The owner; null for the app's own files.
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/admin/files Upload an app file or a file for a user
Auth: Server key, scope files.write

The app's size and type limits apply; the user quota doesn't.

Body (multipart/form-data)
  • file* string (binary)
  • name string
  • uid string · A user's file; the app's own otherwise.
  • folder string
  • visibility string: private, public
Responses
  • 201 The file, with its owner.
    • data object
      • uid string or null · The owner; null for the app's own files.
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/files/{id} One file
Auth: Server key, scope files.read
Parameters
id* path string
Responses
  • 200 The file, with its owner.
    • data object
      • uid string or null · The owner; null for the app's own files.
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
patch /api/v2/admin/files/{id} Rename or change visibility
Auth: Server key, scope files.write
Parameters
id* path string
Body (application/json)
  • name string
  • visibility string: private, public
Responses
  • 200 The file, with its owner.
    • data object
      • uid string or null · The owner; null for the app's own files.
      • id string
      • name string
      • folder string or null
      • mime_type string · Read from the content.
      • size integer
      • checksum object or null
        • sha256 string
      • visibility string: private, public
      • public_url string or null · Public files only.
      • status string: pending, ready
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/admin/files/{id} Delete a file
Auth: Server key, scope files.write
Parameters
id* path string
Responses
  • 204 Deleted.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/files/{id}/url A 10-minute download link
Auth: Server key, scope files.read
Parameters
id* path string
Responses
  • 200 A link that works without credentials until it expires.
    • data object
      • url string
      • expires_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Admin data

Every document of the app, whatever the access mode.

get /api/v2/admin/data The app's collections
Auth: Server key, scope data.read
Responses
  • 200 Every collection, by name.
    • data array of object
      • name string
      • access_mode string: owner_only, authenticated_read, public_read, server_only
      • description string or null
      • documents integer
      • created_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/data/{collection} List every document
Auth: Server key, scope data.read
Parameters
collection* path string
uid query string One user's documents.
owner query string: app app: only the app's own documents.
limit query integer Page size.
cursor query string meta.next_cursor of the previous page.
Responses
  • 200 A page of documents.
    • data array of object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/admin/data/{collection} Create a document
Auth: Server key, scope data.write

Owned by the app, or by the user named by "owner": "<uid>".

Parameters
collection* path string
Body (application/json)
  • fields* object
  • owner string or null · A user's uid; null or absent: the app's own document.
Responses
  • 201 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
post /api/v2/admin/data/{collection}/query Query every document
Auth: Server key, scope data.read
Parameters
collection* path string
Body (application/json)
  • where array of array of any · Filters that must all match: [field, operator, value], for example ["price", ">=", 10].
  • order_by object
    • field* string
    • direction string: asc, desc
    • type string: string, number
  • limit integer
  • cursor string
Responses
  • 200 A page of documents.
    • data array of object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
    • meta object
      • next_cursor string or null · Null on the last page.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
get /api/v2/admin/data/{collection}/{id} Get any document
Auth: Server key, scope data.read
Parameters
collection* path string
id* path string
Responses
  • 200 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
put /api/v2/admin/data/{collection}/{id} Create or replace any document
Auth: Server key, scope data.write

owner applies when the document is created.

Parameters
collection* path string
id* path string
If-Match header string The ETag of the version you read, such as "3": write only over that version.
If-None-Match header "*" *: only create.
Body (application/json)
  • fields* object
  • owner string or null · A user's uid; null or absent: the app's own document.
Responses
  • 200 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • 201 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • 412 data/version-mismatch, data/already-exists
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
patch /api/v2/admin/data/{collection}/{id} Merge fields into any document
Auth: Server key, scope data.write
Parameters
collection* path string
id* path string
If-Match header string The ETag of the version you read, such as "3": write only over that version.
Body (application/json)
  • fields* object · A JSON object, at most 1 MiB and 64 levels deep.
Responses
  • 200 The document; its version is also the ETag header.
    • data object
      • id string
      • fields object
      • owner string or null · The owner's uid; null for the app's own documents.
      • version integer · Increases with every write; also the ETag.
      • created_at string (date-time)
      • updated_at string (date-time)
  • 412 data/version-mismatch
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).
delete /api/v2/admin/data/{collection}/{id} Delete any document
Auth: Server key, scope data.write
Parameters
collection* path string
id* path string
If-Match header string The ETag of the version you read, such as "3": write only over that version.
Responses
  • 204 Deleted.
  • default An error.
    • error* object
      • code* string · Stable; act on this.
      • message* string · For people.
      • fields object · Per-field messages (validation errors).

Discovery

Token verification keys.

get /.well-known/jwks.json The public keys that sign access tokens (JWKS)
Auth: None

Pick the key whose kid matches the token header; refetch when a kid is unknown. Cacheable for 5 minutes.

Responses
  • 200 A JSON Web Key Set.
    • keys array of object
      • kty "RSA"
      • use "sig"
      • alg "RS256"
      • kid string
      • n string
      • e string
get /.well-known/openid-configuration Issuer and JWKS location
Auth: None
Responses
  • 200 Discovery document.
    • issuer string
    • jwks_uri string