Environments — REST API

POST /v1/environments

Register or update a developer machine environment from the CLI.

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"}'

GET /v1/organizations/me/environments

List developer environments registered for the organization.

Auth Cognito JWT member+

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

{
  "environments": [
    {
      "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:05:00.000Z",
      "createdAt": "2026-08-28T12:00:00.000Z",
      "updatedAt": "2026-08-28T12:05:00.000Z"
    }
  ]
}

Status codes

Status	Meaning
200	Success.
401	Missing or expired JWT.
403	Insufficient organization role.
429	Rate limited. See rate limits.
503	Service unavailable.

curl

Shell

curl -X GET 'https://api.dev.relay.oprag.ai/v1/organizations/me/environments' \
  -H 'Authorization: Bearer <Cognito JWT>'

GET /v1/organizations/me/environments/{environmentId}

Fetch one developer environment by id.

Auth Cognito JWT member+

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

None.This endpoint does not read a request body.

Response

200 Success

JSON

{
  "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:05:00.000Z",
    "createdAt": "2026-08-28T12:00:00.000Z",
    "updatedAt": "2026-08-28T12:05:00.000Z"
  }
}

Status codes

Status	Meaning
200	Success.
401	Missing or expired JWT.
403	Insufficient organization role.
404	Resource not found in this organization.
429	Rate limited. See rate limits.
503	Service unavailable.

curl

Shell

curl -X GET 'https://api.dev.relay.oprag.ai/v1/organizations/me/environments/{environmentId}' \
  -H 'Authorization: Bearer <Cognito JWT>'

DELETE /v1/organizations/me/environments/{environmentId}

Revoke a developer environment.

Auth Cognito JWT admin+

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

None.This endpoint does not read a request body.

Response

200 Success

JSON

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

Status codes

Status	Meaning
200	Success.
400	Request body failed validation.
401	Missing or expired JWT.
403	Insufficient organization role.
404	Resource not found in this organization.
429	Rate limited. See rate limits.
503	Service unavailable.

curl

Shell

curl -X DELETE 'https://api.dev.relay.oprag.ai/v1/organizations/me/environments/{environmentId}' \
  -H 'Authorization: Bearer <Cognito JWT>'