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

# Liveness probe with codec build identifier

> Returns the service liveness status and the current codec build
identifier. The build identifier matches the `X-JDC-Codec-Version`
header on every snapshot response, so monitoring tools can detect
deploys by polling this endpoint.

No PII, no per-customer state, no auth required. Safe to poll at
high frequency from third-party uptime monitors (Pingdom,
UptimeRobot, etc.).




## OpenAPI

````yaml /openapi.yaml get /v1/health
openapi: 3.1.0
info:
  title: JD Codec Cloud API
  version: 1.0.0
  summary: Per-snapshot compression API for browser-agent perception streams.
  description: |
    JD Codec is a stateful, lossy perception codec for browser-based AI agents.
    The local connector sends already-redacted DOM/ARIA snapshots to this API
    and receives compressed output — a full keyframe on the first or forced-
    refresh step, and smaller deltas on subsequent steps — that the connector
    splices into its agent's tool response in place of the original snapshot.

    Three wire types cross the connector ↔ cloud boundary:

    - `SnapshotRequest` — one snapshot per request.
    - `SnapshotResponse` — the codec-emitted compressed output (or a
      pass-through signal indicating the connector should reuse the snapshot
      it sent).
    - `ErrorResponse` — uniform shape for every non-2xx response.

    A `UsageEvent` is also emitted server-side per successful snapshot. It is
    persisted to JDC's metering store and is not returned in the response
    body. Customers who want to consume their own usage data should query
    the dashboard at https://jdcodec.com (forthcoming customer dashboard).

    ### Privacy posture

    The connector runs an on-device Privacy Shield over every snapshot before
    it is sent. The cloud refuses any request that does not carry the
    `client_redacted: true` audit signal. Redacted values never reach the
    cloud; only category-level counts (e.g. `{ email: 2, CC_GENERIC: 1 }`)
    flow through to operators for observability.

    ### Sessions and tasks

    A **session** is the technical container for codec state. A **task** is
    a user-meaningful unit of work that fully fits inside one session. Steps
    are 0-indexed snapshots within a session and must increase monotonically.

    Sessions expire after 30 minutes of inactivity (idle TTL) and 4 hours
    absolute, whichever fires first. Per-key overrides are available — talk
    to support if your workload needs a different envelope.
  contact:
    name: JD Codec
    email: hello@jdcodec.com
    url: https://jdcodec.com
  license:
    name: Proprietary
    url: https://jdcodec.com/terms
servers:
  - url: https://api.jdcodec.com
    description: Production
  - url: https://api-staging.jdcodec.com
    description: Staging
security:
  - bearerAuth: []
tags:
  - name: Snapshot
    description: |
      Submit one snapshot, receive the codec-emitted compressed output (or a
      pass-through flag).
  - name: Telemetry
    description: |
      Submit connector-side latency measurements. Observability-only —
      never billable. The codec service is the sole writer to the
      backing telemetry store; the connector does not hold database
      credentials.
  - name: Health
    description: Liveness probes.
paths:
  /v1/health:
    get:
      tags:
        - Health
      summary: Liveness probe with codec build identifier
      description: |
        Returns the service liveness status and the current codec build
        identifier. The build identifier matches the `X-JDC-Codec-Version`
        header on every snapshot response, so monitoring tools can detect
        deploys by polling this endpoint.

        No PII, no per-customer state, no auth required. Safe to poll at
        high frequency from third-party uptime monitors (Pingdom,
        UptimeRobot, etc.).
      operationId: getV1Health
      responses:
        '200':
          description: Service is healthy.
          headers:
            X-JDC-Codec-Version:
              $ref: '#/components/headers/XJdcCodecVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                ok:
                  value:
                    status: ok
                    codec_version: 2026.05.01+a1b2c3d
      security: []
components:
  headers:
    XJdcCodecVersion:
      description: |
        Codec build identifier. Format `YYYY.MM.DD+<short-sha>`. Matches the
        `codec_version` field in the corresponding `UsageEvent`.
      schema:
        type: string
        example: 2026.05.01+a1b2c3d
  schemas:
    HealthResponse:
      type: object
      required:
        - status
        - codec_version
      properties:
        status:
          type: string
          enum:
            - ok
        codec_version:
          type: string
          description: |
            Server codec build. Format `YYYY.MM.DD+<short-sha>`.
          example: 2026.05.01+a1b2c3d
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <api_key_id>.<api_key_secret>
      description: |
        API key in two parts separated by a dot, sent as a single bearer:

        - `api_key_id` — public, stable, `jdck_`-prefixed lookup handle.
          Safe to log and reference in support conversations.
        - `api_key_secret` — opaque high-entropy string. Shown to the
          customer once at issuance and never again. Server stores only
          its hash.

        Example:

            Authorization: Bearer jdck_9f3a2b7c8d1e4f05.BASE32URL_SECRET

````