ColleagueOne
Request access
ColleagueOne documentation

API quickstart

Create and follow Work with the ColleagueOne REST API.

The ColleagueOne Public Work API lets a service account create Work, follow its progress, answer clarification requests, resolve approvals, and download result Artifacts. Version 1 uses JSON over HTTP, with server-sent events (SSE) for live activity.

The published contract currently declares http://127.0.0.1:8080 as its server. Set COLLEAGUEONE_API_BASE to the base URL supplied with your deployment rather than assuming a production hostname.

Before you begin

You need a bearer service-account credential and the ID of a colleague that the service account can use. Keep credentials on a server or in a secret manager; do not put them in browser code or source control.

Each operation requires a scope:

Scope Access
upload:create Create, inspect, and retry input uploads
work:create Create Work
work:read List and read Work; stream its activity
work:guide List and resolve clarification items
approval:read List approvals
approval:resolve Approve or decline an approval
artifact:read List and download result Artifacts

Send the credential on every request:

Authorization: Bearer <service-account-token>

The API returns 401 when the credential is missing, invalid, revoked, or unavailable. It returns 403 when the service account lacks the required scope or policy denies the request.

Create Work

colleague_id and objective are the only required JSON properties. A create request also requires an Idempotency-Key header.

cURL

export COLLEAGUEONE_API_BASE="http://127.0.0.1:8080"
export COLLEAGUEONE_TOKEN="replace-with-service-account-token"
export COLLEAGUEONE_COLLEAGUE_ID="replace-with-colleague-id"

curl --fail-with-body \
  --request POST \
  "$COLLEAGUEONE_API_BASE/api/v1/work" \
  --header "Authorization: Bearer $COLLEAGUEONE_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: quickstart-create-001" \
  --data "{\"colleague_id\":\"$COLLEAGUEONE_COLLEAGUE_ID\",\"objective\":\"Summarize the supplied research notes.\",\"title\":\"Research summary\"}"

JavaScript

const baseUrl = process.env.COLLEAGUEONE_API_BASE ?? "http://127.0.0.1:8080";
const response = await fetch(`${baseUrl}/api/v1/work`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COLLEAGUEONE_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    colleague_id: process.env.COLLEAGUEONE_COLLEAGUE_ID,
    objective: "Summarize the supplied research notes.",
    title: "Research summary",
  }),
});

const body = await response.json();
if (!response.ok) throw new Error(`${body.code}: ${body.detail}`);
console.log(body.id, body.status);

Python

This example uses only the Python standard library.

import json
import os
import uuid
from urllib.request import Request, urlopen

base_url = os.getenv("COLLEAGUEONE_API_BASE", "http://127.0.0.1:8080")
payload = json.dumps({
    "colleague_id": os.environ["COLLEAGUEONE_COLLEAGUE_ID"],
    "objective": "Summarize the supplied research notes.",
    "title": "Research summary",
}).encode()

request = Request(
    f"{base_url}/api/v1/work",
    data=payload,
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['COLLEAGUEONE_TOKEN']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)

with urlopen(request) as response:
    work = json.load(response)
    print(work["id"], work["status"])

A new request returns 201. An exact replay of the same idempotent request can return 200 with Idempotent-Replayed: true. Save the returned Work id for later calls.

Check progress

Read one Work item with the work:read scope:

curl --fail-with-body \
  "$COLLEAGUEONE_API_BASE/api/v1/work/$WORK_ID" \
  --header "Authorization: Bearer $COLLEAGUEONE_TOKEN"

The Work status is one of working, needs_you, paused, or done. For live updates, use the SSE events stream.

Add input content

The public create-Work operation does not accept inline attachments. First create a bounded upload with upload:create, wait until its status is ready, then include its id in input_upload_ids. The API accepts UTF-8 content up to 102,400 bytes with one of these media types: application/json, text/csv, text/markdown, or text/plain. A Work request accepts at most four unique upload IDs.

curl --fail-with-body \
  --request POST \
  "$COLLEAGUEONE_API_BASE/api/v1/uploads" \
  --header "Authorization: Bearer $COLLEAGUEONE_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: quickstart-upload-001" \
  --data '{"name":"notes.md","media_type":"text/markdown","content":"# Research notes\nVerified source material."}'

Poll GET /api/v1/uploads/{id} while the upload is processing. Only ready uploads can be attached. A failed scan reports processing_state, failure_code, and whether it is retryable; retryable scan_failed uploads can be submitted to POST /api/v1/uploads/{id}/processing/retry with a new idempotency key.

Idempotency and concurrent changes

Every mutating operation in this API requires a caller-selected Idempotency-Key of 1–255 characters. Retrying the same operation with the same input returns its original result. Reusing the key with different input returns 409 with code IDEMPOTENCY_CONFLICT.

Resolving a clarification or approval also requires the resource’s current strong integer version tag in If-Match. A missing precondition returns 428; a stale version returns 412. Read the resource again before retrying with its current version. Exact resolution retries can return the prior result with Idempotent-Replayed: true.

Pagination

Only GET /api/v1/work is paginated in the current contract. Results are newest first. limit defaults to 50 and accepts 1–100. When the response contains next_cursor, pass that opaque value as cursor on the next request. Do not construct or modify cursors.

curl --get "$COLLEAGUEONE_API_BASE/api/v1/work" \
  --header "Authorization: Bearer $COLLEAGUEONE_TOKEN" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Errors and retries

Error bodies use application/problem+json and contain type, title, status, detail, instance, code, request_id, and retryable. An input scan failure can also include failure_code. Use code for program logic and keep request_id when contacting support.

All operations can return 429. When rate-limited, honor Retry-After; RateLimit-Policy describes the limit class, burst quota, and window, while RateLimit reports remaining requests and refill time. The contract does not publish fixed quota numbers. Creating Work can also return 503 when execution admission has no capacity; honor its Retry-After header.

Continue with the complete API reference or learn how to stream Work events.