Organizations

List your organizations, create one, manage its details, and control member roles.

Organization routes need only the Authorization header — the organization is named in the path, not by X-Workspace-Id. For what the roles mean, see Concepts.

Your organizations

curl "$API_BASE/v1/organization/mine" \
  -H "Authorization: Bearer $TOKEN"

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.organizations.get_organization_mine()

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.organizations.getOrganizationMine();

{
  "data": {
    "organizations": [
      {
        "uid": "org_5f8e2c1a-7b94-4d06-a3e8-1c62d90b47f5",
        "name": "Acme Analytics",
        "slug": "acme-analytics",
        "role": "admin",
        "plan_name": "Team",
        "plan_tier": "team",
        "is_team_plus": true,
        "can_manage": true
      }
    ],
    "can_invite_members": true
  }
}

role is your role in each organization; can_manage is true for admins. can_invite_members is true when at least one of your organizations is on an organization-tier plan — the gate for invitations and workspace member grants.

Create an organization

curl -X POST "$API_BASE/v1/organization" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Analytics",
    "plan_id": "enterprise",
    "address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "country": "USA",
      "postal_code": "94102"
    }
  }'

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.organizations.post_organization(json={
    "name": "Acme Analytics",
    "plan_id": "enterprise",
    "address": {
        "street": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "country": "USA",
        "postal_code": "94102",
    },
})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.organizations.postOrganization({
  json: {
    name: "Acme Analytics",
    plan_id: "enterprise",
    address: {
      street: "123 Main St",
      city: "San Francisco",
      state: "CA",
      country: "USA",
      postal_code: "94102",
    },
  },
});

{
  "data": {
    "organization_id": "org_5f8e2c1a-7b94-4d06-a3e8-1c62d90b47f5",
    "name": "Acme Analytics",
    "slug": "acme-analytics",
    "workspaces_transferred": 2,
    "message": "Organization created successfully"
  }
}

Request body

Field	Meaning
`name` required	The organization's name.
`plan_id` required	One of the organization plan identifiers — see Billing for what each tier includes.
`address` optional	Street address object.
`billing_address` optional	Defaults to `address`.
`country` optional	ISO alpha-2, e.g. `"US"` — sets the routing country used for region defaults.

Creating an organization has two immediate side effects: you become its owner and admin, and your individual workspaces and credit balance transfer to the organization — workspaces_transferred reports how many moved.

Errors

Status	Why	Example message
`400`	Missing name or plan	`"Organization name is required"`
`400`	Unknown plan	`"Plan must be one of: startup, growth, scale, enterprise"`

Get an organization

Any member can read the organization:

curl "$API_BASE/v1/organization/$ORG_ID" \
  -H "Authorization: Bearer $TOKEN"

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.organizations.get_organization_by_organization_id(ORG_ID)

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.organizations.getOrganizationByOrganizationId(ORG_ID);

{
  "data": {
    "uid": "org_5f8e2c1a-7b94-4d06-a3e8-1c62d90b47f5",
    "name": "Acme Analytics",
    "slug": "acme-analytics",
    "type": "organization",
    "owner": "e1c62b7a-9f04-4d3b-8a15-2c7d90e4b638",
    "address": { "street": "123 Main St", "city": "San Francisco", … },
    "billing_address": { … },
    "created_at": "2026-05-20T10:00:00+00:00",
    "plan": { "name": "Team", "type": "organization", "active": true, … },
    "settings": {
      "default_timezone": "UTC",
      "auto_delete_models_beyond_limit": true
    },
    "policies": {
      "allowed_email_domains": ["acme.dev"],
      "default_member_role": "member",
      "two_factor_required": false
    },
    "credits": 0.0
  }
}

policies are the organization's governance knobs — most visibly allowed_email_domains, which restricts who can be invited, and default_member_role, the role an invite gets when the inviter omits one. For the live credit balance and plan details, use Billing rather than this snapshot.

Errors

Status	Why	Example message
`403`	You aren't a member	`"Not a member of this organization"`
`404`	No such organization	`"Organization not found"`

Update an organization

Requires the organization.settings.manage permission — organization admins (and the owner). Send only what you're changing:

curl -X PUT "$API_BASE/v1/organization/$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "policies": { "allowed_email_domains": ["acme.dev"] } }'

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.organizations.put_organization_by_organization_id(ORG_ID, json={"policies": {"allowed_email_domains": ["acme.dev"]}})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.organizations.putOrganizationByOrganizationId(ORG_ID, {
  json: { policies: { allowed_email_domains: ["acme.dev"] } },
});

{
  "data": {
    "message": "Organization updated successfully",
    "organization": {
      "uid": "org_5f8e2c1a-7b94-4d06-a3e8-1c62d90b47f5",
      "name": "Acme Analytics",
      "slug": "acme-analytics",
      "address": { … },
      "billing_address": { … },
      "country": "US",
      "home_region": null
    }
  }
}

Field	Meaning
`name` / `slug` optional	Rename the organization or change its URL slug.
`address` / `billing_address` optional	Address objects.
`settings` optional	Organization settings, e.g. `default_timezone`.
`policies` optional	Governance knobs — validated against the known schema; unknown keys are dropped.
`country` optional	ISO alpha-2 routing country.
`home_region` optional	A region ID that becomes the default for the organization's new workspaces.

Errors

Status	Why	Example message
`400`	Empty body	`"Request body is empty"`
`403`	Not an admin	`"Insufficient permissions"`

List members

Any member can see the roster:

curl "$API_BASE/v1/organization/$ORG_ID/members" \
  -H "Authorization: Bearer $TOKEN"

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.organizations.get_organization_by_organization_id_members(ORG_ID)

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.organizations.getOrganizationByOrganizationIdMembers(ORG_ID);

{
  "data": {
    "members": [
      {
        "user_id": "e1c62b7a-9f04-4d3b-8a15-2c7d90e4b638",
        "email": "[email protected]",
        "name": "Ada Norberg",
        "role": "admin",
        "is_owner": true,
        "permissions": ["organization.settings.manage", "organization.members.invite", …],
        "added_at": "2026-05-20T10:00:00+00:00",
        "invited_by": null,
        "last_login_at": "2026-07-17T08:45:00+00:00",
        "has_logged_in": true,
        "workspaces": [ { "uid": "ws_…", "name": "Growth", "role": "owner" } ],
        "workspaces_count": 1
      },
      …
    ],
    "count": 3
  }
}

Change a member's role

Requires organization.members.manage — organization admins (and the owner):

Field	Meaning
`role` required	`admin`, `billing`, `member`, or `viewer`. The member's permissions are reset to the new role's set.

curl -X PUT "$API_BASE/v1/organization/$ORG_ID/members/$MEMBER_USER_ID/role" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.organizations.put_organization_by_organization_id_members_by_member_user_id_role(ORG_ID, MEMBER_USER_ID, json={"role": "admin"})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.organizations.putOrganizationByOrganizationIdMembersByMemberUserIdRole(ORG_ID, MEMBER_USER_ID, { json: { role: "admin" } });

{
  "data": {
    "message": "Member role updated successfully",
    "user_id": "4b8f2a90-6d17-4c3e-b5a2-9e01d7c84f53",
    "new_role": "admin"
  }
}

The member is notified of the change.

Errors

Status	Why	Example message
`400`	Unknown role	`"Role must be one of: admin, billing, member, viewer"`
`403`	Not an admin	`"Insufficient permissions"`

Remove a member

Requires organization.members.manage. The owner can't be removed:

curl -X DELETE "$API_BASE/v1/organization/$ORG_ID/members/$MEMBER_USER_ID" \
  -H "Authorization: Bearer $TOKEN"

from predictai import PredictAI

client = PredictAI(token="pa_live_…")

data = client.organizations.delete_organization_by_organization_id_members_by_member_user_id(ORG_ID, MEMBER_USER_ID)

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…" });

const data = await client.organizations.deleteOrganizationByOrganizationIdMembersByMemberUserId(ORG_ID, MEMBER_USER_ID);

{
  "data": {
    "message": "Member removed successfully",
    "user_id": "4b8f2a90-6d17-4c3e-b5a2-9e01d7c84f53"
  }
}

Errors

Status	Why	Example message
`400`	Target is the organization owner	`"Cannot remove the organization owner"`
`403`	Not an admin	`"Insufficient permissions"`

On this page