Technical Documentation Examples: 12 Structures and Templates

1# Acme Events SDK
2
3Send product events from Node.js services to Acme.
4
5## Install
6
7```bash
8npm install @acme/events
9```
10
11## First event
12
13```ts
14import { Acme } from "@acme/events";
15
16const client = new Acme({ apiKey: process.env.ACME_API_KEY });
17await client.track("account.created", { accountId: "acc_123" });
18```
19
20## Next
21
22- [Authentication](/authentication)
23- [Event schema](/events/schema)
24- [Retries](/events/retries)

1# Send your first event
2
3You will create an API key, install the Node SDK, send one event,
4and verify it in the dashboard.
5
6## Before you start
7
8- Node.js 20 or newer
9- An Acme workspace with permission to create API keys
10
11## 1. Create an API key
12...
13
14## 2. Install the SDK
15...
16
17## 3. Send an event
18...
19
20## 4. Verify the result
21
22Open **Events > Live** and confirm `account.created` appears.

1# Delivery guarantees
2
3Acme accepts events at least once. A successful response means the event
4was persisted, not that every downstream destination processed it.
5
6## What can be duplicated
7
8Retries can deliver the same event more than once. Use `event_id` as the
9idempotency key in consumers.
10
11## Ordering
12
13Ordering is preserved within one `account_id`, but not across accounts.
14
15## Choose a retry policy
16
17| Failure | Retry? | Reason |
18|---|---:|---|
19| 429 | Yes | Temporary rate limit |
20| 400 | No | Request must change |
21| 503 | Yes | Temporary service failure |

1# Create an event
2
3`POST /v1/events`
4
5Creates one event for an account.
6
7## Request
8
9| Field | Type | Required | Description |
10|---|---|---:|---|
11| `event_id` | string | yes | Unique idempotency key |
12| `name` | string | yes | Dot-separated event name |
13| `account_id` | string | yes | Owning account |
14| `properties` | object | no | Event-specific values |
15
16## Response
17
18`202 Accepted` means the event was persisted for asynchronous delivery.
19
20## Errors
21
22- `400 invalid_event_name`
23- `401 invalid_api_key`
24- `409 duplicate_event_id`

1# API authentication
2
3Acme uses bearer API keys for server-to-server requests.
4
5## Create a key
6
71. Open **Settings > API keys**.
82. Choose the narrowest required scopes.
93. Store the secret once; Acme does not show it again.
10
11## Send the key
12
13```bash
14curl https://api.acme.test/v1/events \
15  -H "Authorization: Bearer $ACME_API_KEY"
16```
17
18## Environments
19
20Test keys start with `test_`. Production keys start with `live_`.
21
22## Common failures
23
24| Status | Cause | Fix |
25|---|---|---|
26| 401 | Missing or invalid key | Replace the bearer token |
27| 403 | Missing scope | Create a key with the required scope |

1# API errors
2
3Every error response includes a stable `code`, a request-specific `message`,
4and a `request_id` support can use for tracing.
5
6```json
7{
8  "code": "rate_limit_exceeded",
9  "message": "Too many requests for workspace ws_123",
10  "request_id": "req_456"
11}
12```
13
14| Code | Retry | Next action |
15|---|---:|---|
16| `invalid_request` | no | Correct the named field |
17| `rate_limit_exceeded` | yes | Back off using the response headers |
18| `service_unavailable` | yes | Retry with jitter |

1# Node SDK
2
3## Install
4
5```bash
6npm install @acme/events
7```
8
9## Configure one client
10
11Create the client once and reuse it. The client manages connection pooling
12and retries safe failures by default.
13
14```ts
15export const acme = new Acme({
16  apiKey: process.env.ACME_API_KEY,
17  timeout: 5_000,
18});
19```
20
21## Handle an API error
22
23```ts
24try {
25  await acme.events.create(input);
26} catch (error) {
27  if (error instanceof Acme.RateLimitError) {
28    // Respect error.retryAfter before retrying.
29  }
30}
31```

1# `acme events send`
2
3Send one event from a file or standard input.
4
5## Usage
6
7```bash
8acme events send --file event.json
9cat event.json | acme events send --stdin
10```
11
12## Flags
13
14| Flag | Default | Description |
15|---|---|---|
16| `--file` | none | JSON input file |
17| `--stdin` | false | Read JSON from standard input |
18| `--output` | `text` | `text` or `json` |
19
20## Exit codes
21
22| Code | Meaning |
23|---:|---|
24| 0 | Event accepted |
25| 2 | Invalid arguments or input |
26| 3 | Authentication failed |
27| 4 | Remote API failed |

1# Receive webhooks
2
3## Verify the signature
4
5Use the raw request body and the `Acme-Signature` header. Reject requests
6whose timestamp is more than five minutes old.
7
8## Acknowledge quickly
9
10Return a 2xx response within five seconds. Queue slow work for later.
11
12## Handle retries
13
14Acme retries for 24 hours with exponential backoff. The same `event_id`
15can be delivered more than once.
16
17## Test locally
18
19```bash
20acme webhooks listen --forward-to localhost:3000/webhooks/acme
21```

1# Migrate from API v1 to v2
2
3## What changed
4
5- `customer` is now `account`
6- timestamps use RFC 3339 strings instead of Unix seconds
7- list responses use cursor pagination
8
9## Migration order
10
111. Accept both timestamp formats in consumers.
122. Move list calls to cursor pagination.
133. Replace `customer_id` with `account_id`.
144. Switch traffic to v2.
155. Remove the compatibility code after verification.
16
17## Rollback
18
19Keep the v1 key active until v2 traffic has passed production checks.

1# 2026-08-28
2
3## Cursor pagination for event lists
4
5`GET /v1/events` now returns `next_cursor`. Offset pagination remains
6available until 2026-11-30.
7
8**Who is affected:** integrations that request more than one page.
9
10**Action:** update the loop to pass `next_cursor` on the next request.
11
12**No action:** integrations that fetch only the first page.

1# Events do not appear in the dashboard
2
3## 1. Check the response
4
5- `202`: continue to delivery checks
6- `401`: replace the API key
7- `429`: wait for the reset time
8
9## 2. Confirm the environment
10
11Test events and production events appear in separate workspaces.
12
13## 3. Search by request ID
14
15Run:
16
17```bash
18acme requests get req_456
19```
20
21## 4. Contact support
22
23Send the request ID. Do not send the API key or full authorization header.

1# [Task or concept]
2
3[One paragraph defining the outcome or behavior.]
4
5## Before you start
6
7- [Requirement]
8- [Permission]
9- [Supported version]
10
11## [First meaningful step or concept]
12
13[Exact instruction or explanation.]
14
15```language
16[Verified example]
17```
18
19## Verify the result
20
21[Observable success condition.]
22
23## Failures and recovery
24
25| Symptom or error | Cause | Next action |
26|---|---|---|
27
28## Related documentation
29
30- [One prerequisite]
31- [One next task]
32- [One reference page]