Admin Resources

These REST groups expose the same platform administration surfaces available in the web UI. They require API-key bearer auth, the matching api:* scope, and an API-key owner that is an active platform admin. Scopes expose the API surface; they do not grant the owner admin rights.

All request and response JSON keys are snake_case. Write endpoints that accept a body require Content-Type: application/json.

Product Access

Admin REST endpoints follow the current product license:

Audit events are available only when GET /api/v1/status reports "features": { "audit_events": true }.
Model runs are available only when GET /api/v1/status reports "features": { "model_runs": true }.
Team-member creation and reactivation follow the edition’s active human team-member cap.

Team Members

Method	Path	Scope
`GET`	`/api/v1/team-members`	`api:team-members:read`
`POST`	`/api/v1/team-members`	`api:team-members:write`
`GET`	`/api/v1/team-members/:teamMemberId`	`api:team-members:read`
`PATCH`, `DELETE`	`/api/v1/team-members/:teamMemberId`	`api:team-members:write`
`POST`	`/api/v1/team-members/:teamMemberId/enable`, `/api/v1/team-members/:teamMemberId/disable`	`api:team-members:write`

GET /api/v1/team-members accepts query.

Create payload:

{
  "auth_method": "password",
  "email": "admin@example.com",
  "email_verified": true,
  "name": "Admin User",
  "password": "a strong temporary password",
  "require_password_change": true,
  "role": "admin",
  "send_invite_email": false
}

auth_method is password or idp_only. role is admin, project_owner, or member. PATCH accepts partial email, email_verified, name, password, and role fields; omitted fields are preserved. A user cannot delete or disable their own account through the API.

AI Agents and Service Accounts

AI agents and service accounts use the same payload shape. Only the path and scope prefix differ.

Resource	Endpoints	Scopes
AI agents	`GET/POST /api/v1/ai-agents` `GET/PATCH/DELETE /api/v1/ai-agents/:aiAgentId` `POST /api/v1/ai-agents/:aiAgentId/enable` `POST /api/v1/ai-agents/:aiAgentId/disable`	`api:ai-agents:read` `api:ai-agents:write`
Service accounts	`GET/POST /api/v1/service-accounts` `GET/PATCH/DELETE /api/v1/service-accounts/:serviceAccountId` `POST /api/v1/service-accounts/:serviceAccountId/enable` `POST /api/v1/service-accounts/:serviceAccountId/disable`	`api:service-accounts:read` `api:service-accounts:write`

GET collection endpoints accept query.

Create payload:

{
  "display_name": "Nightly sync",
  "email": "nightly-sync@example.com",
  "role": "member"
}

email may be omitted or sent as an empty string. PATCH accepts partial display_name, email, and role fields; omitted fields are preserved.

API Keys

Method	Path	Scope
`GET`	`/api/v1/api-keys`	`api:api-keys:read`
`POST`	`/api/v1/api-keys`	`api:api-keys:write`
`GET`	`/api/v1/api-keys/:apiKeyId`	`api:api-keys:read`
`DELETE`	`/api/v1/api-keys/:apiKeyId`	`api:api-keys:write`

Create payload:

{
  "name": "Provisioning job",
  "scopes": "api:status:read api:team-members:read",
  "user_id": "usr_admin",
  "expires_at": "2027-01-01T00:00:00.000Z"
}

The plaintext token is returned only from POST /api/v1/api-keys:

{
  "api_key": {
    "id": "atok_...",
    "name": "Provisioning job",
    "token_prefix": "rst_...",
    "scopes": "api:status:read api:team-members:read"
  },
  "token": "rst_..."
}

List and get responses include token_prefix, never token hashes or plaintext tokens. DELETE /api/v1/api-keys/:apiKeyId revokes the key.

Audit Events

Audit events are read-only, admin-only, and edition gated.

Method	Path	Scope
`GET`	`/api/v1/audit-events`	`api:audit-events:read`
`GET`	`/api/v1/audit-events/:auditEventId`	`api:audit-events:read`

Supported list filters: action, actor_type, created_from, created_to, event_type, page_index, page_size, query, and resource_type. actor_type accepts all, api_key, service_account, system, or user. Unavailable audit-event access returns 403 with /api/v1/problems/forbidden.

Curl
TypeScript

curl "<your-roster-public-url>/api/v1/audit-events?actor_type=api_key&page_size=25" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

const url = new URL("<your-roster-public-url>/api/v1/audit-events");
url.searchParams.set("actor_type", "api_key");
url.searchParams.set("page_size", "25");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ROSTER_API_KEY}` },
});

const data = await response.json();

Model Runs

Model runs are read-only, admin-only, and edition gated.

Method	Path	Scope
`GET`	`/api/v1/model-runs`	`api:model-runs:read`
`GET`	`/api/v1/model-runs/:modelRunId`	`api:model-runs:read`

Responses include model metadata, token counts, latency, status, trace/request ids, and nested tool_calls. PII and tool payload fields follow the platform privacy settings. Unavailable model-run access returns 403 with /api/v1/problems/forbidden.

Provider Connectors

Method	Path	Scope
`GET`	`/api/v1/provider-connectors`	`api:provider-connectors:read`
`POST`	`/api/v1/provider-connectors`	`api:provider-connectors:write`
`GET`	`/api/v1/provider-connectors/:providerConnectorId`	`api:provider-connectors:read`
`PATCH`, `DELETE`	`/api/v1/provider-connectors/:providerConnectorId`	`api:provider-connectors:write`

kind accepts entra, okta, google_workspace, workday, ldap, or csv. Connector type cannot be changed after creation.

Create payloads require kind and name, plus the fields required by that connector kind. Common fields include enabled, directory_role, refresh_cron, and kind-specific config or secret reference fields such as client_secret_ref, api_key_ref, private_key_ref, bind_password_ref, and s3_secret_access_key_ref.

PATCH /api/v1/provider-connectors/:providerConnectorId preserves omitted config and secret reference fields. To clear an optional field, send null or an empty string. Responses include external secret reference names only and never include secret material.

{
  "kind": "okta",
  "name": "Okta",
  "org_url": "https://example.okta.com",
  "api_key_ref": "secret/data/okta-api-token",
  "directory_role": "primary",
  "enabled": true
}

Platform Settings

Method	Path	Scope
`GET`	`/api/v1/platform-settings`	`api:platform-settings:read`
`PATCH`	`/api/v1/platform-settings`	`api:platform-settings:write`

GET /api/v1/platform-settings returns the global settings record with id, settings, created_at, and updated_at. The nested settings object contains access, retention, pii, rate_limiting, and agents.

PATCH /api/v1/platform-settings requires a full settings object wrapped in settings:

{
  "settings": {
    "access": {
      "method": "authenticated_users",
      "password_login_enabled": true,
      "invite_email": {
        "enabled": false,
        "from_email": null,
        "from_name": null,
        "provider": null,
        "reply_to": null,
        "resend": {
          "api_key_configured": false
        },
        "smtp": {
          "host": null,
          "password_configured": false,
          "port": null,
          "secure": true,
          "username": null
        }
      }
    },
    "retention": {
      "audit_events": { "days": null },
      "model_runs": { "days": null },
      "resolve_requests": { "days": null }
    },
    "pii": {
      "audit_events": {
        "ip_address": true,
        "metadata_personal_fields": true,
        "user_agent": true
      },
      "model_runs": {
        "actor_email": true,
        "actor_name": true,
        "error_details": true,
        "input_output": true,
        "tool_payloads": true
      },
      "operational_logs": {
        "connector_identifiers": true,
        "error_details": true,
        "model_dev_notes": true
      },
      "resolve_requests": {
        "actor_credential_details": true,
        "actor_email": true,
        "actor_name": true,
        "query": true,
        "result_fields": {
          "delegation_details": true,
          "display_name": true,
          "email": true,
          "labels": true,
          "memberships": true,
          "metadata": false,
          "participant_names": true,
          "project_ids": true,
          "title": true,
          "user_id": true
        }
      },
      "worker_journals": {
        "retention_days": null
      }
    },
    "rate_limiting": {
      "enabled": true,
      "rules": []
    },
    "agents": [
      {
        "agent_name": "roster.resolver",
        "api": null,
        "cached_input_cost_per_million_tokens": null,
        "input_cost_per_million_tokens": null,
        "max_tokens": null,
        "model_name": null,
        "model_provider": null,
        "output_cost_per_million_tokens": null,
        "reasoning_effort": null,
        "url": null
      }
    ]
  }
}

Invite-email secrets are redacted in responses. Preserve configured SMTP or Resend secrets by keeping the corresponding password_configured or api_key_configured flag set to true; send a new password or api_key only when replacing the secret.