Convalytics Ingest API

openapi: 3.2.0
info:
  title: Convalytics Dev Ingest API
  version: 1.0.0
  contact:
    url: https://convalytics.dev
  license:
    name: MIT
    url: https://github.com/Dan-Cleary/convalytics/blob/main/LICENSE.txt
  description: 'Operations tagged Ingest across 2 of this provider''s published API definitions: convalytics-dev-openapi.json, convalytics-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.convalytics.dev
  description: Production
tags:
- name: Ingest
  description: Send events and page views
paths:
  /ingest:
    post:
      tags:
      - Ingest
      operationId: ingestEvent
      summary: Ingest a single event or page view
      description: 'Writes one event to the project identified by writeKey. Use event name `page_view` to record a page view (free, not counted against quota); any other name records a custom product event (counts against the monthly quota). Rate limit: 1000 events/min per write key.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestEvent'
      responses:
        '200':
          description: Accepted. Response body is empty.
        '400':
          description: Invalid JSON or missing required fields.
        '401':
          description: Invalid write key.
        '402':
          description: Monthly event quota exceeded (server-side events only; browser events are silently dropped over quota).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaError'
        '429':
          description: Rate limit exceeded (1000 events/min per write key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the rate limit resets.
    servers:
    - url: https://api.convalytics.dev
      description: Production
  /ingest/batch:
    post:
      tags:
      - Ingest
      operationId: ingestBatch
      summary: Ingest up to 100 events in one request
      description: Batch ingest for high-volume tracking. Write key is validated once for the whole batch; per-event results are returned in the same order as the input. Rate limit consumes event-count slots atomically.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - writeKey
              - events
              properties:
                writeKey:
                  type: string
                events:
                  type: array
                  minItems: 0
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/IngestEvent'
      responses:
        '200':
          description: Batch processed. `accepted` and `rejected` counts plus per-event results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResult'
        '400':
          description: Invalid JSON, missing writeKey, events not an array, or batch exceeds 100.
        '401':
          description: Invalid write key.
        '402':
          description: Monthly event quota exceeded. Free page views in the batch are still ingested.
        '429':
          description: Rate limit exceeded for the full batch count.
    servers:
    - url: https://api.convalytics.dev
      description: Production
components:
  schemas:
    RateLimitError:
      type: object
      required:
      - error
      - message
      - retryAfter
      - resetAt
      properties:
        error:
          type: string
          const: rate_limit_exceeded
        message:
          type: string
        retryAfter:
          type: integer
          description: Seconds until reset.
        resetAt:
          type: integer
          description: Unix milliseconds when the window resets.
    QuotaError:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          const: quota_exceeded
        message:
          type: string
        plan:
          type: string
        limit:
          type: integer
    BatchResult:
      type: object
      required:
      - accepted
      - rejected
      - results
      properties:
        accepted:
          type: integer
        rejected:
          type: integer
        results:
          type: array
          items:
            oneOf:
            - type: object
              required:
              - status
              properties:
                status:
                  type: string
                  const: ok
            - type: object
              required:
              - status
              - error
              properties:
                status:
                  type: string
                  const: error
                error:
                  type: string
    IngestEvent:
      type: object
      required:
      - writeKey
      - name
      - userId
      - sessionId
      - timestamp
      properties:
        writeKey:
          type: string
          description: Public write key identifying the project.
        name:
          type: string
          description: Event name. Use `page_view` for page views (free, not quota-counted); any other snake_case name records a custom product event.
        userId:
          type: string
          description: Stable user ID (anonymous UUID or your app's real user ID after identify()).
        sessionId:
          type: string
          description: Session ID (regenerated per browser session).
        timestamp:
          type: integer
          description: Unix milliseconds.
        props:
          type: object
          description: Arbitrary event properties. Values must be string, number, or boolean. Keys starting with $ or _ are dropped.
          additionalProperties:
            oneOf:
            - type: string
            - type: number
            - type: boolean
        deploymentName:
          type: string
          description: Convex deployment slug. When present, environment is resolved via cached deployment metadata (dev → development, prod → production).
        pageOrigin:
          type: string
          description: Page origin for browser events. Used to classify environment (localhost → development, else production).
        userEmail:
          type: string
          description: Human-readable email shown in the dashboard (takes priority over userName and userId).
          maxLength: 200
        userName:
          type: string
          description: Human-readable name shown in the dashboard (fallback after userEmail).
          maxLength: 200
x-refined-from:
- convalytics-dev-openapi.json
- convalytics-dev-openapi.yml