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

# Agent API Reference

Zero-auth programmatic endpoints designed for AI agents — create ephemeral webhooks, inspect events, configure responses, and forward to your app.

The Agent API exposes hookstream's webhook testing infrastructure with agent-friendly aliases under `https://hookstream.io/v1/agent/*`. It's the same surface as `/v1/test/sessions` — same rate limits, same lifetime, same features — but named and documented for programmatic use by AI agents.

**No authentication required.** Rate limited to 10 sessions per IP per hour. Sessions live for 14 days or 2,000 requests, whichever comes first. Sessions can be graduated into a full hookstream account later — no data is lost.

If your agent needs higher limits, longer retention, or access to the full platform (connections, destinations, transforms, metrics), create a free hookstream account and use an API key with the regular [REST API](/api/overview). The Agent API is designed for zero-friction prototyping and ephemeral workflows.

## Base URL

```text
https://hookstream.io/v1/agent/sessions
```

The same endpoints are also mounted at `https://hookstream.io/v1/test/sessions` — use whichever feels clearer in your code.

## Typical agent workflow

**Create a session**

`POST https://hookstream.io/v1/agent/sessions` returns a `session_id` and a live webhook `url`.
  **Configure the response (optional)**

`PATCH https://hookstream.io/v1/agent/sessions/:id/response` to set a custom status code, content type, and body returned to webhook senders.
  **Hand the URL to an external service**

Give the returned `url` to a provider like Stripe, GitHub, or Shopify — or send test requests yourself.
  **Poll for events**

`GET https://hookstream.io/v1/agent/sessions/:id` returns session metadata plus the most recent events. Supports filters and cursor pagination.
  **Inspect or forward**

Read method, headers, body, and timing from each event. Optionally `PATCH .../forwarding` to relay to your local app in real time.
  **Export or clean up**

`GET .../export` dumps NDJSON or CSV. `DELETE .../:id` removes the session early.

## Endpoints

### Create a session

POST `https://hookstream.io/v1/agent/sessions`

Creates a new ephemeral webhook endpoint. No body required, no auth.

**Response**

```json
{
  "session_id": "abc123...",
  "url": "https://hookstream.io/v1/ingest/abc123...",
  "expires_at": "2026-03-16T00:00:00.000Z",
  "request_limit": 2000,
  "request_count": 0
}
```

### List events for a session

GET `https://hookstream.io/v1/agent/sessions/:id`

Returns session metadata and received events. Supports filtering and pagination.

Filter by HTTP method (e.g. `POST`, `PUT`).
Filter by response status range: `2xx`, `4xx`, or `5xx`.
Full-text search in headers and body.
Results per page. Max 100, default 50.
Pagination cursor from a previous response.

**Response**

```json
{
  "session": {
    "id": "abc123...",
    "url": "https://hookstream.io/v1/ingest/abc123...",
    "expires_at": "2026-03-16T00:00:00.000Z",
    "request_count": 5
  },
  "events": [
    {
      "id": "evt_...",
      "method": "POST",
      "headers": { "content-type": "application/json" },
      "body": "{\"type\":\"order.created\"}",
      "received_at": "2026-03-02T12:00:00.000Z"
    }
  ],
  "pagination": { "has_more": false }
}
```

### Configure custom response

PATCH `https://hookstream.io/v1/agent/sessions/:id/response`

Set what hookstream returns to webhook senders that hit this endpoint.

HTTP status code between 200 and 599. Default `200`.
Response content type. Default `application/json`.
Response body. Max 4KB.

**Example request**

```json
{
  "status_code": 200,
  "content_type": "application/json",
  "body": "{\"ok\": true}"
}
```

### Configure forwarding

PATCH `https://hookstream.io/v1/agent/sessions/:id/forwarding`

Real-time relay of incoming webhooks to another URL. Runs in `waitUntil`, so it doesn't block ingest.

Target URL (http or https). Pass `null` to disable forwarding.

**Example request**

```json
{ "url": "https://my-app.com/webhooks" }
```

### Export events

GET `https://hookstream.io/v1/agent/sessions/:id/export`

Dumps all session events.

`ndjson` (default) or `csv`.

### Delete a session

DELETE `https://hookstream.io/v1/agent/sessions/:id`

Removes the session and all its events. Idempotent.

## Full example: agent creates a session, sends a webhook, and checks events

```bash cURL
# 1. Create session
SESSION=$(curl -s -X POST https://hookstream.io/v1/agent/sessions)
URL=$(echo $SESSION | jq -r '.url')
ID=$(echo $SESSION | jq -r '.session_id')

# 2. Send a test webhook
curl -X POST $URL \
  -H 'Content-Type: application/json' \
  -d '{"type": "order.created", "data": {"id": "ord_123"}}'

# 3. Check what landed
curl -s "https://hookstream.io/v1/agent/sessions/$ID" | jq '.events'
```

```javascript JavaScript
// 1. Create an ephemeral endpoint
const res = await fetch("https://hookstream.io/v1/agent/sessions", {
  method: "POST",
});
const { session_id, url } = await res.json();
console.log("Webhook URL:", url);

// 2. Send a test webhook
await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ type: "order.created", data: { id: "ord_123" } }),
});

// 3. Fetch received events
const eventsRes = await fetch(
  `https://hookstream.io/v1/agent/sessions/${session_id}`,
);
const { events } = await eventsRes.json();
console.log(`Received ${events.length} events`);
```

```python Python
import requests

base = "https://hookstream.io/v1/agent/sessions"

# 1. Create session
session = requests.post(base).json()
session_id, url = session["session_id"], session["url"]
print("Webhook URL:", url)

# 2. Send a test webhook
requests.post(
    url,
    json={"type": "order.created", "data": {"id": "ord_123"}},
)

# 3. Fetch events
events = requests.get(f"{base}/{session_id}").json()["events"]
print(f"Received {len(events)} events")
```

## Full-account access for agents

If your agent needs the full platform — connections, transforms, destinations, metrics, real-time streaming — create a free account and issue an API key. Then the agent can hit the full REST API at `https://hookstream.io/v1/*` with an `X-API-Key` header.

```javascript JavaScript
const API = "https://hookstream.io/v1";
const headers = {
  "X-API-Key": process.env.HOOKSTREAM_API_KEY,
  "Content-Type": "application/json",
};

// Create a source
const source = await fetch(`${API}/sources`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "My Agent Source" }),
}).then((r) => r.json());

// Fetch recent events
const events = await fetch(`${API}/events?limit=20`, { headers }).then((r) =>
  r.json(),
);

// Open a real-time WebSocket stream (token via query param)
const ws = new WebSocket(
  `wss://hookstream.io/v1/ws?token=${process.env.HOOKSTREAM_API_KEY}`,
);
ws.addEventListener("message", (ev) => {
  console.log("event:", JSON.parse(ev.data));
});
```

```python Python
import os, requests

API = "https://hookstream.io/v1"
headers = {
    "X-API-Key": os.environ["HOOKSTREAM_API_KEY"],
    "Content-Type": "application/json",
}

# Create a source
source = requests.post(
    f"{API}/sources",
    headers=headers,
    json={"name": "My Agent Source"},
).json()

# Fetch recent events
events = requests.get(f"{API}/events?limit=20", headers=headers).json()
print(f"Fetched {len(events['data'])} events")
```

API keys are plain HTTP headers, so they work with every agent framework — LangChain tool specs, OpenAI function calls, Anthropic tool use, MCP servers, and bespoke agents alike. No SDK required.

## Rate limits and lifetime

- **10 sessions per IP per hour** on session creation
- **2,000 requests per session** — after that, new webhooks are rejected
- **14-day TTL** — sessions expire automatically; data is cleaned up by a Cron job
- **Early deletion** via `DELETE .../:id`
- **Graduation** — calling `POST /v1/test/sessions/:id/claim` with an authenticated session moves the session and all its events into the user's organization. The webhook URL keeps working.

## Session graduation

An ephemeral session can become a persistent source. When a user signs up and authenticates, calling `POST https://hookstream.io/v1/test/sessions/:id/claim` attaches the session to their org. The `url` stays identical, all received events come with it, and it shows up as a regular source in the dashboard. This is useful when an agent prototype graduates into production.

## Related

- [AI & LLM Integration](/ai/overview)
- [Skills & IDE Integration](/ai/skills)
- [Webhook Testing guide](/guides/webhook-testing)