> ## 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.

# Send Server Page Events

> Report page requests your server saw, so AI crawlers that don't run JavaScript are counted

Call this from your server only, never from the browser: it uses a secret
`mk_live_` key. See [Collect AI requests from the server](https://docs.trywildcard.ai/partners.md#collect-ai-requests-from-the-server).


## OpenAPI

````yaml POST /v1/traffic/events
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/traffic/events:
    post:
      tags:
        - Traffic
      summary: Collect server-observed page requests or HTML responses
      description: >
        Server-to-server collection using a secret mk_live_ data key. Send only

        page GET requests or successful HTML responses, excluding assets, API

        requests and prefetches. Request observations omit response status and

        content type and count toward ai.requests, not confirmed ai.pageViews.

        Registered active sites and exact key scope are enforced.

        Retries reuse the same eventId, timestamp and payload; the ID/timestamp

        pair is the idempotency key. A partially written batch can be retried.

        Records analytics only; no enrichment, provider or delivery side
        effects.

        Batch up to 100 events within 250KB. Existing API rate limits apply.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - events
              properties:
                events:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/ServerTrafficEvent'
      responses:
        '202':
          description: Observations accepted or recognized as duplicate retries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      accepted:
                        type: integer
                      duplicates:
                        type: integer
        '400':
          description: Invalid event or batch
        '401':
          description: Invalid data key or account unavailable
        '403':
          description: Site not registered, active, permitted or in key scope
        '409':
          description: Reused eventId/timestamp with different event data
        '429':
          description: Data API rate limit reached; honor Retry-After
        '503':
          description: Deletion protection unavailable; retry
components:
  schemas:
    ServerTrafficEvent:
      type: object
      additionalProperties: false
      required:
        - eventId
        - timestamp
        - url
        - userAgent
        - method
      properties:
        eventId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Stable request ID; reuse with the same timestamp and payload on
            retry
        timestamp:
          type: string
          format: date-time
          description: Original observation time; at most 7 days old or 5 minutes ahead
        url:
          type: string
          format: uri
          maxLength: 4096
          description: Absolute HTTP(S) page URL; query and fragment are discarded
        userAgent:
          type: string
          minLength: 1
          maxLength: 1024
          description: Original request User-Agent, used for claimed agent classification
        method:
          type: string
          enum:
            - GET
        observationType:
          type: string
          enum:
            - request
            - response
          default: response
          description: >-
            Use request for pre-response hooks; do not send both for the same
            request
        statusCode:
          type: integer
          minimum: 200
          maximum: 299
          description: Required for response; must be omitted for request
        contentType:
          type: string
          description: >-
            Required for response; actual text/html or application/xhtml+xml,
            optionally with charset. Must be omitted for request
        visitorId:
          type: string
          minLength: 1
          maxLength: 128
          description: Optional opaque first-party ID; never send email or IP
        sessionId:
          type: string
          minLength: 1
          maxLength: 128
          description: Optional opaque first-party session ID
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'

````

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