> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization API

> List organizations and their email domains via the Public API

Read-only access to organizations and their email domains. Use these endpoints to look up organization details, search by name, and retrieve email domain configurations.

## Authentication

All endpoints require an API key with the `accounts:read` scope:

```bash theme={null}
curl -H "X-API-Key: ago_v1_sk_..." https://your-instance.useago.com/api/v1/organizations
```

See [API Key Authentication](/security/api-key-authentication) for setup instructions.

***

## List Organizations

Get a paginated list of all organizations with user and conversation counts.

```
GET /api/v1/organizations
```

### Query Parameters

| Parameter  | Type    | Default | Description                                    |
| ---------- | ------- | ------- | ---------------------------------------------- |
| page       | integer | 1       | Page number                                    |
| page\_size | integer | 50      | Items per page (max 100)                       |
| search     | string  | —       | Filter by organization name (case-insensitive) |

### Response

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "organization",
      "id": "e1b7d9bf-c3ee-4339-ad43-84632d65f800",
      "name": "Acme Corporation",
      "description": "A technology company",
      "is_system": false,
      "user_count": 25,
      "conversation_count": 142,
      "created_at": "2024-01-15T10:00:00+00:00",
      "updated_at": "2024-06-01T14:30:00+00:00"
    }
  ],
  "has_more": false,
  "total": 1
}
```

### Response Fields

| Field               | Type              | Description                                            |
| ------------------- | ----------------- | ------------------------------------------------------ |
| id                  | string (UUID)     | Organization identifier                                |
| name                | string            | Organization name                                      |
| description         | string or null    | Organization description                               |
| is\_system          | boolean           | Whether this is a system-managed organization          |
| user\_count         | integer           | Number of users in this organization                   |
| conversation\_count | integer           | Number of conversations from this organization's users |
| created\_at         | string (ISO 8601) | Creation timestamp                                     |
| updated\_at         | string (ISO 8601) | Last update timestamp                                  |

***

## Get Organization

Get a single organization by ID, including its email domains.

```
GET /api/v1/organizations/{org_id}
```

### Path Parameters

| Parameter | Type          | Description             |
| --------- | ------------- | ----------------------- |
| org\_id   | string (UUID) | Organization identifier |

### Response

```json theme={null}
{
  "object": "organization",
  "id": "e1b7d9bf-c3ee-4339-ad43-84632d65f800",
  "name": "Acme Corporation",
  "description": "A technology company",
  "is_system": false,
  "user_count": 25,
  "conversation_count": 142,
  "created_at": "2024-01-15T10:00:00+00:00",
  "updated_at": "2024-06-01T14:30:00+00:00",
  "email_domains": [
    {
      "object": "email_domain",
      "id": "992e324b-dcce-4a16-9ff8-1b78b4656d01",
      "domain": "acme.com",
      "is_primary": true,
      "created_at": "2024-01-15T10:00:00+00:00"
    },
    {
      "object": "email_domain",
      "id": "e6f67311-ad66-4657-b83f-23abbc20327b",
      "domain": "acme.io",
      "is_primary": false,
      "created_at": "2024-02-01T12:00:00+00:00"
    }
  ]
}
```

The detail view includes the same fields as the list view, plus an `email_domains` array. Each email domain has:

| Field       | Type              | Description                                             |
| ----------- | ----------------- | ------------------------------------------------------- |
| id          | string (UUID)     | Email domain identifier                                 |
| domain      | string            | The email domain (e.g. "acme.com")                      |
| is\_primary | boolean           | Whether this is the primary domain for the organization |
| created\_at | string (ISO 8601) | Creation timestamp                                      |

***

## List Organization Email Domains

Get email domains for a specific organization, paginated.

```
GET /api/v1/organizations/{org_id}/email-domains
```

### Query Parameters

| Parameter  | Type    | Default | Description              |
| ---------- | ------- | ------- | ------------------------ |
| page       | integer | 1       | Page number              |
| page\_size | integer | 50      | Items per page (max 100) |

### Response

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "email_domain",
      "id": "992e324b-dcce-4a16-9ff8-1b78b4656d01",
      "domain": "acme.com",
      "is_primary": true,
      "created_at": "2024-01-15T10:00:00+00:00"
    }
  ],
  "has_more": false,
  "total": 1
}
```

***

## Filter Conversations by Organization

The [Conversations API](/api/conversations-history-api) supports filtering by organization. This requires both `conversations:read` and `accounts:read` scopes on your API key.

```
GET /api/v1/conversations?organization=Acme+Corporation
```

| Parameter             | Type   | Description                                                                        |
| --------------------- | ------ | ---------------------------------------------------------------------------------- |
| organization          | string | Include only conversations from this organization (UUID or name, case-insensitive) |
| exclude\_organization | string | Exclude conversations from this organization (UUID or name, case-insensitive)      |

You can pass either the organization UUID or its name. Name matching is case-insensitive.

### Examples

Filter by organization name:

```bash theme={null}
curl -H "X-API-Key: ago_v1_sk_..." \
  "https://your-instance.useago.com/api/v1/conversations?organization=Acme+Corporation"
```

Exclude an organization by UUID:

```bash theme={null}
curl -H "X-API-Key: ago_v1_sk_..." \
  "https://your-instance.useago.com/api/v1/conversations?exclude_organization=e1b7d9bf-c3ee-4339-ad43-84632d65f800"
```

***

## MCP Tools

These endpoints are also available as MCP tools for AI agent integrations:

| Tool                              | Description                                   |
| --------------------------------- | --------------------------------------------- |
| `list_organizations`              | List organizations with search and pagination |
| `get_organization`                | Get organization details with email domains   |
| `list_organization_email_domains` | List email domains for an organization        |

The `list_conversations` MCP tool also supports the `organization` and `exclude_organization` parameters.

***

## Error Handling

All endpoints return errors in the standard format:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "Organization not found with ID '00000000-0000-0000-0000-000000000000'.",
    "param": "org_id",
    "doc_url": "https://ago.mintlify.app/api/errors#not_found"
  }
}
```

| Status | Code                | Description                               |
| ------ | ------------------- | ----------------------------------------- |
| 403    | insufficient\_scope | API key missing the `accounts:read` scope |
| 404    | not\_found          | Organization not found or invalid UUID    |

***

## Related Documentation

* [Users API](/api/users-api) - List and look up users
* [Public API Overview](/api/public-api-v1) - Authentication and general API usage
* [API Key Authentication](/security/api-key-authentication) - Create and manage API keys