v1

latestOpenAPI 3.1.02026-07-2295105298.6 KB

Groups

Create Group

Creates a new group with associated websites. Requires a global API key. Partner integrations may include an external_id to map their own identifier onto the new Athena group.

post/api/v1/groups

Request body

namestring required

Name of the group.

website_idsstring[] required

List of website IDs to include in the group. All websites must belong to your organization.

billing_enabledboolean

Whether to enable billing for this group

external_idstring

Partner-only. An identifier from your own system to map to this Athena group. Accepted only when authenticating with an API key for an organization flagged as a partner. Sending this field as a direct customer returns 403 Forbidden. Must be unique per resource type within your organization — duplicates return 409 with the existing resource in the payload.

Example request

{
  "name": "Enterprise Clients",
  "website_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987e6543-e21b-12d3-a456-426614174000"
  ],
  "external_id": "acct_9e4c1b8d"
}

Response

Group created successfully

billingEntityCreatedboolean

Present only when billing_enabled was requested: whether the billing entity exists after provisioning. When false, entity creation failed even after a retry, and setting group credits fails with a 400 until billing is repaired via PATCH /api/v1/groups/{group_id} with billing_enabled: true.

Example response

{
  "group": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Enterprise Clients",
    "orgId": "987e6543-e21b-12d3-a456-426614174000",
    "websiteIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "createdAt": "2024-06-15T10:30:00.000Z",
    "externalId": "acct_9e4c1b8d"
  }
}