Session ingest

Open sessions, append events, and complete them from the CLI.

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

All 3 endpoints on this page use org-secret or public auth — see the CLI ingest reference.

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