Projects

Projects define the operating context for participants, processes, and resolve requests.

Project reads follow status and read_access_mode. live projects use the configured read access mode. draft, test, and archived projects are visible only to admins and project owners. Project writes still require admin access or an owner row.

Endpoints

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

List Projects

Curl

curl "https://roster.example.com/api/v1/projects?query=helios%20vendor&limit=10" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

TypeScript

const url = new URL("https://roster.example.com/api/v1/projects");
url.searchParams.set("query", "helios vendor");
url.searchParams.set("limit", "10");

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

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

const data = await response.json();

Python

import os
import requests

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

query splits into words and matches all words against project name and description, case-insensitively. limit caps returned projects from 1 to 100. Responses include can_manage, read_access_mode, owners, and members so clients can distinguish read-only access from management access. They also include status so clients can show draft, test, live, and archived projects when the caller is allowed to see them.

Create Project

Curl

curl -X POST "https://roster.example.com/api/v1/projects" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Helios Onboarding",
    "description": "Vendor onboarding and security review workflow.",
    "status": "live",
    "read_access_mode": "selected_members",
    "owner_ids": ["usr_owner"],
    "member_ids": ["usr_reader"]
  }'

TypeScript

const response = await fetch("https://roster.example.com/api/v1/projects", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ROSTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Helios Onboarding",
    description: "Vendor onboarding and security review workflow.",
    status: "live",
    read_access_mode: "selected_members",
    owner_ids: ["usr_owner"],
    member_ids: ["usr_reader"],
  }),
});

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

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://roster.example.com/api/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    json={
        "name": "Helios Onboarding",
        "description": "Vendor onboarding and security review workflow.",
        "status": "live",
        "read_access_mode": "selected_members",
        "owner_ids": ["usr_owner"],
        "member_ids": ["usr_reader"],
    },
    timeout=10,
)
response.raise_for_status()
data = response.json()

status accepts draft, test, live, or archived and defaults to live. read_access_mode accepts authenticated_users or selected_members. member_ids grants read-only project access; owner identities are implicit readers.

Archiving a project is a PATCH that sets status to archived. DELETE removes the project from active use.