Directory Records

Directory record endpoints expose cached, materialized user and group entries for participant association. They do not search upstream CSV, LDAP, or Entra connectors live.

The Platform admin participant picker can browse supported connectors live, such as CSV and Microsoft Entra ID. These REST endpoints intentionally remain cache-only so API callers search the same materialized records used by Resolve and MCP.

Endpoints

Method	Path	Required scope
GET	/api/v1/directory-records	api:participants:read
GET	/api/v1/participants/:id/members	api:participants:read
POST	/api/v1/participants/:id/members	api:participants:write
DELETE	/api/v1/participants/:id/members/:directory_entry_id	api:participants:write

Search Directory Records

Curl

curl "https://roster.example.com/api/v1/directory-records?type=user&query=ethan&limit=10" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

TypeScript

const url = new URL("https://roster.example.com/api/v1/directory-records");
url.searchParams.set("type", "user");
url.searchParams.set("query", "ethan");
url.searchParams.set("limit", "10");

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

if (!response.ok) {
  throw new Error(`Directory records search failed: ${response.status}`);
}

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://roster.example.com/api/v1/directory-records",
    params={"type": "user", "query": "ethan", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
data = response.json()

type accepts all, user, or group. query matches cached directory record id, display name, email, and description. limit accepts values from 1 to 100.

List Participant Members

Curl

curl "https://roster.example.com/api/v1/participants/part_123/members?type=user&query=ethan&limit=10" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

TypeScript

const url = new URL("https://roster.example.com/api/v1/participants/part_123/members");
url.searchParams.set("type", "user");
url.searchParams.set("query", "ethan");
url.searchParams.set("limit", "10");

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

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

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://roster.example.com/api/v1/participants/part_123/members",
    params={"type": "user", "query": "ethan", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
data = response.json()

Participant member listing returns direct directory users and groups associated with one participant. type accepts all, user, or group; query matches direct member id, display name, email, type, and description; limit accepts values from 1 to 100.

Add Participant Member

Curl

curl -X POST "https://roster.example.com/api/v1/participants/part_123/members" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "directory_entry_id": "drec_123" }'

TypeScript

const response = await fetch("https://roster.example.com/api/v1/participants/part_123/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ROSTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ directory_entry_id: "drec_123" }),
});

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

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://roster.example.com/api/v1/participants/part_123/members",
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    json={"directory_entry_id": "drec_123"},
    timeout=10,
)
response.raise_for_status()
data = response.json()