curl --request POST \ --url https://api.jdcodec.com/v1/telemetry \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "session_id": "9c1b2f6e-0b8e-4a77-9cfd-3e3f7b5e8d21", "step": 3, "client_round_trip_ms": 47.3, "redaction_ms": 0.4, "cloud_ms": 34.8, "upstream_ms": 12.1, "connector_version": "[email protected]" } '

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Telemetry

Submit connector-side latency measurements

Submit connector-measured timings (Node hrtime.bigint(), sub-millisecond resolution) for a snapshot the connector has already received a /v1/snapshot response for. The codec service validates the bearer token, sanity-checks values, and writes them to its telemetry store. Connector NEVER writes to the store directly — trust boundary preserved.

Telemetry is observability-only and never billable. Billing derives from server-authoritative facts in usage_events, which are never affected by this endpoint.

The request is fire-and-forget from the connector’s perspective. Failure to deliver telemetry should not be retried and never affects the connector’s response to its agent. If the connector is offline or the service is degraded, telemetry is dropped (best-effort, no buffering).

See SPEC.md for the underlying telemetry table shape and the canonical display rule (NULL = not recorded; 0 = <1 ms; ≥1 = numeric ms).

POST

telemetry

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "message": "<string>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Connector-supplied latency measurements for a single snapshot. All timing fields are optional — the connector sends what it measured and omits what it didn't. The display rule applies uniformly across consumers: NULL (omitted) = "not recorded"; 0 = "<1 ms" (rare on the connector side since Node hrtime.bigint() has nanosecond resolution, but the rule is uniform across all timing fields for consistency); ≥1 = numeric ms.

Three components are designed to be additive: client_round_trip_ms ≈ redaction_ms + cloud_ms + upstream_ms. The residual surfaces in queries as a data-quality signal (untracked overhead) — not enforced as a CHECK constraint.

See SPEC.md (telemetry section) for the storage schema and full rationale.

session_id

string<uuid>

required

Same session_id the connector used in the corresponding POST /v1/snapshot call. Must be owned by the bearer token. Joins to usage_events for billing/identity context.

step

integer

required

0-indexed step within the session. The pair (session_id, step) is the join key to usage_events and uniquely identifies a snapshot. Retried POSTs for the same pair are safe — the underlying table has UNIQUE constraint with first-write-wins semantics.

Required range: x >= 0

client_round_trip_ms

number

Connector wall-clock from receiving the agent's tool call to returning the result. The customer-experienced wall-clock; the headline "JDC time" number for benchmarking and unit-economics.

Required range: 0 <= x <= 600000

redaction_ms

number

Connector-measured Privacy Shield CPU work.

Required range: 0 <= x <= 600000

cloud_ms

number

Connector-measured POST /v1/snapshot round-trip wall-clock — includes network RTT to/from the codec service, server-side processing including codec compute, and response transmit.

Required range: 0 <= x <= 600000

upstream_ms

number

Time spent calling the upstream MCP server (Playwright MCP in M1; additional framework adapters in future milestones). The connector populates this from the M1 implementation's measurement.

Required range: 0 <= x <= 600000

connector_version

string

Version string of the connector emitting telemetry (e.g. "[email protected]"). Useful for tracking per-release performance regressions.

Maximum string length: 64

Response

Telemetry accepted and queued for write. No body. Note that the codec service may still drop the row server-side under sampling rules; success here means "received and validated," not "definitely persisted."

Submit one snapshot for compression Liveness probe with codec build identifier

Snapshot

Telemetry

Health

Submit connector-side latency measurements

Authorizations

Body

Response