Organizations

List and manage organizations, members, and invitations.

List Organizations

GET /api/v1/organizations/

Returns all organizations the authenticated user belongs to.

Parameters

Name	Type	Required	Description
`ordering`	string	No	Field to order results by (query parameter)
`cursor`	string	No	Cursor for pagination (query parameter)
`limit`	integer	No	Number of results per page (query parameter)

Request

curl "https://server.avala.ai/api/v1/organizations/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "ee4h6d00-n17k-30m3-j605-335544330000",
      "name": "Acme Robotics",
      "slug": "acme-robotics",
      "logo_url": "https://storage.avala.ai/orgs/acme-robotics/logo.png",
      "member_count": 12,
      "created_at": "2024-06-01T12:00:00Z"
    }
  ]
}

Fields

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the organization
`name`	string	Display name of the organization
`slug`	string	URL-friendly identifier
`logo_url`	string	URL to the organization’s logo image, or `null` if not set
`member_count`	integer	Total number of members in the organization
`created_at`	string (datetime)	ISO 8601 timestamp of when the organization was created

Get Organization

GET /api/v1/organizations/{org_slug}/

Returns detailed information about a specific organization.

Parameters

Name	Type	Required	Description
`org_slug`	string	Yes	Slug identifier of the organization (path parameter)

Request

curl "https://server.avala.ai/api/v1/organizations/acme-robotics/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

Response

{
  "uid": "ee4h6d00-n17k-30m3-j605-335544330000",
  "name": "Acme Robotics",
  "slug": "acme-robotics",
  "logo_url": "https://storage.avala.ai/orgs/acme-robotics/logo.png",
  "member_count": 12,
  "created_at": "2024-06-01T12:00:00Z"
}

Fields

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the organization
`name`	string	Display name of the organization
`slug`	string	URL-friendly identifier
`logo_url`	string	URL to the organization’s logo image, or `null` if not set
`member_count`	integer	Total number of members in the organization
`created_at`	string (datetime)	ISO 8601 timestamp of when the organization was created

List Members

GET /api/v1/organizations/{org_slug}/members/

Returns all members of a specific organization, including their roles.

Parameters

Name	Type	Required	Description
`org_slug`	string	Yes	Slug identifier of the organization (path parameter)
`ordering`	string	No	Field to order results by (query parameter)
`cursor`	string	No	Cursor for pagination (query parameter)
`limit`	integer	No	Number of results per page (query parameter)

Request

curl "https://server.avala.ai/api/v1/organizations/acme-robotics/members/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "aa0d2900-j73g-96i9-f261-991100990000",
      "username": "janedoe",
      "email": "jane@acmerobotics.com",
      "role": "owner",
      "joined_at": "2024-06-01T12:00:00Z"
    },
    {
      "uid": "ff5i7e00-o28l-41n4-k716-446655440000",
      "username": "bobsmith",
      "email": "bob@acmerobotics.com",
      "role": "admin",
      "joined_at": "2024-07-15T09:00:00Z"
    },
    {
      "uid": "gg6j8f00-p39m-52o5-l827-557766550000",
      "username": "alicejones",
      "email": "alice@acmerobotics.com",
      "role": "member",
      "joined_at": "2024-08-20T11:30:00Z"
    }
  ]
}

Fields

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the member
`username`	string	Member’s username
`email`	string	Member’s email address
`role`	string	Member’s role in the organization (`owner`, `admin`, or `member`)
`joined_at`	string (datetime)	ISO 8601 timestamp of when the member joined the organization

Invite User

POST /api/v1/organizations/{org_slug}/invitations/

Sends an invitation to a user to join the organization. The invited user will receive an email with instructions to accept.

Parameters

Name	Type	Required	Description
`org_slug`	string	Yes	Slug identifier of the organization (path parameter)
`email`	string	Yes	Email address of the user to invite (body parameter)
`role`	string	Yes	Role to assign to the invited user: `admin` or `member` (body parameter)

Only users with the owner or admin role can invite new members. The owner role cannot be assigned through invitations.

Request

curl -X POST "https://server.avala.ai/api/v1/organizations/acme-robotics/invitations/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "role": "member"
  }'

Response

{
  "uid": "hh7k9g00-q40n-63p6-m938-668877660000",
  "email": "newuser@example.com",
  "role": "member",
  "status": "pending",
  "invited_by": "aa0d2900-j73g-96i9-f261-991100990000",
  "created_at": "2025-01-21T10:00:00Z"
}

Fields

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the invitation
`email`	string	Email address of the invited user
`role`	string	Role that will be assigned when the invitation is accepted
`status`	string	Invitation status (`pending`, `accepted`, or `expired`)
`invited_by`	string (UUID)	UID of the user who sent the invitation
`created_at`	string (datetime)	ISO 8601 timestamp of when the invitation was created

Member Roles

Organizations support three roles with different permission levels.

Role	Description	Permissions
`owner`	Organization owner	Full access. Can manage billing, delete the organization, transfer ownership, and manage all members including admins.
`admin`	Organization administrator	Can manage projects, datasets, and members. Can invite and remove members. Cannot delete the organization or manage billing.
`member`	Standard member	Can view and work on assigned projects and datasets. Cannot manage organization settings or invite new members.

Each organization must have exactly one owner. Ownership can only be transferred by the current owner through the Mission Control interface.

Error Responses

Not Found (404)

{
  "detail": "Not found."
}

Returned when the specified organization does not exist or the user is not a member.

Permission Denied (403)

{
  "detail": "You do not have permission to perform this action."
}

Returned when the authenticated user does not have the required role to perform the action (e.g., a member attempting to invite users).

Unauthorized (401)

{
  "detail": "Invalid API key."
}

Returned when the X-Avala-Api-Key header is missing or contains an invalid key.

Validation Error (400)

{
  "email": ["Enter a valid email address."],
  "role": ["\"superadmin\" is not a valid choice."]
}

Returned when the request body is missing required fields or contains invalid values.

Conflict (409)

{
  "detail": "An invitation for this email address already exists."
}

Returned when attempting to invite a user who has already been invited or is already a member of the organization.

Overview

Endpoints

Tools

List Organizations

Parameters

Request

Response

Fields

Get Organization

Parameters

Request

Response

Fields

List Members

Parameters

Request

Response

Fields

Invite User

Parameters

Request

Response

Fields

Member Roles

Error Responses

Not Found (404)

Permission Denied (403)

Unauthorized (401)

Validation Error (400)

Conflict (409)

Overview

Endpoints

Tools

​List Organizations

​Parameters

​Request

​Response

​Fields

​Get Organization

​Parameters

​Request

​Response

​Fields

​List Members

​Parameters

​Request

​Response

​Fields

​Invite User

​Parameters

​Request

​Response

​Fields

​Member Roles

​Error Responses

​Not Found (404)

​Permission Denied (403)

​Unauthorized (401)

​Validation Error (400)

​Conflict (409)

List Organizations

Parameters

Request

Response

Fields

Get Organization

Parameters

Request

Response

Fields

List Members

Parameters

Request

Response

Fields

Invite User

Parameters

Request

Response

Fields

Member Roles

Error Responses

Not Found (404)

Permission Denied (403)

Unauthorized (401)

Validation Error (400)

Conflict (409)