Quickstart

1. Create a scoped key

Create a key in RISOS → Developers with:

research:read
research:write

Send it on every authenticated REST request:

Authorization: Bearer $RISOS_API_KEY

REST base URL: https://risos.co/api/rest

2. Choose a Product

Read the canonical Product registry:

curl https://risos.co/api/rest/products \
  -H "Authorization: Bearer $RISOS_API_KEY"

The response contains exactly the 10 current Product machine IDs.

3. Create or select a Project

Use GET /projects to reuse an existing Project or POST /projects to create one.

4. Start Research

Send structured Product input to POST /research-jobs. Every start request requires a stable Idempotency-Key so a safe retry does not create duplicate paid work.

curl -X POST https://risos.co/api/rest/research-jobs \
  -H "Authorization: Bearer $RISOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-study-001" \
  -d '{
    "productId": "understand_customers",
    "input": {
      "subject": "AI coding assistants",
      "question": "What recurring workflow problems do developers describe?"
    }
  }'

5. Read the result

Poll GET /research-jobs/{id} for lifecycle and progress. When the job exposes a Living Deliverable, read it through GET /deliverables/{id}. A valid ResearchJob can finish as ready, partial, or blocked. RISOS does not fabricate a complete answer when admissible evidence is insufficient. Use POST /ask when you want an answer from current Workspace intelligence without starting new Research or reserving Research credits.

Getting started

Core concepts

Build

1. Create a scoped key

2. Choose a Product

3. Create or select a Project

4. Start Research

5. Read the result

​1. Create a scoped key

​2. Choose a Product

​3. Create or select a Project

​4. Start Research

​5. Read the result

1. Create a scoped key

2. Choose a Product

3. Create or select a Project

4. Start Research

5. Read the result