GET /head: Retrieve Latest Replication Head Metadata

The GET /head endpoint returns the single most recent confirmed entry in your agent’s replication log: its sequence number, Merkle root, and last-updated timestamp. It is a single indexed-column lookup, designed for fast polling — ideal as a pre-flight check before a replay, as a sync-status heartbeat, or to verify that a just-submitted chunk was accepted as the new head.

Request

GET /head
Authorization: Bearer <TOKEN>

This endpoint takes no query parameters. The agent is identified entirely from the bearer token.

Response

200 OK

integer

Sequence number of the latest confirmed replication entry for this agent.

string

SHA-256 Merkle root recorded at the time the latest chunk was written.

string

ISO-8601 timestamp of when the current head was last updated.

Example Response

{
  "sequence_number": 10,
  "merkle_root": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c",
  "updated_at": "2026-06-09T16:45:30.123Z"
}

Errors

string

no_replication_entries — returned with HTTP 404 when the authenticated agent has not pushed any replication chunks yet. This is expected for freshly initialized agents that have not called POST /replicate.

curl Example

curl -G https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/head \
  -H "Authorization: Bearer sov_live_YOUR_KEY"

Get Started

Platform

Agent Plugins

Self-Hosted

Integrations

Cookbooks

API Reference

Release Notes

GET /head: Retrieve Latest Replication Head Metadata

Request

Response

200 OK

Example Response

Errors

curl Example

​Request

​Response

​200 OK

​Example Response

​Errors

​curl Example

Request

Response

200 OK

Example Response

Errors

curl Example