# 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/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 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 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

* Core API → [Agents & Context Graphs](/developer-guide/classic-api/core-api/agents-and-context-graphs.md)
* Core 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.