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 via 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 ([email protected]) with DefaultSuperAdministratorRole
Provisions required infrastructure (analytics tenant, tool repository, etc.)

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.

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, [email protected], 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.

titlestring · min: 1Required

An advertising tagline for the services offered by this organization.

main_descriptionstring · min: 1Required

A description of the services offered by this organization that is displayed on the login page for the Amigo frontend for this organization.

sub_descriptionstring · min: 1Required

Additional descriptions of the services offered by this organization that is displayed below main_description in a smaller font.

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.

signup_page_headshotstring · base64Required

An image of the main persona of the organization that is displayed on the signup page for this organization in base64 encoded bytes of a PNG image of size at least 292 * 400 pixels and aspect ratio 0.73. If not specified, a default headshot is used.

onboarding_instructionsstring[]Required

A list of markdown text that's displayed during the onboarding flow of this organization. Each entry corresponds to a page in the onboarding flow.

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

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: 517

{
  "org_name": "text",
  "title": "text",
  "main_description": "text",
  "sub_description": "text",
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ],
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "signup_page_headshot": "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"
    ]
  },
  "onboarding_instructions": [
    "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 caller has administrative permissions.

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-nameany ofOptional

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.

stringOptional

nullOptional

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.

titlestringRequired

An advertising tagline for the services offered by this organization.

main_descriptionstringRequired

A description of the services offered by this organization that is displayed on the login page for the Amigo frontend for this organization.

sub_descriptionstringRequired

Additional descriptions of the services offered by this organization that is displayed below main_description in a smaller font.

onboarding_instructionsstring[]Required

A list of markdown text that's displayed during the onboarding flow of this organization. Each entry corresponds to a page in the onboarding flow.

default_user_preferencesany ofRequired

Default user preferences for new users in this organization. This field is only populated if this endpoint is called with user authentication credentials, and the authenticated user has the Organization:GetOrganizationDetails permission.

nullOptional

tenant_idany ofRequired

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

stringOptional

nullOptional

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",
  "title": "text",
  "main_description": "text",
  "sub_description": "text",
  "onboarding_instructions": [
    "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";

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

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)

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)

Modify an Organization

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

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-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

titleany ofOptional

An advertising tagline for the services offered by this organization. If null, this field is not updated.

string · min: 1Optional

nullOptional

main_descriptionany ofOptional

A description of the services offered by this organization that is displayed on the login page for the Amigo frontend for this organization. If null, this field is not updated.

string · min: 1Optional

nullOptional

sub_descriptionany ofOptional

Additional descriptions of the services offered by this organization that is displayed below main_description in a smaller font. If null, this field is not updated.

string · min: 1Optional

nullOptional

logoany ofOptional

string · base64Optional

nullOptional

square_logoany ofOptional

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.

string · base64Optional

nullOptional

faviconany ofOptional

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.

string · base64Optional

nullOptional

signup_page_headshotany ofOptional

An optional image of the main persona of the organization that is displayed on the signup page for this organization in base64 encoded bytes of a PNG image of size at least 292 * 400 pixels and aspect ratio 0.73. Only updated if not null.

string · base64Optional

nullOptional

user_dimensionsany ofOptional

User dimensions for the organization. If not set or null, this field is not updated.

nullOptional

default_user_preferencesany ofOptional

The default user preferences for the organization. If null, this field is not updated.

nullOptional

onboarding_instructionsany ofOptional

A list of markdown text that's displayed during the onboarding flow of this organization. Each entry corresponds to a page in the onboarding flow. If null, this field is not updated.

string[]Optional

nullOptional

Responses

204

Succeeded.

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: 467

{
  "title": "text",
  "main_description": "text",
  "sub_description": "text",
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "signup_page_headshot": "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"
    ]
  },
  "onboarding_instructions": [
    "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 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.

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-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

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-nameany ofOptional

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.

stringOptional

nullOptional

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.

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

PreviousClassic API NextAgents & Context Graphs

Last updated 22 hours ago

Was this helpful?

Good afternoon

hashtagCreate an Organization

hashtagCreate an organization

Permissions

hashtagGet Organization Details

hashtagGet an organization

Permissions

hashtagModify an Organization

hashtagModify an organization

Permissions

hashtagDelete an Organization

hashtagDelete an organization

Permissions

hashtagGet User Dimensions

hashtagGet user dimensions for the organization

Permissions

hashtagRelated

Create an Organization

Create an organization

Get Organization Details

Get an organization

Modify an Organization

Modify an organization

Delete an Organization

Delete an organization

Get User Dimensions

Get user dimensions for the organization

Related