> ## Documentation Index
> Fetch the complete documentation index at: https://docs.risos.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start one structured Research Product and inspect its Living Deliverable.

## 1. Create a scoped key

Create a key in **RISOS → Developers** with:

* `research:read`
* `research:write`

Send it on every authenticated REST request:

```http theme={null}
Authorization: Bearer $RISOS_API_KEY
```

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

## 2. Choose a Product

Read the canonical Product registry:

```bash theme={null}
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.

```bash theme={null}
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**.