> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations API

> View your organization structure and hierarchy

# Organizations API

The Organizations API allows you to retrieve your organization's hierarchical structure. For holding companies with subsidiaries, this provides a complete tree view of all child organizations and their relationships.

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability.
</Note>

## Key Features

* **Organization Tree**: View the complete hierarchical structure from the top-level holding down to all subsidiaries and child organizations
* **Automatic Root Detection**: Always returns the full tree from the root organization, regardless of which organization the API key belongs to
* **Clean & Simple**: Minimal response with just the essential fields (id, name, children)

## Authentication

All endpoints require authentication using an API key included in the `x-api-key` header.

## Headers

All requests must include:

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Organization Tree" icon="sitemap" href="/api-reference/organizations/tree">
    View the complete organizational hierarchy
  </Card>
</CardGroup>

## Data Model

### Organization Tree Node

Each node in the tree represents an organization:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "dce3ff33-9fcc-4521-910f-7972d81fb70c",
  "name": "Acme Holdings",
  "children": [
    {
      "id": "d9e08b1a-bd28-4950-a730-3c300a2ff91e",
      "name": "Acme Construction",
      "children": [
        {
          "id": "22dcadf6-2da8-4077-a555-7da22c3c5eae",
          "name": "Project Alpha",
          "children": []
        }
      ]
    },
    {
      "id": "e3d4c82b-1a8c-429c-aaea-1f82b6bd7fe4",
      "name": "Acme Services",
      "children": []
    }
  ]
}
```

### Node Attributes

| Field      | Type   | Description                                                  |
| ---------- | ------ | ------------------------------------------------------------ |
| `id`       | UUID   | Unique identifier for the organization                       |
| `name`     | string | Organization name                                            |
| `children` | array  | List of child organization nodes (same structure, recursive) |

## Use Cases

### View Holding Structure

Retrieve the full organization tree for a holding company:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

response = requests.get(
    "https://api.dcycle.io/v2/organizations/tree",
    headers=headers
)

tree = response.json()
print(f"Holding: {tree['name']}")
for subsidiary in tree["children"]:
    print(f"  - {subsidiary['name']} ({len(subsidiary['children'])} children)")
```

### Find Specific Subsidiaries

Navigate the tree to find specific child organizations:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def find_org(node, name_contains):
    """Recursively search the tree for an organization by name."""
    results = []
    if name_contains.lower() in node["name"].lower():
        results.append(node)
    for child in node.get("children", []):
        results.extend(find_org(child, name_contains))
    return results

tree = response.json()
matches = find_org(tree, "construction")
for org in matches:
    print(f"Found: {org['name']} ({org['id']})")
```

## Error Handling

### Common HTTP Status Codes

| Status | Meaning      | Solution                    |
| ------ | ------------ | --------------------------- |
| 200    | Success      | -                           |
| 401    | Unauthorized | Verify API key              |
| 404    | Not Found    | Check organization UUID     |
| 500    | Server Error | Contact support if persists |

### Error Response Format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Error description",
  "code": "ERROR_CODE"
}
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Manage vehicles within organizations
  </Card>

  <Card title="Employees API" icon="users" href="/api-reference/employees/overview">
    Manage employee commuting data
  </Card>

  <Card title="Invoices API" icon="file-invoice" href="/api-reference/invoices/overview">
    Manage invoices for organizations
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/organizations">
    Explore organization structure from AI assistants via MCP
  </Card>
</CardGroup>

## Rate Limiting

API requests are subject to rate limiting. Include rate limit information from response headers:

* `X-RateLimit-Limit`: Maximum requests per minute
* `X-RateLimit-Remaining`: Requests remaining
* `X-RateLimit-Reset`: Unix timestamp when limit resets