Compresr On-Prem Telemetry API

openapi: 3.2.0
info:
  title: Compresr Platform On-Prem Telemetry API
  version: 1.0.0
tags:
- name: On-Prem Telemetry
paths:
  /api/v1/telemetry/register:
    post:
      tags:
      - On-Prem Telemetry
      summary: Register signing secret for HMAC verification
      description: 'Register an on-prem signing secret (`opm_xxx`) for HMAC verification.


        Call once before sending telemetry (optional — the first batch auto-

        registers). The secret is encrypted at rest. `cmp_` API keys are rejected:

        the on-prem image generates its own `opm_` credential on start, so upgrade

        the image rather than supplying one by hand.


        **Required Headers:**

        - `X-API-Key`: Your Compresr API key


        **Body:**

        - `signing_secret`: On-prem signing secret (`opm_xxx`)

        - `instance_id`: Optional instance identifier'
      operationId: register_signing_secret_api_v1_telemetry_register_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterSigningSecretRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterSigningSecretResponse'
        '409':
          description: Secret already registered to a different account. Retrying cannot clear this; generate a new secret for this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/telemetry/batch:
    post:
      tags:
      - On-Prem Telemetry
      summary: Ingest telemetry batch from on-prem instance
      description: 'Receive and store a batch of telemetry events from an on-prem Compresr instance.


        **Required Headers:**

        - `X-API-Key`: Compresr API key (authentication)

        - `X-Compresr-Signature`: HMAC signature (integrity)


        **Optional Headers:**

        - `X-Instance-ID`: On-prem instance identifier


        **First Request (auto-registration):**

        Include `signing_secret` (`opm_xxx`) in the body - it will be registered

        automatically. The on-prem image generates this credential itself; `cmp_`

        API keys are rejected.


        **Signature Format:**

        ```

        t=timestamp,v1=HMAC-SHA256(timestamp + "." + JSON(payload), signing_secret)

        ```


        **Event Types:**

        - `compression`: Counted for billing

        - `error`: Logged only

        - `startup`/`shutdown`: Operational


        **Idempotency:**

        Same batch_id within 24h returns success without reprocessing. A batch

        with failed events stays replayable: retry it and already-billed events

        are returned as status "duplicate" (never billed twice).'
      operationId: ingest_telemetry_batch_api_v1_telemetry_batch_post
      parameters:
      - name: x-instance-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: On-prem instance ID
          title: X-Instance-Id
        description: On-prem instance ID
      - name: x-compresr-signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: HMAC signature
          title: X-Compresr-Signature
        description: HMAC signature
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryBatchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryBatchResponse'
        '401':
          description: Invalid API key or signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryErrorResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/telemetry/health:
    get:
      tags:
      - On-Prem Telemetry
      summary: Telemetry endpoint health check
      description: Simple health check for telemetry ingestion endpoint.
      operationId: telemetry_health_api_v1_telemetry_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Telemetry Health Api V1 Telemetry Health Get
components:
  schemas:
    TelemetryEventResult:
      properties:
        event_id:
          type: string
          title: Event Id
          description: Echo of the on-prem event ID
        status:
          type: string
          enum:
          - billed
          - recorded_unbilled
          - failed
          - duplicate
          title: Status
          description: 'Billing outcome: billed | recorded_unbilled | failed | duplicate'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Reason code when status is not 'billed'
      type: object
      required:
      - event_id
      - status
      title: TelemetryEventResult
      description: "Per-event billing outcome, echoed back to the on-prem appliance.\n\n- ``billed``: cost was charged through the standard billing pipeline\n  (prepaid wallet deduction or postpaid enterprise accumulation).\n- ``recorded_unbilled``: usage was recorded but not charged; ``reason``\n  carries the code (e.g. INSUFFICIENT_CREDITS,\n  ENTERPRISE_CREDIT_LIMIT_EXCEEDED, DEMO_SCOPE).\n- ``failed``: the event was not recorded (e.g. EVENT_HMAC_INVALID,\n  RECORDING_FAILED, INTERNAL_ERROR).\n- ``duplicate``: the event was already billed by an earlier delivery of\n  this batch (replay) and was skipped — not billed and not re-recorded."
    TelemetryEvent:
      properties:
        event_id:
          type: string
          title: Event Id
          description: Unique event ID (UUID)
        timestamp:
          type: string
          title: Timestamp
          description: Event timestamp (ISO8601)
        event_type:
          type: string
          title: Event Type
          description: Event type (compression, error, startup, shutdown)
        model_name:
          type: string
          title: Model Name
          description: Compression model used
        original_tokens:
          type: integer
          maximum: 1000000.0
          minimum: 0.0
          title: Original Tokens
          description: Original token count
          default: 0
        compressed_tokens:
          type: integer
          maximum: 1000000.0
          minimum: 0.0
          title: Compressed Tokens
          description: Compressed token count
          default: 0
        tokens_saved:
          type: integer
          maximum: 1000000.0
          minimum: 0.0
          title: Tokens Saved
          description: Tokens saved (original - compressed)
          default: 0
        duration_ms:
          type: integer
          maximum: 3600000.0
          minimum: 0.0
          title: Duration Ms
          description: Processing duration in milliseconds (max 1h)
          default: 0
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Additional metadata (max 10KB, 50 keys, 3 levels deep)
        event_hmac:
          anyOf:
          - type: string
            pattern: ^[a-f0-9]{64}$
          - type: 'null'
          title: Event Hmac
          description: Per-event HMAC-SHA256(api_key, canonical_event_bytes) computed by on-prem at insert time. Optional — older on-prem builds don't send it. The platform rejects events whose tag doesn't verify.
      additionalProperties: true
      type: object
      required:
      - event_id
      - timestamp
      - event_type
      - model_name
      title: TelemetryEvent
      description: 'Single telemetry event from on-prem instance.


        The optional ``event_hmac`` field is the per-event integrity tag computed

        by the on-prem instance at insert time using HMAC-SHA256(api_key, canonical_event_bytes).

        Older on-prem builds (< 1.1.0) don''t send it; newer builds always do. The

        platform verifies it server-side and rejects events with a bad tag —

        closing the in-flight SQLite tamper window.'
    IdentityManifest:
      properties:
        instance_id:
          type: string
          title: Instance Id
          description: UUID matching /data/identity.json
        api_key_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
          title: Api Key Hash
          description: SHA-256 hex of the api_key the on-prem instance was first bound to
        created_at:
          type: string
          title: Created At
          description: ISO-8601 timestamp manifest was created
      additionalProperties: true
      type: object
      required:
      - instance_id
      - api_key_hash
      - created_at
      title: IdentityManifest
      description: 'On-prem identity manifest, sent in each upload for rebirth detection.


        The on-prem instance persists this manifest in ``/data/identity.json``

        HMAC-bound to the api_key on first authenticated request. Subsequent

        uploads carry the same values. If we see a *new* ``instance_id`` or an

        earlier ``created_at`` for the same api_key, it signals that the operator

        deleted the local manifest — typically an attempt to reset a per-instance

        grace period or quota.'
    RegisterSigningSecretResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
      type: object
      required:
      - success
      - message
      title: RegisterSigningSecretResponse
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: false
        error:
          type: string
          title: Error
        code:
          type: string
          title: Code
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
        retry_after:
          anyOf:
          - type: integer
          - type: 'null'
          title: Retry After
        field:
          anyOf:
          - type: string
          - type: 'null'
          title: Field
      type: object
      required:
      - error
      - code
      title: ErrorResponse
    RegisterSigningSecretRequest:
      properties:
        signing_secret:
          type: string
          title: Signing Secret
          description: On-prem signing secret (opm_xxx), generated by the on-prem image and sent automatically. cmp_ API keys are rejected.
        instance_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance Id
          description: Instance identifier
      type: object
      required:
      - signing_secret
      title: RegisterSigningSecretRequest
    TelemetryBatchResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether batch was accepted
        batch_id:
          type: string
          title: Batch Id
          description: Echo of batch ID
        events_received:
          type: integer
          title: Events Received
          description: Number of events received
        events_stored:
          type: integer
          title: Events Stored
          description: Number of events stored
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Additional message
        events_rejected:
          type: integer
          title: Events Rejected
          description: Events outside the reporting window; will never be billed
          default: 0
        rejected_reasons:
          additionalProperties:
            type: integer
          type: object
          title: Rejected Reasons
          description: Rejection reason -> count
        signing_secret_registered:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Signing Secret Registered
          description: Whether the signing_secret in this request is now stored. Cache 'registered' only on an explicit true - null also means an older server that predates this field, so treating null as success is the very bug this field exists to fix. Anything else means keep sending the secret on subsequent batches, because the server has nothing to verify future uploads against and they will 401.
        signing_secret_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Signing Secret Error
          description: 'Machine-readable reason registration did not happen. ''hash_owned_by_other_account'': this deployment is using a signing secret belonging to a different account - usually a cloned data volume - and only an operator can clear it, so do not retry on it. ''not_attempted_duplicate_batch'': idempotent replay, the next batch will register. ''registration_failed'': transient, retry.'
        events_billed:
          type: integer
          title: Events Billed
          description: Compression events charged through the billing pipeline
          default: 0
        events_unbilled:
          type: integer
          title: Events Unbilled
          description: Compression events recorded but not charged
          default: 0
        events_duplicate:
          type: integer
          title: Events Duplicate
          description: Compression events skipped because an earlier delivery of this batch already billed them (replay protection)
          default: 0
        events_failed:
          type: integer
          title: Events Failed
          description: Compression events that were not recorded; the batch is left replayable so a retry reprocesses exactly these events
          default: 0
        event_results:
          anyOf:
          - items:
              $ref: '#/components/schemas/TelemetryEventResult'
            type: array
          - type: 'null'
          title: Event Results
          description: Per-event billing outcomes for compression events
      type: object
      required:
      - success
      - batch_id
      - events_received
      - events_stored
      title: TelemetryBatchResponse
    TelemetryBatchRequest:
      properties:
        batch_id:
          type: string
          title: Batch Id
          description: Unique batch ID (UUID)
        instance_id:
          type: string
          title: Instance Id
          description: On-prem instance ID (UUID)
        events:
          items:
            $ref: '#/components/schemas/TelemetryEvent'
          type: array
          maxItems: 100
          minItems: 1
          title: Events
          description: List of telemetry events (max 100 per batch)
        identity:
          anyOf:
          - $ref: '#/components/schemas/IdentityManifest'
          - type: 'null'
          description: Signed on-prem identity manifest. Optional — older on-prem builds (< 1.1.0) don't send it. When present, the platform logs identity changes (instance_id or created_at moving) for audit. Future versions will block on mismatch.
        signing_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Signing Secret
          description: Signing secret for HMAC verification (include on first request only)
      additionalProperties: true
      type: object
      required:
      - batch_id
      - instance_id
      - events
      title: TelemetryBatchRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    TelemetryErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for errors
          default: false
        error:
          type: string
          title: Error
          description: Error message
        error_code:
          type: string
          title: Error Code
          description: Error code for debugging
      type: object
      required:
      - error
      - error_code
      title: TelemetryErrorResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Compresr
  source: https://api.compresr.ai/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)