Resolve

Resolve endpoints answer who should handle a workflow question and expose auditable resolve request history. Resolve returns directly associated users plus active members of associated groups, with active delegations applied as runtime coverage.

Endpoints

Method	Path	Required scope
POST	/api/v1/resolve	api:resolve
GET	/api/v1/resolve-requests	api:resolve-requests:read
GET	/api/v1/resolve-requests/:id	api:resolve-requests:read

Create Resolve Request

Curl

curl -X POST "<your-roster-public-url>/api/v1/resolve" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who should handle vendor security review for Atlas onboarding?",
    "project_id": "proj_123",
    "mode": "live"
  }'

TypeScript

const response = await fetch("<your-roster-public-url>/api/v1/resolve", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ROSTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Who should handle vendor security review for Atlas onboarding?",
    project_id: "proj_123",
    mode: "live",
  }),
});

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

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "<your-roster-public-url>/api/v1/resolve",
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    json={
        "query": "Who should handle vendor security review for Atlas onboarding?",
        "project_id": "proj_123",
        "mode": "live",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()

project_id is optional. When it is omitted, Resolve searches all projects visible to the API key owner. mode is optional, defaults to live, and accepts live or test.

Resolve uses project status and project read access:

• Without project_id, live mode receives readable live projects and test mode receives resolvable test projects.
• A live project can be resolved explicitly when the caller has read access.
• A test project can be resolved explicitly only with mode: "test" and admin or project-owner access.
• draft and archived projects are excluded from REST Resolve.

List Resolve Requests

Curl

curl "<your-roster-public-url>/api/v1/resolve-requests?project_id=proj_123&resolution_status=success&limit=25" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

TypeScript

const url = new URL("<your-roster-public-url>/api/v1/resolve-requests");
url.searchParams.set("project_id", "proj_123");
url.searchParams.set("resolution_status", "success");
url.searchParams.set("limit", "25");

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

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

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "<your-roster-public-url>/api/v1/resolve-requests",
    params={"project_id": "proj_123", "resolution_status": "success", "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, actor_id, resolution_status, created_after, created_before, query, and limit. resolution_status accepts success, not_found, out_of_scope, or error. Date filters accept ISO date-time strings. query searches the original Resolve request text. limit accepts values from 1 to 100 and defaults to 25.