REST API (/sdk/v1)

Base path: /sdk/v1. Authenticate runtime calls with X-RAI-Agent-Key. Compatibility range for the public SDK contract is API_RANGE >=1.0.0,<2.0.0.

Endpoints: GET /sdk/v1/health — health check. POST /sdk/v1/heartbeat — integration heartbeat. POST /sdk/v1/sessions — start session. POST /sdk/v1/sessions/{session_id}/input — observe input. POST /sdk/v1/sessions/{session_id}/actions/authorize — authorize before side effects (supports Idempotency-Key). POST /sdk/v1/actions/{decision_id}/execution — report execution result after ALLOW. POST /sdk/v1/sessions/{session_id}/output — observe output. POST /sdk/v1/sessions/{session_id}/end — end session.

Authorize first. Only when the decision is ALLOW should your application perform the business action, then report SUCCEEDED/FAILED (or equivalent) against the decision id.

Prefer the official SDKs for everyday use. Use raw HTTP when you need a non-SDK language. OpenAPI for the stable contract lives in the control-plane / raicentral repository at docs/api/sdk-v1-openapi.yaml.

Do not build new integrations against legacy internal runtime paths — /sdk/v1 is the public surface.