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

# Create a Domain Group

> Creates a named group. A stable groupId with the same name is idempotent when domains is omitted, preserving later attachments. An explicitly different name or domains payload returns 409. Domains must already belong to this partner.



## OpenAPI

````yaml POST /v1/partner/domain-groups
openapi: 3.0.3
info:
  title: Wildcard API
  description: >
    Programmatic access to your Wildcard data — identified website visitors,

    companies, events, and analytics.


    ## Authentication

    Visitor-data endpoints require an `mk_live_...` data key in `X-API-Key`.

    Partner management endpoints under `/v1/partner/*` require your
    `pk_live_...`

    management key instead. `/v1/health` is public and requires no key.


    ```bash

    curl -H "X-API-Key: mk_live_your_key_here"
    https://api-v1.maverickintelligence.co/v1/people

    ```


    ## Data API Rate Limiting

    - **1,000 requests per hour** per customer (shared across all API keys)

    - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

    - When exceeded, you'll receive a `429` response with a `Retry-After` header


    ## Pagination

    List endpoints use cursor-based pagination. Pass the `nextCursor` from the
    response

    as the `cursor` query parameter to fetch the next page.


    ## Sorting

    Visitor lists are sorted by most recently seen first (`lastSeen`
    descending).

    Traffic pages sort by observed human and AI page views, then domain and
    path.

    Custom sorting is not yet supported — passing a `sort` or `order` query

    parameter returns `400 bad_request`. Custom sorting options will be
    available

    in a future version.
  version: 1.1.0
  contact:
    name: Wildcard Support
    email: support@trywildcard.ai
    url: https://trywildcard.ai
servers:
  - url: https://api-v1.maverickintelligence.co
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Traffic
    description: >-
      Per-page human and AI traffic, including anonymous activity and server
      collection
  - name: System
    description: API health and status
  - name: People
    description: Identified website visitors
  - name: Events
    description: Behavioral events (page views, clicks, scrolls)
  - name: Companies
    description: Companies identified from visitors
  - name: Statistics
    description: Aggregate analytics
paths:
  /v1/partner/domain-groups:
    post:
      tags:
        - Partner Management
      summary: Create a domain group
      description: >-
        Creates a named group. A stable groupId with the same name is idempotent
        when domains is omitted, preserving later attachments. An explicitly
        different name or domains payload returns 409. Domains must already
        belong to this partner.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                groupId:
                  type: string
                  pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$
                  description: Optional stable identifier; generated when omitted.
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                domains:
                  type: array
                  maxItems: 1000
                  default: []
                  items:
                    type: string
            example:
              groupId: acme
              name: Acme
      responses:
        '200':
          description: Identical group already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainGroupResult'
        '201':
          description: Group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainGroupResult'
        '400':
          description: Invalid group details or domains not owned by this partner
        '403':
          description: Partner access or required billing setup unavailable
        '409':
          description: This groupId already exists with different details
      security:
        - PartnerKeyAuth: []
components:
  schemas:
    DomainGroupResult:
      type: object
      properties:
        success:
          type: boolean
        group:
          $ref: '#/components/schemas/DomainGroup'
    DomainGroup:
      type: object
      required:
        - groupId
        - name
        - domains
        - createdAt
        - updatedAt
      properties:
        groupId:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$
          example: acme
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: Acme
        domains:
          type: array
          description: >-
            Exact tracked hostnames owned by this partner; paused sites remain
            available for historical queries.
          items:
            type: string
          example:
            - acme-stories.example.com
            - acme-news.example.com
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'
    PartnerKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Partner management key (pk_live_...) from Partner Dashboard. Server-side
        use only; not a visitor-data key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.