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

# Getting Started

> Use the Beach API to create accounts, send inventory into the vault, and request ship-outs.

## Welcome

Our API is currently in Beta and is not yet available to the wider public. More functionality will be added in the near future as we continuously build out our API. If you'd like to request access, offer feedback, or have any inquiries about the API, don't hesitate to contact us at [support@beachdepository.com](mailto:support@beachdepository.com).

<CardGroup cols={2}>
  <Card title="SDKs" icon="code" href="/sdks">
    Install the TypeScript client and call the API from Node.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    How an inbound shipment, an outbound request, an outbound shipment, and a transfer move.
  </Card>

  <Card title="Entities" icon="boxes-stacked" href="/entities/organization">
    The shape of each object the API returns.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Signatures, event types, and which status changes fire an event.
  </Card>

  <Card title="Permissions" icon="key" href="/permissions">
    The scopes on a key, and what each one allows.
  </Card>
</CardGroup>

## Base URL

```
https://api.beachdepository.com/v1
```

Paths in this reference are relative to `/v1`. `GET /` on the host root returns the service name, version, and environment.

## Authorization

Create an API key in the dashboard under **Settings > API Keys**. Each key belongs to one organization, so requests do not take an organization id.

Send the API key as a Bearer token.

```bash theme={null}
curl https://api.beachdepository.com/v1/fbo-accounts \
  -H "Authorization: Bearer ${BEACH_API_KEY}"
```

Keys use the prefix `pv_live_`, then 64 hex characters.

Each key has [permission scopes](/permissions). A request without the required scope returns `403`.

Disable a key to pause it, or revoke it to invalidate it permanently. Disabled and revoked keys return `401`.

## Idempotency

These creates accept an optional `Idempotency-Key` header, any unique string up to 255 characters: FBO accounts, addresses, aliases, inbound shipments, outbound requests, transfers, and webhooks. Cancel, label quote, and every other POST ignore the header.

Retrying a keyed create within 24 hours returns the original response. Replayed responses include `Idempotency-Replayed: true`. Reusing a key while the first request is still in progress returns `409`. Reusing it on a different endpoint returns `422`.

## Rate limits

Each key is allowed **60 requests per minute** by default. The limit is configurable per key in the dashboard. The window is a fixed minute and resets at the start of each minute.

| Header | Description |
| - | - |
| `X-RateLimit-Limit` | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp, in seconds, when the window resets |

A request over the limit returns `429`:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 32 seconds."
  }
}
```

## Pagination

List endpoints take `page` and `limit`. `page` defaults to 1. `limit` defaults to 25 and cannot exceed 100. Both must be positive integers. `page` times `limit` cannot exceed 10,000. A value outside those rules returns `422`.

The response wraps the rows in `data` and adds `pagination`:

```json theme={null}
{
  "data": [],
  "pagination": {
    "page": 1,
    "hasMore": false
  }
}
```

`hasMore` is `true` when another page exists. There is no total count. Request the next page by incrementing `page`.

Webhooks, addresses, and aliases return the full list and do not use these parameters.

## Errors

Failed requests return a JSON body:

```json theme={null}
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authorization header is required."
  }
}
```

| Code | Status | Meaning |
| - | - | - |
| `BAD_REQUEST` | 400 | Malformed request, such as invalid JSON |
| `UNAUTHENTICATED` | 401 | Missing or invalid API key |
| `FORBIDDEN` | 403 | The key lacks the required permission |
| `NOT_FOUND` | 404 | The resource does not exist |
| `CONFLICT` | 409 | The same `Idempotency-Key` is already in progress |
| `VALIDATION_ERROR` | 422 | The body or parameters failed validation |
| `RATE_LIMITED` | 429 | This key is over its rate limit |
| `INTERNAL_ERROR` | 500 | An unexpected server error |