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

# Ingest server-log AI-crawler hits

> Server-log ingestion for Agent Analytics. The customer's edge — a Cloudflare Worker, a generic CDN webhook, or a CSV log upload — forwards a batch of raw request records. Each User-Agent is classified with the same engine catalog the JS beacon uses and written to the same Agents dashboard, so server-side crawlers (GPTBot, ClaudeBot, etc.) that never execute JavaScript are captured. Paid plans only. The batch's site_id must belong to the authenticated account. Max 2000 records per batch; larger batches return 413.



## OpenAPI

````yaml /api-reference/public-openapi.json post /api/public/v1/agents/ingest
openapi: 3.1.0
info:
  title: FixAEO Customer API
  version: 2026.05.23
  description: >-
    Bearer-authed read API over your FixAEO workspace. Create a key in Settings,
    then send it as `Authorization: Bearer <key>`. Every route is scoped to the
    key's own account.


    Generated from the server's OpenAPI spec — see
    scripts/build-public-openapi.py.
servers:
  - url: https://api.fixaeo.com
security:
  - bearerAuth: []
paths:
  /api/public/v1/agents/ingest:
    post:
      tags:
        - Public API
        - Agents
      summary: Ingest server-log AI-crawler hits
      description: >-
        Server-log ingestion for Agent Analytics. The customer's edge — a
        Cloudflare Worker, a generic CDN webhook, or a CSV log upload — forwards
        a batch of raw request records. Each User-Agent is classified with the
        same engine catalog the JS beacon uses and written to the same Agents
        dashboard, so server-side crawlers (GPTBot, ClaudeBot, etc.) that never
        execute JavaScript are captured. Paid plans only. The batch's site_id
        must belong to the authenticated account. Max 2000 records per batch;
        larger batches return 413.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - site_id
                - records
              properties:
                site_id:
                  type: string
                  format: uuid
                  description: The site_id from the brand's Agents tab.
                channel:
                  type: string
                  enum:
                    - cf_worker
                    - webhook
                    - csv
                    - wp_plugin
                  default: cf_worker
                  description: Ingestion path. Unknown values coerce to cf_worker.
                records:
                  type: array
                  maxItems: 2000
                  items:
                    type: object
                    properties:
                      ua:
                        type: string
                        description: Request User-Agent (classification signal).
                      path:
                        type: string
                        description: Request path.
                      ref:
                        type: string
                        description: Request Referer
                        if any.: null
                      ip:
                        type: string
                        description: Client IP; hashed with the salt
                        never stored raw.: null
                      ts:
                        type: integer
                        format: int64
                        description: Unix millis when the hit occurred; 0/absent = now.
                      status:
                        type: integer
                        description: >-
                          HTTP status served (100–599; out-of-range/absent
                          stored as NULL). Powers the per-URL status column +
                          failure-rate KPI.
                      method:
                        type: string
                        description: >-
                          HTTP request method (GET/POST/…). Optional; absent
                          stored as NULL.
                      country:
                        type: string
                        description: >-
                          ISO-3166 alpha-2 country code from the edge. Optional;
                          must be 2 letters or it's dropped. Powers the
                          by_country breakdown.
      responses:
        '200':
          description: Batch accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: integer
                    description: Rows written this batch.
                  monthly_used:
                    type: integer
                    description: >-
                      Server-log events used by this account this calendar month
                      (incl. this batch).
                  monthly_cap:
                    type: integer
                    description: The account's monthly server-log event cap for its plan.
        '400':
          description: Missing site_id or records, or invalid JSON.
        '401':
          description: Missing or invalid API key.
        '403':
          description: >-
            Plan not entitled (server-log ingestion requires Growth or higher),
            or the site_id does not belong to this account.
        '404':
          description: Unknown site_id.
        '413':
          description: Batch exceeds 2000 records; split it.
        '429':
          description: Monthly server-log event cap reached for this account's plan.
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: fxa_
      description: |
        API keys generated via `POST /api/v1/me/api-keys`. Format:
        `Authorization: Bearer fxa_<32-char-secret>`. Only accepted on
        `/api/public/v1/*`. Cookie auth is rejected on that surface.

````