Skip to main content
POST
/
organizations
Create a new organization
curl --request POST \
  --url http://sandbox.mintlify.com/organizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "logo": "https://example.com/logo.png"
}
'
Creates a new organization with the authenticated user as the owner.

​
Authentication

This endpoint requires authentication via Bearer token:
  • Authorization: Bearer <token>

​
Permissions

All authenticated users can create organizations. The user who creates the organization automatically becomes the owner.

​
Request Body

FieldTypeRequiredDescription
namestringYesOrganization name (3-100 characters)
slugstringYesURL-friendly identifier (3-50 characters)
logostringNoURL to organization logo image

​
Organization Roles

After creation, the organization will have the following role structure:
  • Owner: Full control (cannot be changed or removed)
  • Admin: Can manage members and settings
  • Member: Basic access to organization resources

​
Slug Requirements

The organization slug must be:
  • Unique across all organizations
  • URL-friendly (lowercase letters, numbers, hyphens)
  • Between 3-50 characters
  • Cannot be changed after creation
The slug is used in URLs: /org/{slug}/...

​
Example Request

curl -X POST http://localhost:3001/api/organizations \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "logo": "https://example.com/logo.png"
  }'

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "logo": "https://example.com/logo.png",
  "plan": "free",
  "ownerId": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-12-26T10:00:00Z",
  "updatedAt": "2025-12-26T10:00:00Z"
}

​
Common Errors

​
409 Conflict

The slug is already taken by another organization. Choose a different slug. 
{
  "statusCode": 409,
  "message": "Organization slug already exists"
}

​
400 Bad Request

Invalid input data (e.g., slug too short, invalid characters). 
{
  "statusCode": 400,
  "message": ["slug must be at least 3 characters long"]
}

​
Best Practices

  • Use descriptive organization names
  • Choose slugs that are easy to remember and type
  • Slugs are permanent, so choose carefully
  • Keep logo images under 2MB for best performance

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Organization name

Required string length: 1 - 100
Example:

"Acme Corporation"

​
slug
string
required

Organization URL slug

Required string length: 1 - 100
Pattern: ^[a-z0-9-]+$
Example:

"acme-corp"

Organization logo URL

Example:

"https://example.com/logo.png"

Response

Organization created successfully. The user becomes the organization owner.