# Raw HTTP Examples

Some public route families are intentionally raw HTTP today. Use these examples when the TypeScript SDK or CLI does not wrap the operation your integration or agent needs yet.

## How to read these examples

Examples use `swk_...` for project API keys. Routes that say `admin project key` require a project API key with the `admin` role; a write key returns `403`.

Responses are trimmed to show the fields that matter for integration code.

## Project API keys

Project API-key lifecycle routes require an admin project API key. Create and rotate responses are the only time the raw key secret is returned.

**Create a write key**

```bash
curl https://api.hooksbase.com/v1/project/api-keys \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent runner",
    "role": "write"
  }'
```

**201 response**

```json
{
  "apiKey": "swk_...",
  "key": {
    "id": "key_123",
    "name": "Agent runner",
    "role": "write",
    "keyPrefix": "swk_pk_abc",
    "revokedAt": null
  }
}
```

**Rotate a key**

```bash
curl https://api.hooksbase.com/v1/project/api-keys/key_123/rotate \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent runner rotated",
    "role": "write"
  }'
```

## Audit logs

Audit logs require an admin project API key and Business+. They are read-only and cursor-paginated.

**List audit logs**

```bash
curl "https://api.hooksbase.com/v1/project/audit-logs?kind=webhook&limit=20" \
  -H "Authorization: Bearer swk_..."
```

**200 response**

```json
{
  "items": [
    {
      "id": "audit_123",
      "kind": "webhook",
      "action": "updated",
      "actor": {
        "type": "project_api_key",
        "apiKeyId": "key_123"
      },
      "metadata": {
        "changedFields": ["status"]
      },
      "createdAt": 1766600000000
    }
  ],
  "nextCursor": null
}
```

## Operator alerting

Operator alerting routes require an admin project API key. Creating, patching, resuming, restoring, and rotating alert webhooks require Pro+. The route family is raw HTTP; the SDK and CLI do not wrap it yet.

**Create an alert webhook**

```bash
curl https://api.hooksbase.com/v1/project/operator-webhooks \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On-call alerts",
    "targetUrl": "https://alerts.example.com/hooksbase",
    "eventTypes": [
      "terminal_failure_spike",
      "destination_health",
      "dlq_accumulation"
    ]
  }'
```

**201 response**

```json
{
  "id": "opwh_123",
  "name": "On-call alerts",
  "status": "active",
  "targetUrl": "https://alerts.example.com/hooksbase",
  "eventTypes": [
    "terminal_failure_spike",
    "destination_health",
    "dlq_accumulation"
  ],
  "signingSecret": "sws_..."
}
```

**List open incidents**

```bash
curl "https://api.hooksbase.com/v1/project/operator-incidents?status=open&limit=20" \
  -H "Authorization: Bearer swk_..."
```

## Metrics and backlog

Metrics and backlog use a `window` query value. Supported values are `1h`, `24h`, `7d`, and `30d`. The default is `24h`.

**Read webhook metrics**

```bash
curl "https://api.hooksbase.com/v1/webhooks/wh_123/metrics?window=24h" \
  -H "Authorization: Bearer swk_..."
```

**Read backlog history**

```bash
curl "https://api.hooksbase.com/v1/webhooks/wh_123/backlog?window=7d" \
  -H "Authorization: Bearer swk_..."
```

Use `GET /v1/usage` when you need project usage over explicit `from`/`to` timestamps.

**Read usage for a time range**

```bash
curl "https://api.hooksbase.com/v1/usage?from=1766515200000&to=1766601600000" \
  -H "Authorization: Bearer swk_..."
```

## Email allowlists

Listing an email allowlist is project-authenticated. Creating and deleting entries require Starter+.

**Add an allowlist entry**

```bash
curl https://api.hooksbase.com/v1/webhooks/wh_123/email-allowlist \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "*@example.com"
  }'
```

**201 response**

```json
{
  "id": "esal_123",
  "webhookId": "wh_123",
  "projectId": "proj_123",
  "pattern": "*@example.com",
  "createdAt": 1766600000000
}
```

**Delete an allowlist entry**

```bash
curl -X DELETE https://api.hooksbase.com/v1/webhooks/wh_123/email-allowlist/esal_123 \
  -H "Authorization: Bearer swk_..."
```

## Bulk replay and DLQ re-drive

Bulk operations require Starter+ and an `Idempotency-Key`. They return `202` with a bulk-operation view; poll the returned operation id until `job.status` is `completed` or `completed_with_errors`.

**Create a bulk replay job**

```bash
curl https://api.hooksbase.com/v1/deliveries/bulk-replay \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: replay-failed-orders-2026-04-25" \
  -d '{
    "filters": {
      "webhookId": "wh_123",
      "status": "failed"
    },
    "maxItems": 100
  }'
```

**Create a bulk DLQ re-drive job**

```bash
curl https://api.hooksbase.com/v1/dlq/bulk-re-drive \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dlq-redrive-orders-2026-04-25" \
  -d '{
    "filters": {
      "webhookId": "wh_123",
      "errorCode": "http_500"
    },
    "maxItems": 50
  }'
```

**Poll a bulk operation**

```bash
curl https://api.hooksbase.com/v1/bulk-operations/bulk_123 \
  -H "Authorization: Bearer swk_..."
```

## Event drains

Event drains are project-authenticated raw HTTP routes. Create, patch, and resume require Pro+; Pro allows one drain, Business allows three, and Enterprise is unbounded.

**Create a webhook drain**

```bash
curl https://api.hooksbase.com/v1/app/event-drains \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delivery stream",
    "sinkType": "webhook",
    "sinkConfig": {
      "url": "https://observability.example.com/hooksbase",
      "signingSecret": "drain-secret"
    },
    "eventTypes": [
      "delivery.created",
      "attempt.completed",
      "delivery.failed"
    ],
    "filterWebhookIds": ["wh_123"]
  }'
```

**201 response**

```json
{
  "id": "drain_123",
  "name": "Delivery stream",
  "status": "active",
  "sinkType": "webhook",
  "eventTypes": [
    "delivery.created",
    "attempt.completed",
    "delivery.failed"
  ],
  "filterWebhookIds": ["wh_123"],
  "consecutiveFailures": 0
}
```

**Pause and resume**

```bash
curl -X POST https://api.hooksbase.com/v1/app/event-drains/drain_123/pause \
  -H "Authorization: Bearer swk_..."

curl -X POST https://api.hooksbase.com/v1/app/event-drains/drain_123/resume \
  -H "Authorization: Bearer swk_..."
```