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

# Endpoints and requests

> How Admin API endpoints are organized and how to call them.

Admin API endpoints are organized by resource type. All Admin API endpoints
follow this pattern:

```text theme={null}
https://{partner}.mytraddal.com/admin/api/v1/{resource}
```

Replace `{partner}` with your workspace's subdomain (slug) and
`{access_token}` with a token from the
[authentication flow](/guides/authentication). Tokens are partner-bound: a
token minted for one workspace only works on that workspace's subdomain.

Everything on the wire is **snake\_case**, in both directions — request
bodies and response keys alike (`shipment_ref`, `country_of_origin`,
`parcels[].items[]`).

<AccordionGroup>
  <Accordion title="Example POST request — create a consignment">
    ```bash theme={null}
    curl -X POST \
      https://{partner}.mytraddal.com/admin/api/v1/consignments \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer {access_token}' \
      -d '{
        "shipment_ref": "SHIP-1001",
        "receiver": {
          "company_name": "Acme Inc",
          "city": "New York",
          "country_code": "US"
        }
      }'
    ```
  </Accordion>

  <Accordion title="Example GET request — list consignments">
    ```bash theme={null}
    curl https://{partner}.mytraddal.com/admin/api/v1/consignments?limit=25 \
      -H 'Authorization: Bearer {access_token}'
    ```
  </Accordion>

  <Accordion title="Example DELETE request — delete a consignment">
    ```bash theme={null}
    curl -X DELETE \
      https://{partner}.mytraddal.com/admin/api/v1/consignments/{id} \
      -H 'Authorization: Bearer {access_token}'
    ```
  </Accordion>
</AccordionGroup>

## Response envelope

Success responses carry `success: true` and a human-readable `message`
(empty for reads), with the payload spread alongside:

```json theme={null}
{ "success": true, "message": "Customer created", "customer": { "id": 12 } }
```

Errors mirror it — see [Status and error codes](/api-reference/errors).
The one exception is [`POST /screen`](/api-reference/screen/check), whose
result object is the body directly, with no envelope.

## Request ids

Every API request is audited and answered with an `X-Request-Id` response
header (a UUIDv7). Quote it to support, or look the request up in
**Settings → Developers** later.

## Resources

| Resource      | Base path                                      | Scope                                      |
| ------------- | ---------------------------------------------- | ------------------------------------------ |
| Consignments  | `/consignments`                                | `consignments:read` / `consignments:write` |
| Customers     | `/customers`                                   | `customers:read` / `customers:write`       |
| Catalogue     | `/catalogue`                                   | `catalogue:read` / `catalogue:write`       |
| Classify      | `/classify`                                    | `classify:read`                            |
| Calculate     | `/calculate`                                   | `calculate:read`                           |
| Restrict      | `/restrict`                                    | `restrict:read`                            |
| Screen        | `/screen`                                      | `screen:read`                              |
| Usage history | `/usage-history/{classify,calculate,restrict}` | matching `:read` scope                     |

Classify, calculate, restrict, and screen are first-class resources on the
same base URL — one token, one host, one contract.