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:

curl -H "X-API-Key: ago_v1_sk_..." https://your-instance.useago.com/api/v1/organizations

See 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

{
  "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

{
  "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

{
  "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 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:

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

Exclude an organization by UUID:

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:

{
  "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 - List and look up users
• Public API Overview - Authentication and general API usage
• API Key Authentication - Create and manage API keys