Organization

Create, modify, and delete organizations. Manage user dimensions and branding configuration.

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

Organization Scope All API operations are scoped to an organization. The {organization} path parameter is the organization ID returned when creating an organization.

Platform API uses Workspaces: The Platform API scopes resources by Workspace instead of Organization. A workspace maps to an organization through the backend_org_id field.

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

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.

Create an organization

put

/v1/{organization}/organization/

Set up a new organization in the Amigo system. Specifically, it

creates a new organization within the Amigo Mongo database with the given details.
- Along with the new organization, 4 default roles are created:
  - DefaultUserRole.
  - DefaultAdministratorRole.
  - DefaultAmigoAdministratorRole.
  - DefaultSuperAdministratorRole.
- A super user, admin@amigo.ai, is created and granted the DefaultSuperAdministratorRole.
creates a new tenant in Google Identity Platform for users in this organization.
creates a new Route53 record, {org_id}.amigo.ai, that hosts the Amigo frontend for this organization.
creates a new domain, {org_id}.amigo.ai, on Vercel.

The x-mongo-cluster-name header is mandatory for this endpoint.

Permissions

This endpoint requires the following permissions:

Organization:CreateOrganization. for the organization to create.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestringRequired

The Mongo cluster name to perform this request in.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

org_namestring · min: 1Required

A human friendly name of the organization.

logostring · base64Required

A logo for the organization that will be displayed on the Amigo frontend for this organization, as well as all Amigo communications to users on behalf of the organization. Must be provided as base64 encoded bytes of a PNG image of aspect ratio 5:2 with minimum size 400 * 160 pixels.

square_logostring · base64Required

A square logo of the organization. Must be provided as base64 encoded bytes of a square PNG image of size at least 40 * 40 pixels.

faviconstring · base64Required

Favicon for the Amigo frontend for this organization. Must be provided as base64 encoded bytes of a square ICO image that's of size at least 40 * 40 pixels.

azure_devops_team_namestring · min: 1 · max: 20Required

The name of the Azure DevOps team to create (if it doesn't exist) for this organization. All orgs with the same Azure DevOps team name will share access to the same Azure DevOps resources, namely the source code for tools.

Pattern: ^[a-z-]+$

Responses

201

Succeeded.

application/json

org_idstringRequired

ID of the newly created organization. This is used to identify the organization that a resource belongs to in all Amigo endpoints.

400

The specified organization ID is reserved.

401

Invalid authorization credentials.

403

Missing required permissions.

409

Conflicts with existing organization with the same org_id, or a related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 5 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

put/v1/{organization}/organization/

PUT /v1/{organization}/organization/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
x-mongo-cluster-name: text
Content-Type: application/json
Accept: */*
Content-Length: 386

{
  "org_name": "text",
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ],
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "default_user_preferences": {
    "enable_response_recommendation": false,
    "preferred_language": "aaa",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "timezone": "Africa/Abidjan",
    "audio_keyterms": [
      "text"
    ]
  },
  "azure_devops_team_name": "text"
}

{
  "org_id": "text"
}

SDK Support Organization creation is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.

Get Organization Details

Retrieve the details of an organization.

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.

Get an organization

get

/v1/{organization}/organization/

Get the details of an organization.

Permissions

This endpoint may be impacted by the following 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.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

org_idstringRequired

Unique identifier of the organization.

org_namestringRequired

A human friendly name of the organization.

tenant_idstring · nullableRequired

The tenant ID of the organization. This field is only populated if the authenticated user has the Organization:GetOrganizationDetails permission.

404

The specified organization does not exist.

422

Invalid request path parameter failed validation.

503

The service is going through temporary maintenance.

get/v1/{organization}/organization/

GET /v1/{organization}/organization/ HTTP/1.1
Host: api.amigo.ai
Accept: */*

{
  "org_id": "text",
  "org_name": "text",
  "default_user_preferences": {
    "enable_response_recommendation": false,
    "preferred_language": "text",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "timezone": "text",
    "audio_keyterms": [
      "text"
    ]
  },
  "tenant_id": "text"
}

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);

from amigo_sdk import AmigoClient

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

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)

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

Modify an organization

post

/v1/{organization}/organization/

Modify elements of an organization.

Permissions

This endpoint requries the following permissions:

Organization:ModifyOrganization to modify the organization.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

logostring · base64 · nullableOptional

square_logostring · base64 · nullableOptional

A square logo of the organization. Must be provided as base64 encoded bytes of a square PNG image of size at least 40 * 40 pixels. Only updated if not null.

faviconstring · base64 · nullableOptional

Favicon for the Amigo frontend for this organization. Must be provided as base64 encoded bytes of a square ICO image that's of size at least 40 * 40 pixels. Only updated if not null.

Responses

204

Succeeded.

No content

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization does not exist.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 10 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post/v1/{organization}/organization/

POST /v1/{organization}/organization/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 336

{
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ],
  "default_user_preferences": {
    "enable_response_recommendation": false,
    "preferred_language": "aaa",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "timezone": "Africa/Abidjan",
    "audio_keyterms": [
      "text"
    ]
  }
}

No content

SDK Support Organization modification is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.

Delete an Organization

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

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.

Delete an organization

delete

/v1/{organization}/organization/

Delete an organization. All of the organization's data are erased. Some analytical data will be asynchronously removed at a future date.

Unlike other endpoints, this endpoint is not transactional. If any operation fails during the execution, the endpoint does not revert the performed actions. The caller should re-call this endpoint until it succeeds.

Regardless of whether this endpoint succeeds or not, the first time this endpoint is called, the organization is considered deleted. Even if the endpoint fails and the organization isn't completely wiped, it's considered in an invalid state and any other operations on it may fail.

Permissions

This endpoint requires the following permissions:

Organization:DeleteOrganization for the organization to delete.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

No content

400

The current environment or organization does not support this endpoint.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

409

A related operation is in progress.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 5 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

delete/v1/{organization}/organization/

DELETE /v1/{organization}/organization/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

SDK Support Organization deletion is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.

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

Get user dimensions for the organization

get

/v1/{organization}/organization/user_dimensions/

Get the list of user dimensions for the organization.

Permissions

This endpoint requires the following permissions:

Organization:GetOrganizationDetails for the current organization.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

The organization does not exist.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get/v1/{organization}/organization/user_dimensions/

GET /v1/{organization}/organization/user_dimensions/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ]
}

SDK Support User dimensions retrieval is not yet available in the Python or TypeScript SDKs. Use a direct HTTP request for this operation.

Classic API -> Agents & Context Graphs
Classic API -> Services
Getting Started → Authentication
Best Practices → Multi-Org Strategy

PreviousClassic API NextAgents & Context Graphs

Last updated 25 days ago

Was this helpful?

Good night

Create an Organization

Create an organization

Permissions

Get Organization Details

Get an organization

Permissions

Modify an Organization

Modify an organization

Permissions

Delete an Organization

Delete an organization

Permissions

Get User Dimensions

Get user dimensions for the organization

Permissions

Related