Accounts

List the accounts you belong to, rename one, and manage its members and workspaces. Roles are owner, admin, and billing. See the accounts guide.

An account id is the id of that account's primary workspace. Publishable keys cannot call these routes.

List accounts

GET/v1/accounts

A signed-in person receives every account they belong to, including an account they reach only through a workspace role (role is null). An account key receives only its own account, with role null. A workspace key is refused.

Response 200

json

{
  "accounts": [
    {
      "id": "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
      "name": "Rymi",
      "role": "owner"
    }
  ]
}

Field	Type	Description
`id`	string	Account id. Same value as the primary workspace id.
`name`	string	Account name.
`role`	string or null	Your account role: `owner`, `admin`, `billing`, or `null` when you only have a workspace role.

Example

cURLNode.jsPython

bash

curl https://api.rymi.live/v1/accounts \
  -H "Authorization: Bearer $RYMI_API_KEY"

const { accounts } = await rymi.accounts.list();

python

accounts = rymi.accounts.list()["accounts"]

Errors

Status	Code	When
401		Missing or invalid authentication.
403		A publishable key. The error is `Publishable keys cannot list accounts`.
403	`role_forbidden`	A workspace key.

Get an account

GET/v1/accounts/:id

Path parameters

Field	Type	Required	Description
`id`	string	Yes	Account id.

Response 200

json

{
  "account": {
    "id": "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
    "name": "Rymi",
    "role": "owner"
  }
}

A secret key can read its own account. role is your account role, or null for a key.

Example

cURLNode.jsPython

bash

curl https://api.rymi.live/v1/accounts/3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11 \
  -H "Authorization: Bearer $RYMI_API_KEY"

const { account } = await rymi.accounts.get("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11");

python

account = rymi.accounts.get("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11")["account"]

Errors

Status	Code	When
403		A publishable key.
403	`workspace_forbidden`	You do not belong to that account, or a secret key names a different account.
404	`not_found`	The id is not an account.

Rename an account

PATCH/v1/accounts/:id

Owner or Admin. A secret key for this account is treated as Admin.

Body

Field	Type	Required	Description
`name`	string	Yes	1 to 80 characters after trimming spaces.

Example

cURLNode.jsPython

bash

curl -X PATCH https://api.rymi.live/v1/accounts/3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11 \
  -H "Authorization: Bearer $RYMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Rymi" }'

await rymi.accounts.update("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11", { name: "Rymi" });

python

rymi.accounts.update("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11", "Rymi")

Response 200

json

{ "ok": true }

Errors

Status	Code	When
400		`name` is empty or longer than 80 characters.
403		A publishable key.
403	`role_forbidden`	You are not Owner or Admin of this account. Billing is refused.
403	`scope_missing`	The key lacks `workspaces:write`. `required_scope` is `workspaces:write`.

List members

GET/v1/accounts/:id/members

Owner or Admin. A secret key for this account is treated as Admin. Adding an Owner still requires a signed-in Owner.

Response 200

json

{
  "members": [
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "ada@example.com",
      "role": "owner"
    }
  ]
}

Field	Type	Description
`user_id`	string	User id. Send this to change or remove the member.
`email`	string or null	Their sign-in email, when Rymi can read it.
`role`	string	`owner`, `admin`, or `billing`.

Example

cURLNode.jsPython

bash

curl https://api.rymi.live/v1/accounts/3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11/members \
  -H "Authorization: Bearer $RYMI_API_KEY"

const { members } = await rymi.accounts.members.list("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11");

python

members = rymi.accounts.list_members("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11")["members"]

Errors

Status	Code	When
403		A publishable key.
403	`role_forbidden`	You are not Owner or Admin. Billing receives this.
403	`scope_missing`	The key lacks `account_members:read`.

Add a member

POST/v1/accounts/:id/members

Owner or Admin. Only an Owner can grant owner or billing, because both can spend the account's money. A key acts as an Admin, so it can't grant either. Someone without a Rymi account gets an invite email.

Body

Field	Type	Required	Description
`email`	string	Yes	Their email address.
`role`	string	Yes	`owner`, `admin`, or `billing`.

Example

cURLNode.jsPython

bash

curl -X POST https://api.rymi.live/v1/accounts/3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11/members \
  -H "Authorization: Bearer $RYMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "arvind@example.com", "role": "billing" }'

const { member } = await rymi.accounts.members.add(
  "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
  { email: "arvind@example.com", role: "billing" },
);

python

member = rymi.accounts.add_member(
    "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
    "arvind@example.com",
    "billing",
)["member"]

Response 201

json

{
  "member": {
    "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "email": "arvind@example.com",
    "role": "billing"
  }
}

Errors

Status	Code	When
400	`invalid_email`	The email address is not valid.
400	`role_not_allowed`	`role` is not `owner`, `admin`, or `billing`.
403		A publishable key.
403	`role_forbidden`	You are not Owner or Admin, or an Admin tried to add an Owner. A secret key cannot add an Owner.
403	`scope_missing`	The key lacks `account_members:write`.
409	`already_member`	That person is already a member.

Change a member's role

PATCH/v1/accounts/:id/members/:userId

Owner or Admin. Only an Owner can change an Owner, or grant owner or billing. Demoting the last Owner returns 400 last_owner.

Body

Field	Type	Required	Description
`role`	string	Yes	`owner`, `admin`, or `billing`.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	Account id.
`userId`	string	Yes	`user_id` from the members list.

Example

cURLNode.jsPython

bash

curl -X PATCH https://api.rymi.live/v1/accounts/3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11/members/6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  -H "Authorization: Bearer $RYMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

await rymi.accounts.members.update(
  "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  { role: "admin" },
);

python

rymi.accounts.update_member(
    "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "admin",
)

Response 200

json

{
  "member": {
    "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "role": "admin"
  }
}

Errors

Status	Code	When
400	`role_not_allowed`	`role` is not `owner`, `admin`, or `billing`.
400	`last_owner`	This change would leave the account with no Owner.
403		A publishable key.
403	`role_forbidden`	You are not Owner or Admin, or an Admin tried to change an Owner or grant `owner`.
403	`scope_missing`	The key lacks `account_members:write`.
404	`not_a_member`	That person is not a member.

Remove a member

DELETE/v1/accounts/:id/members/:userId

Owner or Admin. Only an Owner can remove an Owner. Removing the last Owner returns 400 last_owner.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	Account id.
`userId`	string	Yes	`user_id` from the members list.

Example

cURLNode.jsPython

bash

curl -X DELETE https://api.rymi.live/v1/accounts/3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11/members/6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  -H "Authorization: Bearer $RYMI_API_KEY"

await rymi.accounts.members.remove(
  "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
);

python

rymi.accounts.remove_member(
    "3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
)

Response 200

json

{ "ok": true }

Errors

Status	Code	When
400	`last_owner`	The account would have no Owner.
403		A publishable key.
403	`role_forbidden`	You are not Owner or Admin, or an Admin tried to remove an Owner.
403	`scope_missing`	The key lacks `account_members:write`.
404	`not_a_member`	That person is not a member.

List workspaces

GET/v1/accounts/:id/workspaces

Owner or Admin. Each workspace includes this calendar month's calls, minutes, and credits (UTC), from workspace_month_usage. Billing receives 403 role_forbidden.

Response 200

json

{
  "workspaces": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Sarang Stay Homes",
      "calls": 41,
      "minutes": 96.5,
      "credits": 579,
      "spend_cap_cents_monthly": 5000
    }
  ]
}

Field	Type	Description
`id`	string	Workspace id.
`name`	string	Display name.
`calls`	number	Calls in the current month (UTC).
`minutes`	number	Billed minutes that month, to one decimal.
`credits`	number	Credits used that month. 1 credit = $0.01.
`spend_cap_cents_monthly`	number or null	Monthly spend cap in credits, or `null`.

Example

cURLNode.jsPython

bash

curl https://api.rymi.live/v1/accounts/3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11/workspaces \
  -H "Authorization: Bearer $RYMI_API_KEY"

const { workspaces } = await rymi.accounts.workspaces("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11");

python

workspaces = rymi.accounts.workspaces("3f1c0a2e-6b4d-4e1a-9c77-2a6e0b9d4f11")["workspaces"]

Errors

Status	Code	When
403		A publishable key.
403	`role_forbidden`	You are not Owner or Admin. Billing receives this on the workspaces list.
403	`scope_missing`	The key lacks `workspaces:read`.

Accounts ​

List accounts ​

Response 200 ​

Example ​

Errors ​

Get an account ​

Path parameters ​

Response 200 ​

Example ​

Errors ​

Rename an account ​

Body ​

Example ​

Response 200 ​

Errors ​

List members ​

Response 200 ​

Example ​

Errors ​

Add a member ​

Body ​

Example ​

Response 201 ​

Errors ​

Change a member's role ​

Body ​

Path parameters ​

Example ​

Response 200 ​

Errors ​

Remove a member ​

Path parameters ​

Example ​

Response 200 ​

Errors ​

List workspaces ​

Response 200 ​

Example ​

Errors ​

Accounts

List accounts

Response 200

Example

Errors

Get an account

Path parameters

Response 200

Example

Errors

Rename an account

Body

Example

Response 200

Errors

List members

Response 200

Example

Errors

Add a member

Body

Example

Response 201

Errors

Change a member's role

Body

Path parameters

Example

Response 200

Errors

Remove a member

Path parameters

Example

Response 200

Errors

List workspaces

Response 200

Example

Errors