# Outpost API Reference

## Introduction

The Outpost REST API is a JSON API for managing tenants, destinations, and publishing events to your webhook infrastructure.

Outpost API versions are included in the base URL. Managed deployments use calendar versioning (i.e. `/2025-07-01`), while OSS/self-hosted deployments use `/v1` as the API prefix.

Managed URL: `https://api.outpost.hookdeck.com/2025-07-01`

Self-hosted URL: `https://outpost.your-domain.com/api/v1`

## Authentication

The Outpost API supports two authentication methods depending on the operation:

| Method | Description |
| --- | --- |
| Admin API Key | Bearer token for all admin operations. Set via the `API_KEY` environment variable (self-hosted) or the Hookdeck dashboard (managed). |
| Tenant JWT | Per-tenant JWT token valid for 24 hours. Used for tenant-scoped operations and portal access. Generated via the [Get Tenant JWT Token](#gettenantportalurl) endpoint. |

Include your credentials as a Bearer token in every request.

```bash
curl https://api.outpost.hookdeck.com/2025-07-01/tenants \
  -H "Authorization: Bearer $API_KEY"

```

```bash
curl https://api.outpost.hookdeck.com/2025-07-01/tenants/t1/destinations \
  -H "Authorization: Bearer $TENANT_JWT"

```

## Errors

Outpost returns JSON error responses with a consistent shape across API endpoints. The `status` field matches the HTTP status code, `message` describes the error, and `data` is included when additional details are available.

| Field | Type | Description |
| --- | --- | --- |
| `status` | Integer | HTTP status code for the response. |
| `message` | String | Human-readable error message. |
| `data` | Array or object | Optional details about the error. Validation errors use an array of messages. |

Common error responses include:

| Status | Description |
| --- | --- |
| `400` | Malformed JSON or invalid request parameters. |
| `401` | Missing or invalid authentication credentials. |
| `404` | Requested resource not found. |
| `422` | Request body fails validation. |
| `500` | Unexpected server error. |

```json
{
  "status": 422,
  "message": "validation error",
  "data": [
    "url is required"
  ]
}

```

## Rate Limits

The Outpost API applies rate limits per API key to ensure system stability. The default rate limit is 240 requests per minute. If you need a higher rate limit, [contact us](/contact) to increase it.

> Rate limits are only applicable with managed deployments. Self-hosted deployments do not have rate limits and the operator is responsible for managing the service capacity.

When a rate limit is exceeded, the API returns a `429 Too Many Requests` response. Retry the request after the interval indicated in the `Retry-After` header.

| 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 when the current window resets |
| `Retry-After` | Seconds to wait before retrying (present on 429 responses) |

```text
HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067260

{
  "error": "rate limit exceeded"
}

```

## OpenAPI Schema

The Outpost OpenAPI schema is available and can be used to generate SDKs, import into Postman, or work with any OpenAPI-compatible tooling.

The schema is available in the [Outpost GitHub repository](https://github.com/hookdeck/outpost/blob/main/docs/apis/openapi.yaml).

> To import the schema into Postman, use File → Import → Link → paste the URL above

```bash
# Download the schema
curl https://github.com/hookdeck/outpost/blob/main/docs/apis/openapi.yaml \
  -o outpost-openapi.json

```

## SDKs

Official SDKs for the Outpost API are available for Go, TypeScript, and Python. All SDKs are generated by [Speakeasy](https://speakeasy.com) from the OpenAPI schema and published to their respective package registries.

| Language | Package | Repository |
| --- | --- | --- |
| TypeScript | [`@hookdeck/outpost-sdk`](https://www.npmjs.com/package/@hookdeck/outpost-sdk) | [GitHub](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-typescript) |
| Python | [`outpost-sdk`](https://pypi.org/project/outpost-sdk/) | [GitHub](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-python) |
| Go | [`outpost-go`](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-go) | [GitHub](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-go) |

```bash
npm install @hookdeck/outpost-sdk

```

```bash
pip install outpost-sdk

```

```bash
go get github.com/hookdeck/outpost/sdks/outpost-go

```

## API Resources

### Configure

* [Configure](/docs/outpost/api/configure.md)
  * [Tenants](/docs/outpost/api/configure.md#tenants)
  * [Destinations](/docs/outpost/api/configure.md#destinations)
  * [Configuration](/docs/outpost/api/configure.md#configuration)

### Publishing

* [Publishing](/docs/outpost/api/publishing.md)
  * [Publish](/docs/outpost/api/publishing.md#publish)
  * [Retry](/docs/outpost/api/publishing.md#retry)

### Inspect

* [Inspect](/docs/outpost/api/inspect.md)
  * [Events](/docs/outpost/api/inspect.md#events)
  * [Attempts](/docs/outpost/api/inspect.md#attempts)
  * [Metrics](/docs/outpost/api/inspect.md#metrics)

### Resources

* [Resources](/docs/outpost/api/resources.md)
  * [Destination Types](/docs/outpost/api/resources.md#schemas)
  * [Topics](/docs/outpost/api/resources.md#topics)
  * [Health](/docs/outpost/api/resources.md#health)