Skip to content
Zerker Gateway

Record a metadata-only agent event

POST
/v1/agent-events
curl --request POST \
  --url https://example.com/v1/agent-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "schema": "zerker.agent-event.v1", "event_id": "example", "agent_id": "example", "type": "session.started", "session_ref": "example", "occurred_at": "2026-04-15T12:00:00Z", "tool_name": "example", "outcome": "succeeded", "duration_ms": 1, "provider": "example", "model": "example", "input_tokens": 1, "output_tokens": 1, "cache_read_tokens": 1, "cache_write_tokens": 1, "cost_usd": 1, "source": "example", "source_version": "example" }'

Records lifecycle, tool outcome, or model usage metadata. Unknown fields are rejected. The contract has no prompt, tool argument, tool output, command-line, or file-path fields. Reusing event_id is idempotent.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
schema
required
string
Allowed values: zerker.agent-event.v1
event_id
required
string
<= 128 characters
agent_id
required
string
<= 128 characters
type
required
string
Allowed values: session.started session.ended tool.completed model.usage
session_ref
required
string
/^sha256:[0-9a-f]{64}$/
occurred_at
required
string format: date-time
tool_name
string
<= 128 characters
outcome
string
Allowed values: succeeded failed cancelled
duration_ms
integer format: int64
provider
string
<= 128 characters
model
string
<= 256 characters
input_tokens
integer format: int64
output_tokens
integer format: int64
cache_read_tokens
integer format: int64
cache_write_tokens
integer format: int64
cost_usd
number format: double
source
required
string
<= 64 characters
source_version
required
string
<= 64 characters

Responses

Section titled “Responses”

200

Section titled “200”

The event was already recorded.

Media typeapplication/json
object
recorded
required
boolean
duplicate
required
boolean
Examplegenerated
{
  "recorded": true,
  "duplicate": true
}

201

Section titled “201”

Event recorded.

Media typeapplication/json
object
recorded
required
boolean
duplicate
required
boolean
Examplegenerated
{
  "recorded": true,
  "duplicate": true
}

400

Section titled “400”

Invalid event or a field outside the privacy-bounded contract.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

401

Section titled “401”

Missing or invalid bearer token, or the token’s tenant/user claims are absent. No body.

404

Section titled “404”

No resource with this ID exists in the caller’s tenant.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

500

Section titled “500”

An unexpected server-side error. No body (internal detail is never returned to callers, invariant