Delegations

Delegations route requests to temporary coverage contacts when the original participant member is unavailable or has delegated responsibility.

Endpoints

Method	Path	Required scope
GET	/api/v1/delegations	api:delegations:read
POST	/api/v1/delegations	api:delegations:write
GET	/api/v1/delegations/:id	api:delegations:read
PATCH	/api/v1/delegations/:id	api:delegations:write
DELETE	/api/v1/delegations/:id	api:delegations:write

List Delegations

Curl

curl "https://roster.example.com/api/v1/delegations?project_id=proj_123&status=active&limit=25" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

TypeScript

const url = new URL("https://roster.example.com/api/v1/delegations");
url.searchParams.set("project_id", "proj_123");
url.searchParams.set("status", "active");
url.searchParams.set("limit", "25");

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

if (!response.ok) {
  throw new Error(`Delegation list failed: ${response.status}`);
}

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://roster.example.com/api/v1/delegations",
    params={"project_id": "proj_123", "status": "active", "limit": 25},
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
data = response.json()

Supported filters include project_id, participant_id, delegator_user_id, delegate_user_id, scope, status, and limit. scope accepts all_participants or participant; status accepts active, expired, revoked, or upcoming; limit accepts values from 1 to 100.

Delegation reads use the same visibility model as the dashboard: admins can read all delegations; project owners can read participant-scoped delegations for owned participants when the delegator is represented on that participant; other non-admin callers can read only their own eligible delegation context. Delegation writes still require admin access, project ownership for the participant, or the caller’s own eligible delegation context.

Create Delegation

Curl

curl -X POST "https://roster.example.com/api/v1/delegations" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "delegate_user_id": "drec_delegate",
    "delegator_user_id": "drec_delegator",
    "scope": "participant",
    "participant_id": "part_123",
    "starts_at": "2026-05-27",
    "ends_at": "2026-06-27"
  }'

TypeScript

const response = await fetch("https://roster.example.com/api/v1/delegations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ROSTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    delegate_user_id: "drec_delegate",
    delegator_user_id: "drec_delegator",
    scope: "participant",
    participant_id: "part_123",
    starts_at: "2026-05-27",
    ends_at: "2026-06-27",
  }),
});

if (!response.ok) {
  throw new Error(`Delegation creation failed: ${response.status}`);
}

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://roster.example.com/api/v1/delegations",
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    json={
        "delegate_user_id": "drec_delegate",
        "delegator_user_id": "drec_delegator",
        "scope": "participant",
        "participant_id": "part_123",
        "starts_at": "2026-05-27",
        "ends_at": "2026-06-27",
    },
    timeout=10,
)
response.raise_for_status()
data = response.json()