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

# Experts

> Read the expert registry with live state, or replace it wholesale, over the ShoulderTap HTTP API.

These endpoints expose the expert registry. See [Experts and routing](/run/experts) for how experts are matched.

## List experts

<code>GET /api/v1/experts</code>

Returns each expert's configuration plus the live state the engine tracks.

```bash theme={null}
curl http://localhost:8776/api/v1/experts \
  -H "Authorization: Bearer $SHOULDERTAP_API_TOKEN"
```

```json theme={null}
[
  {
    "id": "U0123ABC",
    "name": "Dana Kim",
    "topics": ["revenue metrics", "customer definitions"],
    "escalation_to": "U0456DEF",
    "muted": false,
    "open_asks": 1,
    "asks_today": 2
  }
]
```

<ResponseField name="id" type="string">The expert's Slack user ID.</ResponseField>

<ResponseField name="name" type="string" />

<ResponseField name="topics" type="array" />

<ResponseField name="escalation_to" type="string | null" />

<ResponseField name="muted" type="boolean">Whether the expert has opted out with `mute`.</ResponseField>
<ResponseField name="open_asks" type="integer">Unanswered asks currently outstanding.</ResponseField>
<ResponseField name="asks_today" type="integer">Asks sent to this expert today.</ResponseField>

## Replace the registry

<code>PUT /api/v1/experts</code>

Replaces the entire registry with the array you send — this is a **full replace, not a merge**.

```bash theme={null}
curl -X PUT http://localhost:8776/api/v1/experts \
  -H "Authorization: Bearer $SHOULDERTAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": "U0123ABC", "name": "Dana Kim", "topics": ["revenue metrics"], "escalation_to": "U0456DEF"}]'
```

Each entry takes `id`, `name`, `topics`, and optional `escalation_to`. Returns the updated registry with live state.

<Warning>
  `PUT /experts` rewrites the `experts:` section of `shouldertap.yaml` on disk — the config file remains the source of truth. Anything you omit from the array is removed.
</Warning>