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).
Authorizations
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
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.
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.
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.
x >= 0Connector 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.
0 <= x <= 600000Connector-measured Privacy Shield CPU work.
0 <= x <= 600000Connector-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.
0 <= x <= 600000Time 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.
0 <= x <= 600000Version string of the connector emitting telemetry (e.g.
"[email protected]"). Useful for tracking per-release
performance regressions.
64Response
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."