T
testing
API Reference: Users & Organizations Managing Organizations via API

Welcome to the Organizations API. Whether you are building a custom dashboard or automating your workspace provisioning, these endpoints allow you to programmatically create organizations, manage settings, and invite team members.

This guide covers the core endpoints for organization management, user invitations, and administrative tasks.

Authentication Required

All endpoints described on this page require a valid API token passed in the Authorization header as a Bearer token.

Organization Lifecycle Flow

Setting up a new organization typically follows a standard sequence of API calls. Here is the recommended flow for provisioning a new workspace:

flowchart TD
    A["POST /v1/organization"] --> B["POST /.../complete-onboarding"]
    B --> C["POST /.../upload-logo"]
    C --> D["POST /.../user/invite"]
    D --> E["User Accepts Invitation"]

Core Organization Management

Use these endpoints to perform standard Create, Read, Update, and Delete (CRUD) operations on your organizations.

ActionMethodEndpoint
List my organizationsGET/v1/organization
Create organizationPOST/v1/organization
Get organization detailsGET/v1/organization/{organization_id}
Update organizationPUT/v1/organization/{organization_id}
Delete organizationDELETE/v1/organization/{organization_id}

Deleting an organization (DELETE /v1/organization/{organization_id}) is a permanent action. All associated data, including users and configurations, will be immediately inaccessible.

Example: Creating a new organization

To create a new workspace, send a POST request with the required organization details.

curl -X POST https://api.example.com/v1/organization 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Acme Corp",
    "billing_email": "billing@acmecorp.com"
  }'

Onboarding & Customization

Once an organization is created, you can finalize its setup and customize its appearance.

  1. 1

    Complete Onboarding

    Call POST /v1/organization/{organization_id}/complete-onboarding to mark the workspace as fully provisioned and ready for users.

  2. 2

    Upload a Logo

    Call POST /v1/organization/{organization_id}/upload-logo with a multipart form payload to set the organization's avatar.

We recommend uploading logos in a square aspect ratio (e.g., 400x400 pixels) in PNG or JPEG format for the best display quality in the UI.

Managing Users & Invitations

Organizations are collaborative spaces. Use these endpoints to manage the members of a specific organization and handle the invitation lifecycle.

Organization Member Endpoints

ActionMethodEndpoint
List all usersGET/v1/organization/{organization_id}/user
List active usersGET/v1/organization/{organization_id}/user/active
List pending invitesGET/v1/organization/{organization_id}/user/pending
Invite a userPOST/v1/organization/{organization_id}/user/invite

User Invitation Endpoints

When a user receives an invitation, they can use the following endpoints to view and accept it.

ActionMethodEndpoint
View my pending invitesGET/v1/invitations
Accept an invitePOST/v1/invitations/{invitation_id}/accept

Events & Documentation Backups

Organizations also support event tracking and documentation backups. Use these endpoints to manage project-specific events and restore documentation states.

Events

ActionMethodEndpoint
List events for a projectGET/v1/organizations/{organization_id}/projects/{project_id}/events
Create a new eventPOST/v1/organizations/{organization_id}/projects/{project_id}/events
List events (simplified)POST/v1/event/list
Delete an eventDELETE/v1/event
Get VAPID public keyGET/v1/event/vapid-public-key

Documentation Backups

ActionMethodEndpoint
Restore documentation backupPOST/v1/documentation/{organization_id}/documentation/{documentation_id}/backup/restore

Administrator Endpoints

The following endpoints are restricted to system administrators. They provide global visibility into all customers and organizations across the platform.

These endpoints require elevated Admin privileges. Standard user tokens will receive a 403 Forbidden response.

ActionMethodEndpoint
List all organizationsGET/v1/organization/all
List all customersGET/v1/admin/customers
Export customers (CSV)GET/v1/admin/customers/export
Get customer overviewGET/v1/admin/customers/{organization_id}

Internal Services (S2S)

For server-to-server (S2S) communication, internal endpoints are available to manage backend subscriptions:

  • Toggle active documentation: POST /internal/subscriptions/{organization_id}/toggle-active

Frequently Asked Questions

Who can invite new users to an organization?

Only users with the Admin or Owner role within a specific organization can send invitations using the /user/invite endpoint.

Do invitations expire?

Yes, pending invitations automatically expire after 7 days. If an invitation expires, an administrator will need to send a new one.

What is the difference between 'all users' and 'active users'?

The /user endpoint returns everyone associated with the organization, including those who have been suspended or deactivated. The /user/active endpoint filters the list to only include members who currently have access.