Account, usage, billing and pricing routes

Read and update your account, read usage, billing and prices, manage notifications, and sign in.

Every route is on https://sandbox.tangle.tools and takes your account API key as Authorization: Bearer <key> unless it says otherwise. Errors use the shape in Error codes. This page is generated from the OpenAPI document, which also has every response schema.

Account

Get the current account (alias of /v1/me)

GET /v1/account/me

Get the current account

GET /v1/me

Update the account profile

PATCH /v1/me

The name is the only field that can change.

Request body (application/json):

Get email preferences

GET /v1/me/email-preferences

Update email preferences

PUT /v1/me/email-preferences

Fields left out keep their value.

Request body (application/json):

Resolve a model credential for an agent profile

POST /v1/model-credentials/resolve

Selects a model-credential seat for the profile and returns how to reach it: a CLI auth reference or an API key environment variable with its base URL. The response never holds a raw key and is never cached. Only the principal enrolled for the deployment’s account-owner grant can call it; other callers, keys scoped to one sandbox and member-paid line keys get 403. A retained sandbox must be one the caller owns personally.

Request body (application/json):

Create an account without sign-in

POST /v1/signup

Needs no credential and is off in production, which answers 410 SIGNUP_DISABLED: sign in through the OAuth provider instead. Where a deployment turns it on, the account is created unverified and no API key is issued.

Authentication: none.

Request body (application/json):

Usage

Get today’s usage

GET /usage

Counts for the billing owner of the credential, not for one sandbox.

Get current usage stats

GET /v1/usage

Get sandbox egress for a calendar month

GET /v1/usage/egress

The account’s egress for one calendar month (UTC) as the meter recorded it: the account total, the plan’s allowance, the overage beyond it, each sandbox’s bytes, and what the meter has charged or reserved. Paid plans include 2 TB per account per month, shared by its sandboxes, then bill per decimal GB; Free accounts are capped at 100 GiB per month and never charged.

Export usage data as CSV

GET /v1/usage/export

Get subscription info

GET /v1/usage/subscription

Billing

Get the plan, credit and limits

GET /subscription

Reports the plan of the billing owner of the credential. Plan changes and top-ups are made at id.tangle.tools.

Get the credit balance

GET /v1/billing/balance

Read from id.tangle.tools for the billing owner of the credential; the query string is passed through.

List credit transactions

GET /v1/billing/transactions

Read from id.tangle.tools for the billing owner of the credential; the query string is passed through.

Get spend by product

GET /v1/billing/usage

Read from id.tangle.tools for the billing owner of the credential; the query string is passed through. Only debits count.

Call a retired billing path

GET /v1/billing/{path}

Any method on any other path under /v1/billing answers 410: send the same request to https://id.tangle.tools with your Platform API key.

Pricing

Get egress pricing

GET /v1/pricing/egress

Each plan’s monthly egress allowance and the price beyond it. Public: no credential is required. Outbound bytes from each sandbox are counted per UTC calendar month; inbound traffic is free. Every plan’s allowance is per account (scope: account), shared by its sandboxes: overage: billed plans pay usdPerGb per decimal GB (10^9 bytes) beyond includedBytes; overage: refused plans are refused new sandboxes and prompts at it and never charged. Computed from the allowances quota admission enforces and the rates this deployment bills.

Get the sandbox rate card

GET /v1/pricing/sandboxes

USD per vCPU-hour, per GB-hour of memory, per GB-hour of disk, and the hourly minimum, for the pool this deployment bills sandboxes in. A sandbox is billed vcpucpuCoreHourUsd + memoryGBmemoryGBHourUsd + diskGB*diskGBHourUsd per hour, floored at minChargeHourUsd. source is pool-derived when the numbers come from the configured pool’s own host cost and sellable capacity, and reference-constants when no pool cost is configured and the deployment prices on the pricing engine’s reference server instead. Public: no credential is required.

Notifications

List notifications

GET /v1/notifications

Mark all notifications as read

POST /v1/notifications/read-all

Mark a notification as read

POST /v1/notifications/{id}/read

Sign-in

Delete the account

DELETE /auth/account

Takes the session cookie, or its token as a Bearer token, from a browser sign-in; an API key, CLI token or runtime token gets 403 SESSION_AUTH_REQUIRED. It also needs the recent_auth cookie that sign-in sets, which expires soon after. Marks the account deleted, revokes the API keys Sandbox created for it, except a team’s keys, and clears the session cookie.

Authentication: a browser session cookie.

Finish browser sign-in

GET /auth/callback

Takes the one-time code from Tangle sign-in and the oauth_state cookie set when sign-in started. Always answers with a redirect. On success it sets the session and recent_auth cookies and redirects to the redirect_to target from sign-in, by default /dashboard. When the account has two-factor sign-in on, it sets the mfa_challenge cookie and redirects to the dashboard /mfa page instead. A CLI sign-in redirects to its loopback callback_url with grant_token, expires_at and session_expires_at; exchange the grant_token at POST /auth/cli/exchange. On failure it redirects to /login?error=<reason> on the dashboard, or to the loopback callback_url with error=<reason>. Reasons include missing_code, csrf_mismatch, auth_failed, email_verification_required and paid_access_required.

Authentication: none.

Forward a CLI sign-in return

GET /auth/cli/callback

Takes no credential. Redirects to GET /auth/callback on the API origin with the same code, state, error and error_description.

Authentication: none.

Show the device approval page

GET /auth/cli/device

Takes no credential; it reads the session cookie to see who is signed in. With a user_code and no session it redirects to GET /auth/login. When the dashboard runs on another origin it redirects to the dashboard’s device page. Otherwise it answers an HTML page where the person approves the code.

Authentication: none.

Approve a device sign-in

POST /auth/cli/device/authorize

Takes the session cookie of the person approving the code. Without a session it redirects to GET /auth/login. Approving lets the CLI’s next poll succeed. Answers an HTML page, or a 303 redirect to the dashboard’s device page when result_redirect is frontend and the dashboard runs on another origin.

Authentication: none.

Request body (application/x-www-form-urlencoded):

Poll a device sign-in

POST /auth/cli/device/poll

Takes the device_code from POST /auth/cli/device/start. Answers 428 AUTHORIZATION_PENDING until the person approves the code. The approved answer is returned once; the device code is spent after it.

Authentication: none.

Request body (application/json):

Start device sign-in

POST /auth/cli/device/start

Takes no credential. Show user_code to the person, open verification_uri_complete in a browser, and poll POST /auth/cli/device/poll with device_code every interval seconds until expires_in seconds have passed.

Authentication: none.

Request body (application/json):

Exchange a CLI grant for credentials

POST /auth/cli/exchange

Takes the grant_token that GET /auth/callback appended to the CLI’s loopback callback_url. A grant token is short-lived.

Authentication: none.

Request body (application/json):

Mint a Hub key for the CLI

POST /auth/cli/hub-key

Takes the session cookie, a session token as a Bearer token, or an account API key as a Bearer token. Returns an API key for Hub; expires_at says when it stops working. Minting again for the same device_id revokes that device’s previous key.

Authentication: an API key as a bearer token or a browser session cookie.

Request body (application/json):

Start CLI browser sign-in

GET /auth/cli/login

Takes no credential. Sets the oauth_state cookie and redirects the browser to Tangle sign-in. After sign-in the browser returns to callback_url with a grant_token for POST /auth/cli/exchange.

Authentication: none.

Start browser sign-in

GET /auth/login

Takes no credential. Sets the oauth_state cookie and redirects the browser to Tangle sign-in, which returns it to GET /auth/callback.

Authentication: none.

Start browser sign-in from a form

POST /auth/login

Takes no credential. Accepts a JSON body or a form body. Sets the oauth_state cookie and redirects the browser to Tangle sign-in.

Authentication: none.

Request body (application/json):

Sign out

POST /auth/logout

Takes no credential. Clears the session and mfa_challenge cookies. To also end the shared Tangle sign-in, send the browser to signoutUrl.

Authentication: none.

Sign out and redirect

GET /auth/logout

Takes no credential. Clears the session and mfa_challenge cookies, then redirects to the Tangle sign-out URL, or to the dashboard when no Tangle sign-in is configured.

Authentication: none.

Replace backup codes

POST /auth/mfa/backup-codes

Takes the session cookie, or its token as a Bearer token, from a browser sign-in; an API key, CLI token or runtime token gets 403 SESSION_AUTH_REQUIRED. It also needs the recent_auth cookie that sign-in sets, which expires soon after. Needs a current code. The old backup codes stop working.

Authentication: a browser session cookie.

Request body (application/json):

Complete a two-factor sign-in

POST /auth/mfa/challenge

Takes the mfa_challenge cookie that sign-in sets when the account has two-factor sign-in on, and a current code or an unused backup code. On success it sets the session and recent_auth cookies and clears mfa_challenge. Each correct submission uses up the cookie. A wrong code sets a fresh mfa_challenge cookie with the same expiry; use it for the retry. For a CLI sign-in, redirect_to is the loopback callback_url carrying the grant_token for POST /auth/cli/exchange.

Authentication: the two-factor challenge cookie from sign-in.

Request body (application/json):

Turn off two-factor sign-in

POST /auth/mfa/disable

Takes the session cookie, or its token as a Bearer token, from a browser sign-in; an API key, CLI token or runtime token gets 403 SESSION_AUTH_REQUIRED. It also needs the recent_auth cookie that sign-in sets, which expires soon after. Needs a current code, so a stolen session cannot remove the second factor.

Authentication: a browser session cookie.

Request body (application/json):

Start two-factor enrollment

POST /auth/mfa/enroll

Takes the session cookie, or its token as a Bearer token, from a browser sign-in; an API key, CLI token or runtime token gets 403 SESSION_AUTH_REQUIRED. It also needs the recent_auth cookie that sign-in sets, which expires soon after. Returns a new secret and backup codes. Two-factor sign-in stays off until POST /auth/mfa/verify accepts a code from the secret.

Authentication: a browser session cookie.

Get two-factor status

GET /auth/mfa/status

Takes the session cookie, or its token as a Bearer token, from a browser sign-in; an API key, CLI token or runtime token gets 403 SESSION_AUTH_REQUIRED.

Authentication: a browser session cookie.

Finish two-factor enrollment

POST /auth/mfa/verify

Takes the session cookie, or its token as a Bearer token, from a browser sign-in; an API key, CLI token or runtime token gets 403 SESSION_AUTH_REQUIRED. It also needs the recent_auth cookie that sign-in sets, which expires soon after. Turns on two-factor sign-in when code matches the secret from POST /auth/mfa/enroll.

Authentication: a browser session cookie.

Request body (application/json):

List sign-in methods

GET /auth/providers

Takes no credential. Each flag says whether this deployment offers the method.

Authentication: none.

Get the current session

GET /auth/session

Takes the session cookie, a session token as a Bearer token, or an account API key as a Bearer token. Answers 200 with authenticated: false when no valid credential is sent.

Authentication: an API key as a bearer token or a browser session cookie.

Exchange an API key for a browser session

POST /auth/session

Takes an account API key as a Bearer token; a session token or the session cookie gets 401. Sets the session and recent_auth cookies. When the account has two-factor sign-in on, sets the mfa_challenge cookie instead and answers 403 MFA_REQUIRED; finish with POST /auth/mfa/challenge.

Authentication: an API key as a bearer token or a browser session cookie.

Service

Check service health

GET /health

Needs no credential. status is ok while the service answers requests; a billing backlog never changes it and is reported under checks.

Authentication: none.

Get the deployed revision

GET /version

Needs no credential. The response is never cached. A 503 means the deploy stamp names a different revision than the running bundle.

Authentication: none.

Get the deployed revision (trailing slash)

GET /version/

Needs no credential. The response is never cached. A 503 means the deploy stamp names a different revision than the running bundle.

Authentication: none.

Next steps

• E2B-compatible routes: E2B’s REST shape on Tangle.
• Pricing and spend: what you pay for and how to cap it.
• Limits and timeouts: plan limits and the API rate limit.