Organization CRUD Operations

Create Organization

Endpoint

POST /organizations

Request

{
  "name": "Engineering",
  "slug": "engineering",
  "parentId": null
}

Fields

Field	Type	Required	Description
name	string	Yes	Display name
slug	string	No	URL-friendly ID (auto-generated if not provided)
parentId	UUID	No	Parent organization ID (null for root)

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Engineering",
  "slug": "engineering",
  "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "parentId": null,
  "status": "ACTIVE",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

List Organizations

Endpoint

GET /organizations

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)
parentId	UUID	Filter by parent organization
status	string	Filter by status (ACTIVE, INACTIVE)
search	string	Search by name

Response (200 OK)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Engineering",
      "slug": "engineering",
      "parentId": null,
      "status": "ACTIVE"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Frontend Team",
      "slug": "frontend-team",
      "parentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "ACTIVE"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Get Organization

Endpoint

GET /organizations/:id

Response (200 OK)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Engineering",
  "slug": "engineering",
  "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "parentId": null,
  "status": "ACTIVE",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "_count": {
    "children": 3,
    "memberships": 15
  }
}

Update Organization

Endpoint

PATCH /organizations/:id

Request

{
  "name": "Engineering Department"
}

Updatable Fields

Field	Type	Description
name	string	Display name
parentId	UUID	Move to different parent
status	string	Change status

Response (200 OK)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Engineering Department",
  "slug": "engineering",
  "parentId": null,
  "status": "ACTIVE",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}

Delete Organization

Endpoint

DELETE /organizations/:id

Response (204 No Content)

No response body on success.

Error: Has Children

{
  "type": "https://api.cortex.purplelab.ai/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Cannot delete organization with child organizations. Delete or reassign children first."
}

Code Examples

TypeScript

interface Organization {
  id: string;
  name: string;
  slug: string;
  tenantId: string;
  parentId: string | null;
  status: 'ACTIVE' | 'INACTIVE';
}

interface CreateOrganizationDto {
  name: string;
  slug?: string;
  parentId?: string;
}

// Create organization
async function createOrganization(
  accessToken: string,
  data: CreateOrganizationDto
): Promise<Organization> {
  const response = await fetch('http://localhost:8091/organizations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
    },
    body: JSON.stringify(data),
  });
  return response.json();
}

// List organizations
async function listOrganizations(
  accessToken: string,
  params?: { page?: number; parentId?: string }
): Promise<{ data: Organization[]; pagination: any }> {
  const url = new URL('http://localhost:8091/organizations');
  if (params?.page) url.searchParams.set('page', String(params.page));
  if (params?.parentId) url.searchParams.set('parentId', params.parentId);

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${accessToken}` },
  });
  return response.json();
}

cURL

# Create organization
curl -X POST http://localhost:8091/organizations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"name": "Engineering", "slug": "engineering"}'

# List organizations
curl http://localhost:8091/organizations \
  -H "Authorization: Bearer <access-token>"

# Get organization
curl http://localhost:8091/organizations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access-token>"

# Update organization
curl -X PATCH http://localhost:8091/organizations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"name": "Engineering Department"}'

# Delete organization
curl -X DELETE http://localhost:8091/organizations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access-token>"