Agents — REST API

GET /v1/agents

List supported agent definitions in the Relay catalog.

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

{
  "agents": [
    {
      "agentId": "cursor",
      "displayName": "Cursor",
      "vendor": "Anysphere",
      "status": "active",
      "createdAt": "2026-08-01T00:00: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/agents' \
  -H 'Authorization: Bearer <Cognito JWT>'

GET /v1/organizations/me/agents

List agent installations 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

{
  "installations": [
    {
      "installationId": "inst_abc123",
      "organizationId": "org_abc123",
      "agentId": "cursor",
      "environmentId": "env_abc123",
      "status": "active",
      "createdAt": "2026-08-28T12:00:00.000Z",
      "updatedAt": "2026-08-28T12:00: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/agents' \
  -H 'Authorization: Bearer <Cognito JWT>'

POST /v1/organizations/me/agents

Create an agent installation from the dashboard.

Auth Cognito JWT admin+

Path parameters

None.

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`).
`environmentId`	`string`	Optional	Registered environment id.
`version`	`string`	Optional	Agent or CLI version string.
`config`	`object`	Optional	Agent-specific configuration object.

Request

JSON

{
  "agentId": "cursor",
  "environmentId": "env_abc123"
}

Response

201 Success

JSON

{
  "installation": {
    "installationId": "inst_abc123",
    "organizationId": "org_abc123",
    "agentId": "cursor",
    "environmentId": "env_abc123",
    "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 or expired JWT.
403	Insufficient organization role.
429	Rate limited. See rate limits.
503	Service unavailable.

curl

Shell

curl -X POST 'https://api.dev.relay.oprag.ai/v1/organizations/me/agents' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"agentId": "cursor","environmentId": "env_abc123"}'

PATCH /v1/organizations/me/agents/{installationId}

Update an agent installation's version, config, or status.

Auth Cognito JWT admin+

Path parameters

Name	Type	Required	Description
`installationId`	`string`	Required	Agent installation id.

Query parameters

None.This endpoint does not read query parameters.

Body parameters

Name	Type	Required	Description
`version`	`string`	Optional	Agent or CLI version string.
`config`	`object`	Optional	Agent-specific configuration object.
`status`	`"active" \| "disabled"`	Optional	Session terminal status: `completed` or `failed`.

Request

JSON

{
  "status": "disabled"
}

Response

200 Success

JSON

{
  "installation": {
    "installationId": "inst_abc123",
    "organizationId": "org_abc123",
    "agentId": "cursor",
    "environmentId": "env_abc123",
    "status": "disabled",
    "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 PATCH 'https://api.dev.relay.oprag.ai/v1/organizations/me/agents/{installationId}' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"status": "disabled"}'

POST /v1/environments/{environmentId}/agents

Register or upsert an agent installation from the CLI.

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