CLI ingest API

Routes callable with an organization secret from the Relay CLI.

dev · https://api.dev.relay.oprag.ai

These 8 routes power relay install, relay sync, and session capture. Send X-Relay-Secret or Authorization: Bearer sk_live_….

Ingest routes by resource
Endpoint	Credential	What it does
`GET /health`	Public	Liveness probe for the Relay API.
`GET /config`	Public	Cognito pool/client IDs and API URL for the Architect SPA bootstrap.
`POST /v1/environments`	Org secret	Register or update a developer machine environment from the CLI.
`POST /v1/environments/{environmentId}/heartbeat`	Org secret	Refresh last-seen timestamp for a registered environment.
`POST /v1/environments/{environmentId}/agents`	Org secret	Register or upsert an agent installation from the CLI.
`POST /v1/sessions`	Org secret	Open a new agent session for event capture.
`POST /v1/sessions/{sessionId}/events`	Org secret	Append one or more session events (CLI hooks and sync). Each event's `payload` is optional and defaults to `{}`.
`POST /v1/sessions/{sessionId}/complete`	Org secret	Mark a session completed or failed.

GET /health

Liveness probe for the Relay API.

Auth Public — no credential

Path parameters

None.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

None.This endpoint does not read a request body.

Response

200 Success

JSON

{
  "status": "ok",
  "version": "0.1.0",
  "service": "relay-api"
}

Status codes

Status	Meaning
200	Success.
429	Rate limited. See rate limits.
503	Service unavailable.

curl

Shell

curl -X GET 'https://api.dev.relay.oprag.ai/health' \
  -H 'Authorization: Bearer sk_live_...'

GET /config

Cognito pool/client IDs and API URL for the Architect SPA bootstrap.

Auth Public — no credential

Path parameters

None.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

None.This endpoint does not read a request body.

Response

200 Success

JSON

{
  "cognitoUserPoolId": "us-east-1_example",
  "cognitoClientId": "exampleclientid",
  "apiUrl": "https://api.dev.relay.oprag.ai",
  "cognitoRegion": "us-east-1",
  "cognitoDomain": "ashutech-dev-relay"
}

Status codes

Status	Meaning
200	Success.
429	Rate limited. See rate limits.
503	Service unavailable.

curl

Shell

curl -X GET 'https://api.dev.relay.oprag.ai/config' \
  -H 'Authorization: Bearer sk_live_...'

POST /v1/environments

Auth Org secret

Path parameters

None.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

Name	Type	Required	Description
`displayName`	`string`	Optional	Friendly name for the environment.
`hostname`	`string`	Required	Machine hostname reported by the CLI.
`platform`	`"darwin" \| "linux" \| "win32"`	Required	OS platform: `darwin`, `linux`, or `win32`.
`repoRoot`	`string`	Optional	Absolute path to the repository root on the machine.
`repoRemote`	`string`	Optional	Git remote URL, when known.
`gitBranch`	`string`	Optional	Active git branch during capture.
`relayCliVersion`	`string`	Required	Relay CLI semver string.

Request

JSON

{
  "hostname": "ash-laptop.local",
  "platform": "darwin",
  "relayCliVersion": "0.1.0",
  "displayName": "Ash laptop",
  "repoRoot": "/Users/dev/myproject",
  "gitBranch": "main"
}

Response

201 Success

JSON

{
  "environmentId": "env_abc123",
  "environment": {
    "environmentId": "env_abc123",
    "organizationId": "org_abc123",
    "displayName": "Ash laptop",
    "hostname": "ash-laptop.local",
    "platform": "darwin",
    "relayCliVersion": "0.1.0",
    "status": "active",
    "lastSeenAt": "2026-08-28T12:00:00.000Z",
    "createdAt": "2026-08-28T12:00:00.000Z",
    "updatedAt": "2026-08-28T12:00:00.000Z"
  }
}

Status codes

Status	Meaning
200	Success.
400	Request body failed validation.
401	Missing, revoked, or invalid organization secret.
429	Ingest rate limit exceeded for this secret.
503	Service unavailable.

curl

Shell

curl -X POST 'https://api.dev.relay.oprag.ai/v1/environments' \
  -H 'X-Relay-Secret: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"hostname": "ash-laptop.local","platform": "darwin","relayCliVersion": "0.1.0","displayName": "Ash laptop","repoRoot": "/Users/dev/myproject","gitBranch": "main"}'

POST /v1/environments/{environmentId}/heartbeat

Refresh last-seen timestamp for a registered environment.

Auth Org secret

Before you call it

Response shape is { environmentId, lastSeenAt } per @relay/api-contract.

Path parameters

Name	Type	Required	Description
`environmentId`	`string`	Required	Registered developer environment id.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

Name	Type	Required	Description
`relayCliVersion`	`string`	Optional	Relay CLI semver string.

Request

JSON

{
  "relayCliVersion": "0.1.0"
}

Response

200 Success

JSON

{
  "environmentId": "env_abc123",
  "lastSeenAt": "2026-08-28T12:05:00.000Z"
}

Status codes

Status	Meaning
200	Success.
400	Request body failed validation.
401	Missing, revoked, or invalid organization secret.
403	Environment is revoked.
404	Resource not found in this organization.
429	Ingest rate limit exceeded for this secret.
503	Service unavailable.

curl

Shell

curl -X POST 'https://api.dev.relay.oprag.ai/v1/environments/{environmentId}/heartbeat' \
  -H 'X-Relay-Secret: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"relayCliVersion": "0.1.0"}'

POST /v1/environments/{environmentId}/agents

Auth Org secret

Before you call it

Response is { installationId, installation } — top-level id matches the nested installation.installationId.

Path parameters

Name	Type	Required	Description
`environmentId`	`string`	Required	Registered developer environment id.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

Name	Type	Required	Description
`agentId`	`enum`	Required	Agent catalog id (e.g. `cursor`).
`version`	`string`	Optional	Agent or CLI version string.
`config`	`object`	Optional	Agent-specific configuration object.

Request

JSON

{
  "agentId": "cursor",
  "version": "1.0.0"
}

Response

201 Success

JSON

{
  "installationId": "inst_abc123",
  "installation": {
    "installationId": "inst_abc123",
    "organizationId": "org_abc123",
    "agentId": "cursor",
    "environmentId": "env_abc123",
    "version": "1.0.0",
    "status": "active",
    "createdAt": "2026-08-28T12:00:00.000Z",
    "updatedAt": "2026-08-28T12:00:00.000Z"
  }
}

Status codes

Status	Meaning
201	Created.
400	Request body failed validation.
401	Missing, revoked, or invalid organization secret.
404	Resource not found in this organization.
429	Ingest rate limit exceeded for this secret.
503	Service unavailable.

curl

Shell

curl -X POST 'https://api.dev.relay.oprag.ai/v1/environments/{environmentId}/agents' \
  -H 'X-Relay-Secret: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"agentId": "cursor","version": "1.0.0"}'

POST /v1/sessions

Open a new agent session for event capture.

Auth Org secret

Before you call it

Optional agentId defaults to the installation's agent when omitted.

Path parameters

None.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

Name	Type	Required	Description
`environmentId`	`string`	Required	Registered environment id.
`agentInstallationId`	`string`	Required	Installation id returned from agent registration.
`agentId`	`string`	Optional	Agent catalog id (e.g. `cursor`).
`title`	`string`	Optional	Optional session title for the review UI.
`repoRoot`	`string`	Optional	Absolute path to the repository root on the machine.
`gitBranch`	`string`	Optional	Active git branch during capture.

Request

JSON

{
  "environmentId": "env_abc123",
  "agentInstallationId": "inst_abc123",
  "title": "Fix auth middleware",
  "repoRoot": "/Users/dev/myproject",
  "gitBranch": "feature/auth"
}

Response

201 Success

JSON

{
  "sessionId": "sess_abc123",
  "session": {
    "sessionId": "sess_abc123",
    "organizationId": "org_abc123",
    "environmentId": "env_abc123",
    "agentInstallationId": "inst_abc123",
    "agentId": "cursor",
    "status": "active",
    "secretEnvironment": "live",
    "title": "Fix auth middleware",
    "startedAt": "2026-08-28T12:00:00.000Z",
    "eventCount": 0,
    "createdAt": "2026-08-28T12:00:00.000Z",
    "updatedAt": "2026-08-28T12:00:00.000Z"
  }
}

Status codes

Status	Meaning
201	Created.
400	Request body failed validation.
401	Missing, revoked, or invalid organization secret.
429	Ingest rate limit exceeded for this secret.
503	Service unavailable.

curl

Shell

curl -X POST 'https://api.dev.relay.oprag.ai/v1/sessions' \
  -H 'X-Relay-Secret: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"environmentId": "env_abc123","agentInstallationId": "inst_abc123","title": "Fix auth middleware","repoRoot": "/Users/dev/myproject","gitBranch": "feature/auth"}'

POST /v1/sessions/{sessionId}/events

Append one or more session events (CLI hooks and sync). Each event's payload is optional and defaults to {}.

Auth Org secret

Before you call it

Send Idempotency-Key: <unique> (preferred) or idempotencyKey in the body for safe retries.
Returns 202 when EventBridge async persistence is enabled; 200 when events persist synchronously. Check async in the response body.
Up to 50 events per batch. Each event's payload is optional (defaults to {} when omitted); when present it must be JSON-serializable and ≤256 KiB.

Path parameters

Name	Type	Required	Description
`sessionId`	`string`	Required	Session id returned from `POST /v1/sessions`.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

Name	Type	Required	Description
`events`	`object[]`	Required	Batch of session events (1–50 per request).
`idempotencyKey`	`string`	Optional	Optional idempotency key (prefer the `Idempotency-Key` header).

Request

JSON

{
  "events": [
    {
      "eventType": "tool.call",
      "payload": { "tool": "grep", "args": { "pattern": "auth" } }
    }
  ]
}

Responses

202 202 Accepted (async)

JSON

{
  "sessionId": "sess_abc123",
  "accepted": 1,
  "firstSequence": 1,
  "lastSequence": 1,
  "async": true
}

200 200 OK (sync)

JSON

{
  "sessionId": "sess_abc123",
  "accepted": 1,
  "firstSequence": 1,
  "lastSequence": 1,
  "async": false
}

Status codes

Status	Meaning
200	Accepted synchronously (`async: false`).
202	Queued for async persistence (`async: true`).
400	Request body failed validation.
401	Missing, revoked, or invalid organization secret.
404	Resource not found in this organization.
409	Session is closed, or idempotent request in progress.
503	Service unavailable.

curl

Shell

curl -X POST 'https://api.dev.relay.oprag.ai/v1/sessions/{sessionId}/events' \
  -H 'X-Relay-Secret: sk_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: batch-001' \
  -d '{"events":[{"eventType":"tool.call","payload":{"tool":"grep"}}]}'

POST /v1/sessions/{sessionId}/complete

Mark a session completed or failed.

Auth Org secret

Path parameters

Name	Type	Required	Description
`sessionId`	`string`	Required	Session id returned from `POST /v1/sessions`.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

Name	Type	Required	Description
`status`	`"completed" \| "failed"`	Optional	Session terminal status: `completed` or `failed`.
`endedAt`	`string`	Optional	ISO-8601 timestamp when the session ended.

Request

JSON

{
  "status": "completed"
}

Response

200 Success

JSON

{
  "sessionId": "sess_abc123",
  "status": "completed",
  "endedAt": "2026-08-28T12:30:00.000Z"
}

Status codes

Status	Meaning
200	Success.
400	Request body failed validation.
401	Missing, revoked, or invalid organization secret.
404	Resource not found in this organization.
409	Session is already closed.
429	Ingest rate limit exceeded for this secret.
503	Service unavailable.

curl

Shell

curl -X POST 'https://api.dev.relay.oprag.ai/v1/sessions/{sessionId}/complete' \
  -H 'X-Relay-Secret: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"status": "completed"}'

Ready to ship?

Get started free