find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/athenahq-ai:athenahq-ai-groups-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: AthenaHQ Groups API
  description: AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization.
  version: 1.0.0
  contact:
    email: support@athenahq.ai
servers:
- url: https://api.athenahq.ai
  description: Production server
security:
- apiKey: []
tags:
- name: Groups
  description: Endpoints for managing groups of websites
paths:
  /api/v1/groups:
    get:
      tags:
      - Groups
      summary: List Groups
      description: Returns all groups for your organization, including associated websites. Requires a global API key. **Partner integrations** may pass `external_id` as a query parameter to find the Athena group mapped to a partner-supplied identifier. Partner responses additionally include `externalId` on each group and on every website object inside `websites` (`null` when no mapping exists), so sites can be matched by your own identifier instead of by URL.
      operationId: listGroups
      security:
      - apiKey: []
      parameters:
      - name: external_id
        in: query
        required: false
        schema:
          type: string
          minLength: 1
        description: '**Partner-only.** Filter results to the group mapped to this partner-supplied identifier. Accepted only when authenticating with a partner API key — direct customers that pass this parameter receive `403 Forbidden`. Exact match, scoped to your organization; unmapped IDs return an empty array.'
        example: acct_9e4c1b8d
      responses:
        '200':
          description: Successful response with list of groups. Partner responses include an `externalId` field on each item (string or `null`); direct-customer responses omit the field entirely.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
                required:
                - groups
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Requires a global API key, or (when using the `external_id` filter) a partner API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                global_required:
                  summary: Global API key required
                  value:
                    error: 'Forbidden: global API key required'
                partner_required:
                  summary: Partner API key required for external_id filter
                  value:
                    error: 'Forbidden: partner API key required'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Groups
      summary: Create Group
      description: 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.
      operationId: createGroup
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '201':
          description: Group created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/CreatedGroup'
                  billingEntityCreated:
                    type: boolean
                    description: '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.'
                required:
                - group
        '400':
          description: Bad request - Validation error or invalid website IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_website_ids:
                  value:
                    error: 'Website IDs not found in organization: 123e4567-e89b-12d3-a456-426614174000'
                missing_name:
                  value:
                    error: Group name is required
                missing_websites:
                  value:
                    error: At least one website_id is required
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Requires a global API key, or (partner-only field) the key lacks partner identity for an `external_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                global_required:
                  summary: Global API key required
                  value:
                    error: 'Forbidden: global API key required'
                partner_required:
                  summary: Partner API key required for external_id
                  value:
                    error: 'Forbidden: partner API key required'
        '409':
          description: Conflict - (partners only) the supplied `external_id` is already mapped to another group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalIdConflictError'
              examples:
                external_id_conflict:
                  summary: Partner external_id already mapped
                  value:
                    error: external_id_conflict
                    message: external_id acct_9e4c1b8d is already mapped to a group
                    existing:
                      id: 123e4567-e89b-12d3-a456-426614174000
                      externalId: acct_9e4c1b8d
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/groups/{group_id}:
    parameters:
    - name: group_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The unique identifier of the group
      example: 123e4567-e89b-12d3-a456-426614174000
    get:
      tags:
      - Groups
      summary: Get Group
      description: Returns a single group by ID, including associated websites. Requires a global API key. **Partner integrations** additionally receive an `externalId` field populated from the partner mapping (if any), and every website object inside `websites` carries its own `externalId` (`null` when that website has no mapping), so sites can be matched by your own identifier instead of by URL.
      operationId: getGroup
      security:
      - apiKey: []
      responses:
        '200':
          description: Successful response with the group. Partner responses include an `externalId` field (string or `null`); direct-customer responses omit the field entirely.
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/Group'
                required:
                - group
        '400':
          description: Bad request - Invalid group ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid group ID format
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Global API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Forbidden: global API key required'
        '404':
          description: Not found - Group does not exist or does not belong to your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Group not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - Groups
      summary: Update Group
      description: Updates a group's name, adds websites, removes websites, and/or (partners only) sets or clears the `external_id` mapping. At least one field must be provided. Requires a global API key. **Partner integrations** may pass `external_id` as a non-empty string to set/replace the mapping, or as `null` to clear it. The partner response includes `externalId` on the group and on every website object inside `websites` (`null` when no mapping exists).
      operationId: updateGroup
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      responses:
        '200':
          description: Group updated successfully. Partner responses include an `externalId` field (string or `null`); direct-customer responses omit the field entirely.
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/Group'
                required:
                - group
        '400':
          description: Bad request - Validation error or invalid website IDs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_fields:
                  value:
                    error: At least one of 'name', 'add_website_ids', 'remove_website_ids', 'external_id', or 'billing_enabled' is required
                invalid_website_ids:
                  value:
                    error: 'Website IDs not found in organization: 123e4567-e89b-12d3-a456-426614174000'
                invalid_group_id:
                  value:
                    error: Invalid group ID format
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Requires a global API key, or (partner-only field) the key lacks partner identity for an `external_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                global_required:
                  summary: Global API key required
                  value:
                    error: 'Forbidden: global API key required'
                partner_required:
                  summary: Partner API key required for external_id
                  value:
                    error: 'Forbidden: partner API key required'
        '404':
          description: Not found - Group does not exist or does not belong to your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Group not found
        '409':
          description: Conflict - (partners only) the supplied `external_id` is already mapped to another group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalIdConflictError'
              examples:
                external_id_conflict:
                  summary: Partner external_id already mapped
                  value:
                    error: external_id_conflict
                    message: external_id acct_9e4c1b8d is already mapped to a group
                    existing:
                      id: 123e4567-e89b-12d3-a456-426614174000
                      externalId: acct_9e4c1b8d
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Upstream billing provider failed to provision the billing entity. Only returned when `billing_enabled: true` is in the request body. No database changes were committed — the request can be retried cleanly.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Failed to provision billing entity
components:
  schemas:
    Error:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Unauthorized
    ExternalIdConflictError:
      type: object
      description: Returned when a partner tries to set an `external_id` that is already mapped to another resource of the same type within the organization. The `existing` field identifies the resource that currently holds the ID, letting the partner recover from a retry or reconcile their mapping.
      required:
      - error
      - message
      - existing
      properties:
        error:
          type: string
          enum:
          - external_id_conflict
          description: Machine-readable error code. Always `external_id_conflict`.
          example: external_id_conflict
        message:
          type: string
          description: Human-readable explanation of the conflict.
          example: external_id ws_a7f3b2c9 is already mapped to a website
        existing:
          type: object
          required:
          - id
          - externalId
          description: The resource that currently holds the conflicting `external_id`.
          properties:
            id:
              type: string
              format: uuid
              description: Athena ID of the existing resource.
              example: 123e4567-e89b-12d3-a456-426614174000
            externalId:
              type: string
              description: The external_id that is already mapped.
              example: ws_a7f3b2c9
    Group:
      type: object
      description: A group of websites in your organization
      required:
      - id
      - name
      - orgId
      - billingEnabled
      - createdAt
      - websites
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the group
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Display name of the group
          example: Enterprise Clients
        orgId:
          type: string
          format: uuid
          description: The organization ID the group belongs to
          example: 987e6543-e21b-12d3-a456-426614174000
        billingEnabled:
          type: boolean
          description: Whether billing is enabled for this group
          example: false
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the group was created (UTC)
          example: '2024-06-15T10:30:00.000Z'
        websites:
          type: array
          description: Websites associated with this group
          items:
            $ref: '#/components/schemas/GroupWebsite'
        externalId:
          type: string
          nullable: true
          description: '**Partner-only.** The partner-supplied identifier mapped to this group. Only present on responses to callers whose organization is flagged as a partner. Direct-customer responses omit the field entirely. `null` indicates no mapping exists for this group.'
          example: acct_9e4c1b8d
    CreateGroupRequest:
      type: object
      description: Request body for creating a new group
      required:
      - name
      - website_ids
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the group.
          example: Enterprise Clients
        website_ids:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
          description: List of website IDs to include in the group. All websites must belong to your organization. Duplicate IDs are collapsed to a single membership.
          example:
          - 123e4567-e89b-12d3-a456-426614174000
          - 987e6543-e21b-12d3-a456-426614174000
        billing_enabled:
          type: boolean
          default: false
          description: Whether to enable billing for this group
          example: false
        external_id:
          type: string
          minLength: 1
          description: '**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: acct_9e4c1b8d
    GroupWebsite:
      type: object
      description: A website associated with a group
      required:
      - id
      - websiteUrl
      - websiteName
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the website
          example: 123e4567-e89b-12d3-a456-426614174000
        websiteUrl:
          type: string
          description: The URL of the website
          example: example.com
        websiteName:
          type: string
          description: Display name of the website
          example: My Awesome Blog
        externalId:
          type: string
          nullable: true
          description: '**Partner-only.** The partner-supplied identifier mapped to this website. Only present on responses to callers whose organization is flagged as a partner. Direct-customer responses omit the field entirely. `null` indicates no mapping exists for this website.'
          example: ws_a7f3b2c9
    UpdateGroupRequest:
      type: object
      description: Request body for updating a group. At least one field must be provided.
      properties:
        name:
          type: string
          minLength: 1
          description: New name for the group.
          example: Renamed Group
        add_website_ids:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
          description: Website IDs to add to the group. Must belong to your organization. Websites already in the group are silently ignored.
          example:
          - 123e4567-e89b-12d3-a456-426614174000
        remove_website_ids:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
          description: Website IDs to remove from the group. IDs not currently in the group are silently ignored.
          example:
          - 987e6543-e21b-12d3-a456-426614174000
        external_id:
          type: string
          minLength: 1
          nullable: true
          description: '**Partner-only.** Partner-supplied identifier to attach to this group. Pass a non-empty string to set or replace the mapping, or `null` to clear an existing mapping. 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 — setting a value already used by another group returns `409` with the existing resource in the payload.'
          example: acct_9e4c1b8d
        billing_enabled:
          type: boolean
          description: Set to `true` to enable billing for this group. This provisions a billing entity in the upstream billing provider, which is a prerequisite for setting credits on the group (a partner-only operation). Idempotent — safe to call on groups whose entity was never created or whose initial provisioning failed silently. Set to `false` to disable the flag without destroying existing billing state; credit balances and usage history are preserved. Returns `502` if the upstream billing provider fails to provision the entity — in that case the database is not modified, so the request can be retried cleanly.
          example: true
    CreatedGroup:
      type: object
      description: A newly created group resource
      required:
      - id
      - name
      - orgId
      - billingEnabled
      - websiteIds
      - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the group
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Name of the group
          example: Enterprise Clients
        orgId:
          type: string
          format: uuid
          description: The organization ID the group belongs to
          example: 987e6543-e21b-12d3-a456-426614174000
        billingEnabled:
          type: boolean
          description: Whether billing is enabled for this group
          example: false
        websiteIds:
          type: array
          items:
            type: string
            format: uuid
          description: List of website IDs associated with this group
          example:
          - 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the group was created (UTC)
          example: '2024-06-15T10:30:00.000Z'
        externalId:
          type: string
          nullable: true
          description: '**Partner-only.** Echoes the `external_id` from the create request if provided, or `null` if the partner did not supply one. Only present on responses to partner API keys — direct-customer responses omit the field.'
          example: acct_9e4c1b8d
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api).