Docs/Organisations
Organisations

Organisations

Create, list, rename and delete Organisations under /v1/orgs.

These are the endpoints the portal calls to manage Organisations. They accept a signed-in person's session only. Any other credential gets 403:

Credentialerror
Personal API keysession_required
Organisation Keynot_available_for_organisation_key
Tenant tokennot_available_for_tenant

The exceptions are Organisation usage and Session spend, which also take an Organisation Key of that Organisation.

A person who is not a member of the Organisation gets 404 not_found, so the routes never confirm that an Organisation exists. A member without the role a route needs gets 403 forbidden.

The Organisation object

An OrganisationJSON
{
  "orgId": "org_3f9a1c0b7e2d4a6f8c10",
  "name": "Acme Health",
  "status": "active",
  "role": "owner",
  "createdAt": 1790000000000
}
FieldNotes
orgIdSai's id for the Organisation.
name1 to 100 characters. Names are not unique.
statusactive or disabled. A disabled Organisation can still be read, but every change, every Tenant token and every Organisation Key is refused with 403 organisation_disabled. Contact support@simular.ai.
roleYour role in it: owner or admin. See Members.
createdAtUnix time in milliseconds.

Create an Organisation

Anyone signed in. You become its owner.

Create an OrganisationcURL
curl -s "$SAI_API_URL/v1/orgs" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Health" }'
FieldTypeRequiredNotes
namestringyes1 to 100 characters.
201 Created · OrganisationJSON
{
  "orgId": "org_3f9a1c0b7e2d4a6f8c10",
  "name": "Acme Health",
  "status": "active",
  "role": "owner",
  "createdAt": 1790000000000
}
StatuserrorWhen
400invalid_bodyname is missing or out of range.
403phone_verification_requiredA free account has not verified a phone number, as for an API key.
422organisation_limit_reachedYou already created 5 Organisations.
429rate_limitedToo many Organisations created recently. Try again later.

List your Organisations

Anyone signed in. Lists every Organisation you are a member of, with your role in each.

List your OrganisationscURL
curl -s "$SAI_API_URL/v1/orgs" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"
200 OK · OrganisationsJSON
{
  "organisations": [
    {
      "orgId": "org_3f9a1c0b7e2d4a6f8c10",
      "name": "Acme Health",
      "status": "active",
      "role": "owner",
      "createdAt": 1790000000000
    }
  ]
}

Get an Organisation

Owner or admin.

Get an OrganisationcURL
curl -s "$SAI_API_URL/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

200 with the Organisation, or 404 not_found.

Rename an Organisation

Owner only.

Rename an OrganisationcURL
curl -s -X PATCH "$SAI_API_URL/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Health Group" }'
FieldTypeRequiredNotes
namestringyes1 to 100 characters.

200 with the renamed Organisation.

StatuserrorWhen
403forbiddenYou are an admin, not an owner.
403organisation_disabledThe Organisation is disabled.
404not_foundNo such Organisation, or not yours.

Organisation usage

Owner or admin, or an Organisation Key of this Organisation. Another Organisation's key gets 404 not_found. This is what the console's Billing page shows.

This month's usage, by Tenant
curl -s "$SAI_API_URL/v1/orgs/$ORG_ID/usage?granularity=month&from=2026-10&to=2026-10" \
  -H "Authorization: Bearer $SAI_ORG_KEY"
QueryNotes
granularityhour, day or month. Default day.
from, toThe first and last period, in UTC: 2026-10 for a month, 2026-10-15 for a day, 2026-10-15T09 for an hour. Each defaults on its own, to a range ending with the current period: the last 24 hours, 30 days or 12 months. Send both, or sending only to can put the default from after it. At most 168 hours, 400 days or 60 months.
200 OK · Organisation usage (abridged)JSON
{
  "granularity": "month",
  "from": "2026-10",
  "to": "2026-10",
  "totals": {
    "costCents": 1840,
    "byTenant": {
      "Xk2p9QzR4tLm8vNa3bCd": {
        "tenantId": "Xk2p9QzR4tLm8vNa3bCd",
        "name": "Riverside Clinic",
        "externalId": "clinic-4821",
        "costCents": 1215,
        "byCategory": { "token": { "costCents": 905 }, "compute": { "costCents": 310 } }
      }
    }
  },
  "buckets": [{ "bucket": "2026-10", "costCents": 1840, "byTenant": { "...": "..." } }]
}

totals covers the whole range and buckets has the same numbers per period. byTenant holds the spend that is tied to a Tenant, with byCategory splitting it by kind, such as token for AI calls and compute for computer time. costCents can be more than the sum of byTenant: spend not tied to any Tenant is in no entry, and each period holds at most 500 Tenants. At most 500 Tenants get a name in one answer. Read the Tenant's id from tenantId, not from the map key. For what each of a Tenant's sessions spent on AI calls, see Session spend.

StatuserrorWhen
400invalid_querygranularity is not hour, day or month, or from or to is not shaped like one of the keys above.
400billing_rejectedfrom or to doesn't match granularity (a day with granularity=month) or is not a real date (2026-13), from is after to, or the range has too many periods.
403session_requiredA personal API key, or any credential other than a member's session or an Organisation Key.
403not_available_for_tenantA Tenant token.
403organisation_disabledAn Organisation Key of a disabled Organisation.
404not_foundNo such Organisation, not yours, or an Organisation Key of another Organisation.
503billing_unavailableUsage could not be read right now. Try again shortly.

Delete an Organisation

Owner only. Every Tenant must be deleted first.

Delete an OrganisationcURL
curl -s -X DELETE "$SAI_API_URL/v1/orgs/$ORG_ID" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

204 No Content. Deleting an Organisation removes its keys, members and pending invitations. Unspent credit is lost.

While any Tenant exists, active or disabled, the delete returns 409 and lists them, at most 100, with more set when there are others:

409 Conflict · organisation_has_tenantsJSON
{
  "error": "organisation_has_tenants",
  "message": "Delete every Tenant before deleting the Organisation.",
  "tenants": [{ "tenantId": "Xk2p9QzR4tLm8vNa3bCd", "name": "Riverside Clinic" }],
  "more": false
}
StatuserrorWhen
403forbiddenYou are an admin, not an owner.
403organisation_disabledThe Organisation is disabled.
404not_foundNo such Organisation, or not yours.
409organisation_has_tenantsThe Organisation still has Tenants.
© 2026 Simular Inc. All rights reserved.