Skip to main content
Each operation page defines its exact input and output schema. The conventions here explain recurring fields. Use the operation’s schema for validation: a watch, candidate, job and event do not share one universal response envelope.

​
Inputs and identifiers

Send a JSON object using the documented field names and types. An optional field can be omitted; it accepts null only when its schema permits null. For supported expectation updates, null clears an expectation. Omission leaves that field outside the requested change. Keep returned identifiers exactly as received. Use projectId, watchId, runId, candidateId or jobId in the operation that asks for it. A localReference associates a hosted record with a customer-owned record. Join through that reference rather than relying on identical URL spelling after normalization. Reuse idempotencyKey only for retries of the same intended operation and arguments. Revision fields serve a different purpose: expectedRevision rejects stale concurrent updates, while a selected historical revision chooses immutable saved evidence.

​
Records and pagination

Treat cursors as opaque. Follow the operation’s continuation fields until its selected result set ends. Apply event pages before advancing the saved cursor. A cursor belongs to its feed and query; source and destination cursors cannot be exchanged.

​
Evidence and missing values

Observation states present, absent and unknown describe link evidence. Destination states healthy, unavailable and unknown describe target health. A job can succeed while its observation remains unknown. Lifecycle status, such as active or paused, describes the watch rather than its last fetch. Keep unknown and null values in reports. Missing supplier rows do not become zero links; missing search rows do not become zero impressions. Preserve the provider observation date, import/capture date and check date separately. Evidence semantics defines confirmed loss and retained snapshots.

​
Usage and batch results

Usage names the UTC period, unit totals and check reservations. Reserved, consumed and released totals describe different stages of work. Source and destination checks share allowance; discovery and overview counters describe separate work. A candidate verification batch has schema_version: 1, aggregate state and counts, per-item results and a reservation. Each item can have a nullable job, watch, observation, error and usage record. Read all items: a partial batch includes outcomes that need different next actions. The batch’s completed state alone does not establish link presence. Response contracts permit extension fields where documented so clients can retain new information. Validate known required fields without silently inventing defaults for absent evidence. See error conventions, concepts and sync recovery before building a consumer. The local context result reference describes the separate stdio result envelope and per-tool records.