Organizations Guide

Set up and manage organizations for team collaboration. Manage organizations programmatically via the Organizations API; see Authentication or API Keys for access.

Overview

Organizations let you:

• Share resources with team members
• Centralize billing
• Control access with roles
• Manage settings across the team

Organization switcher and scope

In the dashboard sidebar you can switch between Personal and any organization you belong to. The active context is stored so that:

• Personal — You see only your personal knowledge bases, documents, and chat sessions (no organization).
• Organization — You see that organization’s knowledge bases, documents, and chat; new resources you create are created in that organization.

Switching refreshes the current page so list views and create flows use the selected scope. To create or manage organizations, go to Settings → Organizations (or open the user menu and choose Organizations).

Creating an Organization

From the Dashboard

1. Go to Settings → Organizations (or user menu → Organizations).
2. Click Create organization.
3. Enter name and slug.
4. Create. You can then open the new org to add members and change settings.

Via API

curl -X POST "/api/organizations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "settings": {
      "billing_email": "billing@acme.com"
    }
  }'

Member Management

Adding Members

Dashboard:

1. Go to Settings → Organizations → open an organization.
2. Open the Members tab.
3. Use Add by email (invites existing users by email) or use the API with user_id to add by ID.
4. Select role and add.

API (add by user ID):

curl -X POST "/api/organizations/{org_id}/members" \
  -d '{"user_id": "user-uuid", "role": "member"}'

API (invite by email — existing users only):

curl -X POST "/api/organizations/{org_id}/members/invite" \
  -d '{"email": "colleague@example.com", "role": "member"}'

Roles and Permissions

Role Capabilities

Changing Roles

curl -X PATCH "/api/organizations/{org_id}/members/{user_id}" \
  -d '{"role": "admin"}'

Removing Members

curl -X DELETE "/api/organizations/{org_id}/members/{user_id}"

Organization Resources

Creating Organization Resources

Add organization_id when creating resources:

# Create knowledge base for organization
curl -X POST "/api/knowledge-bases" \
  -d '{
    "name": "Team Knowledge Base",
    "organization_id": "org-uuid"
  }'
 
# Upload document to organization
curl -X POST "/api/upload" \
  -F "file=@document.pdf" \
  -F "organization_id=org-uuid"

Resource Visibility

Organization resources are visible to all members based on their role.

Organization Settings

Available Settings

{
  "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
  }
}

Updating Settings

curl -X PATCH "/api/organizations/{org_id}/settings" \
  -d '{
    "billing_email": "finance@acme.com",
    "require_2fa": true
  }'

API Keys

Organization-Scoped Keys

Create API keys for the organization in the dashboard: go to Settings → API Keys, click Create API Key, and set Organization to the desired team. Key management (create, list, rotate, revoke) is dashboard-only.

Organization keys:

• Access organization resources
• Automatically use org context
• Billed to organization

Billing

Organization Billing

When organization_id is set:

• Usage is tracked at org level
• Credits are shared across members
• Invoices go to billing email

Viewing Usage

curl -X GET "/api/analytics?organization_id=org-uuid"

Best Practices

Team Setup

1. Create organization - Set up org before inviting
2. Configure settings - Set billing, domains
3. Define roles - Plan who needs what access
4. Add members - Invite with appropriate roles
5. Create shared resources - Knowledge bases, schemas

Access Control

1. Least privilege - Start with minimal roles
2. Use viewer role - For read-only access
3. Admin sparingly - Only for trusted members
4. Single owner - One person owns billing

Resource Organization

1. Name clearly - Use descriptive names
2. Organize by project - Group related resources
3. Document usage - Note what each resource is for
4. Clean up unused - Remove old resources

Migrating to Organizations

Moving Personal Resources

To move existing resources to an organization:

1. Documents - Re-upload with organization_id
2. Knowledge Bases - Create new org-scoped KB
3. Schemas - Recreate in organization context
4. Workflows - Create new org workflows

Bulk Migration

Contact support for bulk migration assistance.

Leaving an Organization

As a Member

curl -X POST "/api/organizations/{org_id}/leave"

As an Owner

Owners must transfer ownership before leaving:

1. Promote another member to owner
2. Then leave the organization

Deleting an Organization

Only owners can delete:

curl -X DELETE "/api/organizations/{org_id}"

This deletes:

• All organization resources
• Member associations
• API keys
• Usage data

This cannot be undone.