# Organization

Manage organization lifecycle and configuration. Organizations are the top-level scope for all Amigo resources including users, services, agents, context graphs, and tools.

{% hint style="info" %}
**Organization Scope** All API operations are scoped to an organization. The `{organization}` path parameter is the organization ID returned when creating an organization.
{% endhint %}

{% hint style="info" %}
**Platform API uses Workspaces** - The Platform API scopes resources by [Workspace](https://docs.amigo.ai/developer-guide/platform-api/platform-api/workspaces) instead of Organization. A workspace maps to an organization via the `backend_org_id` field.
{% endhint %}

## Create an Organization

Set up a new organization in the Amigo system. This operation:

* Creates the organization in the database with the supplied details
* Creates four default roles: `DefaultUserRole`, `DefaultAdministratorRole`, `DefaultAmigoAdministratorRole`, `DefaultSuperAdministratorRole`
* Creates a super user with `DefaultSuperAdministratorRole` using the designated admin email
* Provisions required infrastructure (analytics tenant, tool repository, etc.)

{% hint style="warning" %}
**Required Fields** All fields including branding assets (`logo`, `square_logo`, `favicon`, `signup_page_headshot`), content (`org_name`, `title`, `main_description`, `sub_description`), `user_dimensions`, `onboarding_instructions`, and `azure_devops_team_name` are required.
{% endhint %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/organization/" method="put" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% hint style="info" %}
**SDK Support** Organization creation is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.
{% endhint %}

## Get Organization Details

Retrieve the details of an organization.

{% hint style="info" %}
**Permissions** The `default_user_preferences` field is only populated if the caller has administrative permissions.
{% endhint %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/organization/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({
  apiKey: process.env.AMIGO_API_KEY!,
  apiSecret: process.env.AMIGO_API_SECRET!,
  organizationId: "my-org",
});

const organization = await client.organizations.getOrganization();
console.log(organization.org_name);
```

{% endtab %}

{% tab title="Python" %}

```python
from amigo_sdk import AmigoClient

client = AmigoClient(
    api_key="your-api-key",
    api_secret="your-api-secret",
    organization_id="my-org",
)

organization = client.organizations.get()
print(organization.org_name)
```

{% endtab %}

{% tab title="Python (async)" %}

```python
from amigo_sdk import AsyncAmigoClient

client = AsyncAmigoClient(
    api_key="your-api-key",
    api_secret="your-api-secret",
    organization_id="my-org",
)

organization = await client.organizations.get()
print(organization.org_name)
```

{% endtab %}
{% endtabs %}

## Modify an Organization

Update organization settings such as branding, descriptions, and preferences.

**Permission required:** `Organization:ModifyOrganization`

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/organization/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% hint style="info" %}
**SDK Support** Organization modification is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.
{% endhint %}

## Delete an Organization

Permanently delete an organization and all associated data. Some analytical data is removed asynchronously at a later date.

{% hint style="danger" %}
**Irreversible Operation** This endpoint is **not transactional**. If any step fails during execution, previously completed steps are not reverted. The organization is considered deleted after the first call, even if it does not fully succeed. Re-call the endpoint until it returns success to ensure all cleanup completes.
{% endhint %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/organization/" method="delete" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% hint style="info" %}
**SDK Support** Organization deletion is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.
{% endhint %}

## Get User Dimensions

Retrieve the list of user dimensions configured for the organization. User dimensions define the structured attributes tracked for each user.

**Permission required:** `Organization:GetOrganizationDetails`

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/organization/user\_dimensions/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% hint style="info" %}
**SDK Support** User dimensions retrieval is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.
{% endhint %}

## Related

* Core API → [Agents & Context Graphs](https://docs.amigo.ai/developer-guide/classic-api/core-api/agents-and-context-graphs)
* Core API → [Services](https://docs.amigo.ai/developer-guide/classic-api/core-api/services)
* Getting Started → [Authentication](https://docs.amigo.ai/developer-guide/getting-started/authentication)
* Best Practices → [Multi-Org Strategy](https://docs.amigo.ai/developer-guide/operations/devops/multi-org-tenancy)