Create Organization

Create a new organization

curl --request POST \
  --url https://api.example.com/organizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "logo": "https://example.com/logo.png"
}
'

import requests

url = "https://api.example.com/organizations"

payload = {
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "logo": "https://example.com/logo.png"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Acme Corporation',
    slug: 'acme-corp',
    logo: 'https://example.com/logo.png'
  })
};

fetch('https://api.example.com/organizations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/organizations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Acme Corporation',
    'slug' => 'acme-corp',
    'logo' => 'https://example.com/logo.png'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/organizations"

	payload := strings.NewReader("{\n  \"name\": \"Acme Corporation\",\n  \"slug\": \"acme-corp\",\n  \"logo\": \"https://example.com/logo.png\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/organizations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme Corporation\",\n  \"slug\": \"acme-corp\",\n  \"logo\": \"https://example.com/logo.png\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/organizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Acme Corporation\",\n  \"slug\": \"acme-corp\",\n  \"logo\": \"https://example.com/logo.png\"\n}"

response = http.request(request)
puts response.read_body

POST

organizations

Create a new organization

curl --request POST \
  --url https://api.example.com/organizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "logo": "https://example.com/logo.png"
}
'

import requests

url = "https://api.example.com/organizations"

payload = {
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "logo": "https://example.com/logo.png"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Acme Corporation',
    slug: 'acme-corp',
    logo: 'https://example.com/logo.png'
  })
};

fetch('https://api.example.com/organizations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/organizations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Acme Corporation',
    'slug' => 'acme-corp',
    'logo' => 'https://example.com/logo.png'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/organizations"

	payload := strings.NewReader("{\n  \"name\": \"Acme Corporation\",\n  \"slug\": \"acme-corp\",\n  \"logo\": \"https://example.com/logo.png\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/organizations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Acme Corporation\",\n  \"slug\": \"acme-corp\",\n  \"logo\": \"https://example.com/logo.png\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/organizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Acme Corporation\",\n  \"slug\": \"acme-corp\",\n  \"logo\": \"https://example.com/logo.png\"\n}"

response = http.request(request)
puts response.read_body

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

Field	Type	Required	Description
`name`	string	Yes	Organization name (3-100 characters)
`slug`	string	Yes	URL-friendly identifier (3-50 characters)
`logo`	string	No	URL 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 https://api.timbrix.mx/organizations \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "logo": "https://example.com/logo.png"
  }'

import { Timbrix } from "@timbrix/sdk"

const client = new Timbrix({ bearerToken: "<your_token>" })

const organization = await client.organizations.create({
  name: "Acme Corp",
  slug: "acme-corp",
  logo: "https://example.com/logo.png",
})
console.log(organization)

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"

logo

string

Organization logo URL

Example:

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

Response

Organization created successfully. The user becomes the organization owner.

​Authentication

​Permissions

​Request Body

​Organization Roles

​Slug Requirements

​Example Request

​Example Response

​Common Errors

​409 Conflict

​400 Bad Request

​Best Practices

Authorizations

Body

Response

Authentication

Permissions

Request Body

Organization Roles

Slug Requirements

Example Request

Example Response

Common Errors

409 Conflict

400 Bad Request

Best Practices