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

# Request archive

> Look up audited API requests and download the archived original payloads.

Every **mutating** call (`POST`/`PUT`/`PATCH`/`DELETE`) to the API is
answered with an `X-Request-Id` response header — a time-sortable UUIDv7 —
and its **verbatim request body is archived** along with a searchable audit
row. These endpoints are the read side: prove exactly what was sent on any
past request.

Reads (`GET`) are not archived — they carry no payload.

## List / search requests

`GET /api/requests`

<ParamField query="route" type="string">
  Path prefix filter, e.g. `/admin/api/v1/consignments` or `/v1/restrict`.
</ParamField>

<ParamField query="source" type="string">
  Surface: `api` (external `/v1`), `admin-api` (this partner surface),
  `account-api`, `cds`.
</ParamField>

<ParamField query="method" type="string">
  `POST` | `PUT` | `PATCH` | `DELETE`.
</ParamField>

<ParamField query="outcome" type="string">
  `completed` | `failed` (4xx/5xx).
</ParamField>

<ParamField query="ref" type="string">
  Search by an identifier extracted from payloads at write time — tracking
  number (S10), shipment ref, declaration ref, external code.
</ParamField>

<ParamField query="starting_after" type="string">
  Keyset cursor: return requests older than this request id.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  1–100.
</ParamField>

Returns `{ requests: [...], has_more }`, newest first. Each row:
`id` (the `X-Request-Id` UUIDv7), `route`, `method`, `source`, `actor`,
`customer_id`, `http_status`, `outcome`, `duration_ms`, `has_body`,
`error_summary`, `created_at`.

## One request

`GET /api/requests/{id}` — the audit row plus its extracted refs
(`{ request: {...}, refs: [{ref_type, ref_value}] }`).

## Download the original payload

`GET /api/requests/{id}/body` — streams the archived request body
**byte-for-byte as it was received** (`404` when the request carried no
body). This is the dispute-resolution artifact: what the caller actually
sent, regardless of what they claim.

<RequestExample>
  ```bash cURL theme={null}
  # Which request touched tracking number LB123456789GB?
  curl "https://{partner}.mytraddal.com/admin/api/v1/api/requests?ref=LB123456789GB" \
    -H "Authorization: Bearer $TOKEN"

  # Pull the exact payload that was sent
  curl "https://{partner}.mytraddal.com/admin/api/v1/api/requests/0198c5a2-7e14-7c3b-9f21-4d6a8b0c2e13/body" \
    -H "Authorization: Bearer $TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json List theme={null}
  {
    "success": true,
    "message": "",
    "requests": [
      {
        "id": "0198c5a2-7e14-7c3b-9f21-4d6a8b0c2e13",
        "route": "/admin/api/v1/consignments",
        "method": "POST",
        "source": "admin-api",
        "actor": "api-client:client_01HV…",
        "customer_id": 4837291056,
        "http_status": 201,
        "outcome": "completed",
        "duration_ms": 412,
        "has_body": true,
        "error_summary": null,
        "created_at": "2026-07-30T14:05:12.000Z"
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>