Skip to content

Commit e5fc57d

Browse files
alexboucharddalexbouchardd
authored
feat: Add API ref content and openapi schema updates (#883)
* feat: Add API ref content and openapi schema updates * chore: Update content code blocks and clarify base url * chore: Clean health check endpoint description * chore: Tweak concepts docs * fix: Remove UUID terminology openapi spec * fix: Fix merge conflict * fix: Fix typos
1 parent 60ad339 commit e5fc57d

11 files changed

Lines changed: 609 additions & 108 deletions

File tree

‎docs/apis/api-reference.json‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
[
2+
{
3+
"label": "Introduction",
4+
"sections": [
5+
{ "type": "content", "slug": "introduction" },
6+
{ "type": "content", "slug": "authentication" },
7+
{ "type": "content", "slug": "errors" },
8+
{ "type": "content", "slug": "rate-limit" },
9+
{ "type": "content", "slug": "openapi" },
10+
{ "type": "content", "slug": "sdks" }
11+
]
12+
},
13+
{
14+
"label": "Configure",
15+
"sections": [
16+
{ "type": "tag", "tag": "Tenants", "schema": "Tenant" },
17+
{ "type": "tag", "tag": "Destinations", "schema": "Destination" },
18+
{ "type": "tag", "tag": "Configuration" }
19+
]
20+
},
21+
{
22+
"label": "Publishing",
23+
"sections": [
24+
{ "type": "tag", "tag": "Publish" },
25+
{ "type": "tag", "tag": "Retry" }
26+
]
27+
},
28+
{
29+
"label": "Inspect",
30+
"sections": [
31+
{ "type": "tag", "tag": "Events", "schema": "Event" },
32+
{ "type": "tag", "tag": "Attempts", "schema": "Attempt" },
33+
{ "type": "tag", "tag": "Metrics" }
34+
]
35+
},
36+
{
37+
"label": "Resources",
38+
"sections": [
39+
{ "type": "tag", "tag": "Schemas", "label": "Destination Types", "schema": "DestinationTypeSchema" },
40+
{ "type": "tag", "tag": "Topics" },
41+
{ "type": "tag", "tag": "Health" }
42+
]
43+
}
44+
]

‎docs/apis/content/authentication.mdoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<section>
2+
<div>
3+
4+
## Authentication
5+
6+
The Outpost API supports two authentication methods depending on the operation:
7+
8+
| Method | Description |
9+
|--------|-------------|
10+
| **Admin&nbsp;API&nbsp;Key** | Bearer token for all admin operations. Set via the `API_KEY` environment variable (self-hosted) or the Hookdeck dashboard (managed). |
11+
| **Tenant&nbsp;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. |
12+
13+
Include your credentials as a Bearer token in every request.
14+
15+
</div>
16+
<aside>
17+
18+
{% codeBlock heading="Using Admin API Key" lang="shell" %}
19+
```bash
20+
curl https://api.outpost.hookdeck.com/2025-07-01/tenants \
21+
-H "Authorization: Bearer $API_KEY"
22+
```
23+
{% /codeBlock %}
24+
25+
{% codeBlock heading="Using Tenant JWT" lang="shell" %}
26+
```bash
27+
curl https://api.outpost.hookdeck.com/2025-07-01/tenants/t1/destinations \
28+
-H "Authorization: Bearer $TENANT_JWT"
29+
```
30+
{% /codeBlock %}
31+
32+
</aside>
33+
</section>

‎docs/apis/content/errors.mdoc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<section>
2+
<div>
3+
4+
## Errors
5+
6+
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.
7+
8+
| Field | Type | Description |
9+
|-------|------|-------------|
10+
| `status` | Integer | HTTP status code for the response. |
11+
| `message` | String | Human-readable error message. |
12+
| `data` | Array or object | Optional details about the error. Validation errors use an array of messages. |
13+
14+
Common error responses include:
15+
16+
| Status | Description |
17+
|--------|-------------|
18+
| `400` | Malformed JSON or invalid request parameters. |
19+
| `401` | Missing or invalid authentication credentials. |
20+
| `404` | Requested resource not found. |
21+
| `422` | Request body fails validation. |
22+
| `500` | Unexpected server error. |
23+
24+
</div>
25+
<aside>
26+
27+
{% codeBlock heading="Example validation error response" lang="JSON" %}
28+
```json
29+
{
30+
"status": 422,
31+
"message": "validation error",
32+
"data": [
33+
"url is required"
34+
]
35+
}
36+
```
37+
{% /codeBlock %}
38+
39+
</aside>
40+
</section>

‎docs/apis/content/introduction.mdoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Introduction
2+
3+
The Outpost REST API is a JSON API for managing tenants, destinations, and publishing events to your webhook infrastructure.
4+
5+
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.
6+
7+
**Managed URL:** `https://api.outpost.hookdeck.com/2025-07-01`
8+
9+
**Self-hosted URL:** `https://outpost.your-domain.com/api/v1`
10+

‎docs/apis/content/openapi.mdoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<section>
2+
<div>
3+
4+
## OpenAPI Schema
5+
6+
The Outpost OpenAPI schema is available and can be used to generate SDKs, import into Postman, or work with any OpenAPI-compatible tooling.
7+
8+
The schema is available in the [Outpost GitHub repository](https://github.com/hookdeck/outpost/blob/main/docs/apis/openapi.yaml).
9+
10+
> To import the schema into Postman, use File → Import → Link → paste the URL above
11+
12+
</div>
13+
<aside>
14+
15+
{% codeBlock heading="Download the schema" lang="Shell" %}
16+
```bash
17+
# Download the schema
18+
curl https://github.com/hookdeck/outpost/blob/main/docs/apis/openapi.yaml \
19+
-o outpost-openapi.json
20+
```
21+
{% /codeBlock %}
22+
23+
</aside>
24+
</section>

‎docs/apis/content/rate-limit.mdoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<section>
2+
<div>
3+
4+
## Rate Limits
5+
6+
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.
7+
8+
> 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.
9+
10+
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.
11+
12+
| Header | Description |
13+
| ----------------------- | ---------------------------------------------------------- |
14+
| `X-RateLimit-Limit` | Maximum requests allowed in the current window |
15+
| `X-RateLimit-Remaining` | Requests remaining in the current window |
16+
| `X-RateLimit-Reset` | Unix timestamp when the current window resets |
17+
| `Retry-After` | Seconds to wait before retrying (present on 429 responses) |
18+
19+
20+
</div>
21+
<aside>
22+
23+
```text
24+
HTTP/1.1 429 Too Many Requests
25+
Retry-After: 1
26+
X-RateLimit-Limit: 1000
27+
X-RateLimit-Remaining: 0
28+
X-RateLimit-Reset: 1704067260
29+
30+
{
31+
"error": "rate limit exceeded"
32+
}
33+
```
34+
35+
</aside>
36+
</section>

‎docs/apis/content/sdks.mdoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<section>
2+
<div>
3+
4+
## SDKs
5+
6+
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.
7+
8+
| Language | Package | Repository |
9+
|----------|---------|------------|
10+
| TypeScript | [`@hookdeck/outpost-sdk`](https://www.npmjs.com/package/@hookdeck/outpost-sdk) | [GitHub](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-typescript) |
11+
| Python | [`outpost-sdk`](https://pypi.org/project/outpost-sdk/) | [GitHub](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-python) |
12+
| Go | [`outpost-go`](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-go) | [GitHub](https://github.com/hookdeck/outpost/tree/main/sdks/outpost-go) |
13+
14+
</div>
15+
<aside>
16+
17+
{% codeBlock heading="Install the Node.js SDK" lang="Shell" %}
18+
```bash
19+
npm install @hookdeck/outpost-sdk
20+
```
21+
{% /codeBlock %}
22+
23+
{% codeBlock heading="Install the Python SDK" lang="Shell" %}
24+
```bash
25+
pip install outpost-sdk
26+
```
27+
{% /codeBlock %}
28+
29+
{% codeBlock heading="Install the Go SDK" lang="Shell" %}
30+
```bash
31+
go get github.com/hookdeck/outpost/sdks/outpost-go
32+
```
33+
{% /codeBlock %}
34+
35+
</aside>
36+
</section>

0 commit comments

Comments
 (0)