openapi: 3.1.0
info:
  title: Compresr Platform Admin 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.\n\n    Call once before sending telemetry (optional — the first batch auto-\n    registers). The secret is encrypted at rest. `cmp_` API keys are rejected;\n    mint an `opm_` credential in the dashboard under Settings -> On-Prem.\n\n    **Required Headers:**\n    - `X-API-Key`: Your Compresr API key\n\n    **Body:**\n    - `signing_secret`: On-prem signing secret (`opm_xxx`)\n    - `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'
        '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.\n    \n    **Required Headers:**\n    - `X-API-Key`: Compresr API key (authentication)\n    - `X-Compresr-Signature`: HMAC signature (integrity)\n    \n    **Optional Headers:**\n    - `X-Instance-ID`: On-prem instance identifier\n    \n    **First Request (auto-registration):**\n    Include `signing_secret` (`opm_xxx`) in the body - it will be registered\n    automatically. `cmp_` API keys are rejected; mint an `opm_` credential\n    in the dashboard under Settings -> On-Prem first.\n\n    **Signature Format:**\n    ```\n    t=timestamp,v1=HMAC-SHA256(timestamp + \".\" + JSON(payload), signing_secret)\n    ```\n    \n    **Event Types:**\n    - `compression`: Counted for billing\n    - `error`: Logged only\n    - `startup`/`shutdown`: Operational\n    \n    **Idempotency:**\n    Same batch_id within 24h returns success without reprocessing."
      operationId: ingest_telemetry_batch_api_v1_telemetry_batch_post
      security:
      - HTTPBearer: []
      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'
        '409':
          description: Duplicate batch (idempotency)
          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/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:
    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
    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
    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
      type: object
      required:
      - success
      - batch_id
      - events_received
      - events_stored
      title: TelemetryBatchResponse
    RegisterSigningSecretRequest:
      properties:
        signing_secret:
          type: string
          title: Signing Secret
          description: On-prem signing secret (opm_xxx). Mint via dashboard -> Settings -> On-Prem. 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
    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
    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
    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.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer