> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/core-api/organization.md).

# 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](/developer-guide/platform-api/workspaces.md) instead of Organization. A workspace maps to an organization through 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, `admin@amigo.ai`, granted the `DefaultSuperAdministratorRole`
* Provisions the authentication tenant and the hosted Amigo frontend domain (`{org_id}.amigo.ai`) for the organization

{% hint style="warning" %}
**Required Fields** The required fields are `org_name`, `user_dimensions`, the branding assets (`logo`, `square_logo`, `favicon`), and `azure_devops_team_name`. The `default_user_preferences` field is optional and defaults if omitted. The `x-mongo-cluster-name` header is mandatory for this endpoint.
{% 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 endpoint is called with user authentication credentials and the authenticated user has the `Organization:GetOrganizationDetails` permission.
{% 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";

// See the Authentication guide for client configuration
const client = new AmigoClient({ ...config });

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

{% endtab %}

{% tab title="Python" %}

```python
from amigo_sdk import AmigoClient

# See the Authentication guide for client configuration
with AmigoClient() as client:
    organization = client.organizations.get()
    print(organization.org_name)
```

{% endtab %}

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

```python
from amigo_sdk import AsyncAmigoClient

# See the Authentication guide for client configuration
async with AsyncAmigoClient() as client:
    organization = await client.organizations.get()
    print(organization.org_name)
```

{% endtab %}
{% endtabs %}

## Modify an Organization

Update organization settings: branding assets (`logo`, `square_logo`, `favicon`), `user_dimensions`, and `default_user_preferences`. Only the fields you provide are updated.

**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 rolled back. The organization is considered deleted after the first call, even if it does not fully succeed. Call the endpoint again 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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/core-api/organization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.