> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Group > 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). ## OpenAPI ````yaml /api-reference/openapi.json patch /api/v1/groups/{group_id} openapi: 3.1.0 info: title: AthenaHQ 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: Basics description: Core API operations for managing websites and prompts - name: Metrics description: Metrics and analytics endpoints for tracking AI visibility - name: Billing description: Billing and credits endpoints for managing usage - name: Team Management description: Endpoints for managing team members and invitations - name: Groups description: Endpoints for managing groups of websites - name: Content description: >- Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL prompt breakdowns. - name: Pitch Workspace description: >- Endpoints for accessing pitch workspace reports — org-scoped pitch runs with competitors, prompts, attributes, and aggregate metrics. - name: Knowledge Base description: >- Endpoints for reading the brand Knowledge Base — approved brand facts and the pillars that organize them. paths: /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 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 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 security: - apiKey: [] components: schemas: 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 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 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 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 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). ````