> ## 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.

# Requests

> Submit a context request and read its status and answer over the ShoulderTap HTTP API.

A request is a consumer asking for context. Submit one, then read its status until it resolves.

## Submit a request

<code>POST /api/v1/requests</code>

Body is a [ContextRequest](/api/contracts) — required fields `kind`, `topic`, `question`, `consumer`.

```bash theme={null}
curl -X POST http://localhost:8776/api/v1/requests \
  -H "Authorization: Bearer $SHOULDERTAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "glossary.definition",
    "topic": "revenue metrics",
    "question": "What does '\''active customer'\'' mean for Q2 reporting?",
    "consumer": "bi.assistant",
    "context": {
      "asked_because": "BI agent hit low confidence answering a user query",
      "entity": "dim_customers.active_flag"
    },
    "dedup_key": "glossary:dim_customers.active_flag"
  }'
```

### Response

```json theme={null}
{ "id": "req_01J...", "status": "queued" }
```

<ResponseField name="id" type="string">
  The request id, prefix `req_`.
</ResponseField>

<ResponseField name="status" type="string">
  The submit-time status: `queued`, `deduped_open`, `deduped_resolved`, or `failed`. See [Status codes](/api/errors#request-status-vs-submit-status).
</ResponseField>

## Get a request

<code>GET /api/v1/requests/\{id}</code>

Returns the full request plus runtime fields — its current `status`, the `subscribers` attached to it, the expert it was `asked` of, whether it `escalated`, and the accepted `proposal` once resolved.

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

```json theme={null}
{
  "id": "req_01J...",
  "kind": "glossary.definition",
  "topic": "revenue metrics",
  "question": "What does 'active customer' mean for Q2 reporting?",
  "consumer": "bi.assistant",
  "status": "accepted",
  "subscribers": ["bi.assistant"],
  "routing_policy": { "priority": 50 },
  "proposal": { "id": "prop_01J...", "answer": "paying accounts active in 90 days" }
}
```

A `status` of `accepted` means `proposal` holds the approved answer. An unknown id returns `404`.