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

# HaulStow Developer API

> A beginner-friendly guide to adding HaulStow deliveries to your app.

The HaulStow Developer API lets your software talk to HaulStow. Your backend can ask for a price, create a delivery, check its status, and receive automatic status updates.

You do **not** need to understand HaulStow's internal systems. If you can send an HTTP request and read JSON, you can use this API.

<Note>
  This is a server-to-server API. Your frontend calls your backend, and your backend calls HaulStow. Never put a HaulStow API key in browser JavaScript, a mobile app, or a public repository.
</Note>

## What you need

Before you begin, get these from the HaulStow developer portal:

1. A developer application.
2. A **test API key** beginning with `hsg_test_key_`.
3. A tool for sending HTTP requests. The quickstart uses `curl`, which is already available on most macOS and Linux computers.

Start with the sandbox. It behaves like the live API but does not dispatch a rider, charge money, send messages, or create a real delivery.

## Base URLs

| Environment          | Base URL                                   | Credential         |
| -------------------- | ------------------------------------------ | ------------------ |
| Sandbox (start here) | `https://sandbox.developer.haulstow.co/v1` | `hsg_test_key_...` |
| Live                 | `https://developer.haulstow.co/v1`         | `hsg_live_key_...` |

The URL and key must match. A live key cannot access sandbox data, and a test key cannot access live data. There is no `environment` field to add to your JSON.

## The three ideas to remember

### 1. Put the key in the Authorization header

```http theme={null}
Authorization: Bearer hsg_test_key_your_key_here
```

`Bearer` is required, followed by one space and the complete API key.

### 2. Send an idempotency key when creating something

An idempotency key is a unique label for one action. It makes retrying safe if your network disconnects.

```http theme={null}
Idempotency-Key: order-1842-create
```

Reuse that value only when retrying the exact same request. Use a new value for a new recipient, address, delivery, or sandbox transition.

### 3. Read the `data` field

Every response has the same outer shape, called an **envelope**. On success, the useful result is inside `data`.

## Response envelope

```json Success theme={null}
{
  "success": true,
  "statusCode": 200,
    "message": "Delivery returned",
  "data": {
    "id": "dlv_3f1a821cdb58498cbb52f4706545a089",
    "status": "in_transit"
  }
}
```

```json Error theme={null}
{
  "success": false,
  "statusCode": 422,
  "message": "Delivery request is invalid",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": {
      "fields": []
    }
  }
}
```

On failure, `error.code` is the short, stable value your program should check. `message` is the human-readable explanation.

Every response also includes `X-Request-ID`. Save it in your logs. If you contact HaulStow support about a request, include this value so the request can be found quickly.

## Common words

| Word        | Meaning                                                                |
| ----------- | ---------------------------------------------------------------------- |
| Application | The integration you create in the developer portal.                    |
| Recipient   | The person receiving a package.                                        |
| Address     | A reusable drop-off location belonging to a recipient.                 |
| Delivery    | One package movement from pickup to drop-off.                          |
| Sandbox     | A safe test environment with simulated deliveries.                     |
| Webhook     | An HTTP request HaulStow sends to your server when a delivery changes. |
| Scope       | A permission attached to an API key, such as `deliveries:read`.        |

## Start integrating

1. Follow the [10-minute quickstart](/quickstart) to create a simulated delivery.
2. Read [authentication](/authentication) before saving a key in your app.
3. Read [idempotency](/idempotency) before creating live deliveries.
4. Use [webhooks](/webhooks) for automatic updates, or [polling](/polling) as a simpler fallback while learning.
5. Open [common errors](/errors) when a request does not work.
6. Use the [API reference](/reference) when you need every field and status code.