Organizations API

Manage organizations for team collaboration and resource sharing. See the Organizations guide for setup and concepts.

List Organizations


GET /api/organizations

Get all organizations you belong to.

Response


{
  "organizations": [
    {
      "id": "org-uuid",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "settings": {},
      "role": "owner",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Organization


POST /api/organizations

Create a new organization.

Request


{
  "name": "Acme Corp",
  "slug": "acme-corp",
  "settings": {
    "default_knowledge_base_id": null,
    "billing_email": "billing@acme.com"
  }
}

Field	Type	Required	Description
`name`	string	Yes	Organization name
`slug`	string	Yes	URL-friendly identifier (unique)
`settings`	object	No	Organization settings

Response


{
  "organization": {
    "id": "org-uuid",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "settings": {},
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Get Organization


GET /api/organizations/{id}

Update Organization


PATCH /api/organizations/{id}

Update organization details.


{
  "name": "Acme Corporation",
  "settings": {
    "billing_email": "billing@acme-corp.com"
  }
}

Delete Organization


DELETE /api/organizations/{id}

Delete an organization. Requires owner role. All organization resources are deleted.

Leave Organization


POST /api/organizations/{id}/leave

Leave an organization. Owners cannot leave without transferring ownership.

Members

List Members


GET /api/organizations/{id}/members

Get all organization members.

Response


{
  "members": [
    {
      "id": "member-uuid",
      "user_id": "user-uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "owner",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "member-uuid",
      "user_id": "user-uuid",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "admin",
      "created_at": "2024-01-05T00:00:00Z"
    }
  ]
}

Add Member


POST /api/organizations/{id}/members

Add a user to the organization.


{
  "user_id": "user-uuid",
  "role": "member"
}

Roles

Role	Permissions
`owner`	Full access, can delete org, manage billing
`admin`	Manage members, all resources
`member`	Create and manage own resources
`viewer`	Read-only access

Update Member Role


PATCH /api/organizations/{id}/members/{userId}

Change a member’s role.


{
  "role": "admin"
}

Remove Member


DELETE /api/organizations/{id}/members/{userId}

Remove a member from the organization.

Organization Settings

Get Settings


GET /api/organizations/{id}/settings

Response


{
  "settings": {
    "default_knowledge_base_id": "kb-uuid",
    "billing_email": "billing@acme.com",
    "allowed_domains": ["acme.com"],
    "require_2fa": false,
    "data_retention_days": 365,
    "hipaa_enabled": false
  }
}

Update Settings


PATCH /api/organizations/{id}/settings

Requires owner or admin role.


{
  "billing_email": "finance@acme.com",
  "require_2fa": true,
  "allowed_domains": ["acme.com", "acme-corp.com"]
}

Available Settings

Setting	Type	Description
`default_knowledge_base_id`	string	Default KB for new documents
`billing_email`	string	Billing notifications email
`allowed_domains`	array	Allowed email domains for members
`require_2fa`	boolean	Require two-factor authentication
`data_retention_days`	number	Data retention period
`hipaa_enabled`	boolean	Enable HIPAA compliance features

Organization Scoped Resources

When creating resources with an organization, use the organization_id parameter:


{
  "name": "Team Knowledge Base",
  "organization_id": "org-uuid"
}

Resources created with an organization_id:

Are accessible to all organization members
Follow organization settings
Are billed to the organization

Organizations API

Manage organizations for team collaboration and resource sharing. See the Organizations guide for setup and concepts.

List Organizations


GET /api/organizations

Get all organizations you belong to.

Response


{
  "organizations": [
    {
      "id": "org-uuid",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "settings": {},
      "role": "owner",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Organization


POST /api/organizations

Create a new organization.

Request


{
  "name": "Acme Corp",
  "slug": "acme-corp",
  "settings": {
    "default_knowledge_base_id": null,
    "billing_email": "billing@acme.com"
  }
}

Field	Type	Required	Description
`name`	string	Yes	Organization name
`slug`	string	Yes	URL-friendly identifier (unique)
`settings`	object	No	Organization settings

Response


{
  "organization": {
    "id": "org-uuid",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "settings": {},
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Get Organization


GET /api/organizations/{id}

Update Organization


PATCH /api/organizations/{id}

Update organization details.


{
  "name": "Acme Corporation",
  "settings": {
    "billing_email": "billing@acme-corp.com"
  }
}

Delete Organization


DELETE /api/organizations/{id}

Delete an organization. Requires owner role. All organization resources are deleted.

Leave Organization


POST /api/organizations/{id}/leave

Leave an organization. Owners cannot leave without transferring ownership.

Members

List Members


GET /api/organizations/{id}/members

Get all organization members.

Response


{
  "members": [
    {
      "id": "member-uuid",
      "user_id": "user-uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "owner",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "member-uuid",
      "user_id": "user-uuid",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "admin",
      "created_at": "2024-01-05T00:00:00Z"
    }
  ]
}

Add Member


POST /api/organizations/{id}/members

Add a user to the organization.


{
  "user_id": "user-uuid",
  "role": "member"
}

Roles

Role	Permissions
`owner`	Full access, can delete org, manage billing
`admin`	Manage members, all resources
`member`	Create and manage own resources
`viewer`	Read-only access

Update Member Role


PATCH /api/organizations/{id}/members/{userId}

Change a member’s role.


{
  "role": "admin"
}

Remove Member


DELETE /api/organizations/{id}/members/{userId}

Remove a member from the organization.

Organization Settings

Get Settings


GET /api/organizations/{id}/settings

Response


{
  "settings": {
    "default_knowledge_base_id": "kb-uuid",
    "billing_email": "billing@acme.com",
    "allowed_domains": ["acme.com"],
    "require_2fa": false,
    "data_retention_days": 365,
    "hipaa_enabled": false
  }
}

Update Settings


PATCH /api/organizations/{id}/settings

Requires owner or admin role.


{
  "billing_email": "finance@acme.com",
  "require_2fa": true,
  "allowed_domains": ["acme.com", "acme-corp.com"]
}

Available Settings

Setting	Type	Description
`default_knowledge_base_id`	string	Default KB for new documents
`billing_email`	string	Billing notifications email
`allowed_domains`	array	Allowed email domains for members
`require_2fa`	boolean	Require two-factor authentication
`data_retention_days`	number	Data retention period
`hipaa_enabled`	boolean	Enable HIPAA compliance features

Organization Scoped Resources

When creating resources with an organization, use the organization_id parameter:


{
  "name": "Team Knowledge Base",
  "organization_id": "org-uuid"
}

Resources created with an organization_id:

Are accessible to all organization members
Follow organization settings
Are billed to the organization