Durablr API Documentation

Handle any Server-Sent Events stream without serverless timeout issues. Perfect for OpenAI, analytics, and real-time data streams.

🚀 Quick Start in 3 Steps

Get Your API Key

Subscribe to a Stream

Send a POST request to subscribe to any SSE endpoint. Choose webhook (real-time push) or resumable (stored in Redis).

curl -X POST https://api.durablr.run/stream/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"your_project","streamType":"webhook",...}'

Receive Events

Webhook streams push events to your URL in real-time. Resumable streams can be consumed via SSE anytime.

🌐 API Base URL

https://api.durablr.run

The API runs on a separate server from the web frontend. All stream operations use this base URL.

🔑 Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

How to get your API key:

1. Go to your Dashboard
2. Navigate to Settings → API Keys
3. Click "Create API Key"
4. Copy and use in your requests

🎯 Webhook vs Resumable Streams

Choose the right stream type for your use case:

Webhook Streams

✓ Real-time push to your webhook URL
✓ Lowest latency
✓ No storage needed
✗ Not resumable
Best for: Real-time notifications, alerts

Resumable Streams

✓ Pull via SSE endpoint anytime
✓ Fully resumable from any point
✓ Stored in Redis for 24 hours
✗ Requires polling
Best for: Long-running jobs, batch processing

🤖 Example: OpenAI Chat Streaming

Stream OpenAI chat completions to your webhook in real-time:

curl -X POST https://api.durablr.run/stream/subscribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DURABLR_API_KEY" \
  -d '{
    "projectId": "your_project_id",
    "streamType": "webhook",
    "method": "POST",
    "streamUrl": "https://api.openai.com/v1/chat/completions",
    "webhookUrl": "https://webhook.site/your-unique-url",
    "headers": {
      "Authorization": "Bearer YOUR_OPENAI_API_KEY",
      "Content-Type": "application/json"
    },
    "body": {
      "model": "gpt-4",
      "messages": [{"role": "user", "content": "Write a creative story"}],
      "stream": true,
      "max_tokens": 500
    }
  }'

Response:

{"streamId": "7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f"}

📡 Example: Simple GET Stream

Subscribe to any Server-Sent Events endpoint:

curl -X POST https://api.durablr.run/stream/subscribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DURABLR_API_KEY" \
  -d '{
    "projectId": "your_project_id",
    "streamType": "webhook",
    "streamUrl": "https://your-sse-endpoint.com/events",
    "webhookUrl": "https://webhook.site/your-unique-url",
    "headers": {
      "Authorization": "Bearer YOUR_ENDPOINT_TOKEN"
    }
  }'

🔄 Example: Resumable Stream

Create a resumable stream that stores data in Redis and can be consumed via SSE:

curl -X POST https://api.durablr.run/stream/subscribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DURABLR_API_KEY" \
  -d '{
    "projectId": "your_project_id",
    "streamType": "resumable",
    "streamUrl": "https://api.openai.com/v1/chat/completions",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer YOUR_OPENAI_API_KEY",
      "Content-Type": "application/json"
    },
    "body": {
      "model": "gpt-4",
      "messages": [{"role": "user", "content": "Tell me a story"}],
      "stream": true
    }
  }'

Consume the resumable stream:

curl https://api.durablr.run/stream/resume/7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f?fromId=0 \
  -H "Authorization: Bearer YOUR_DURABLR_API_KEY"

Streams all chunks as Server-Sent Events. Can reconnect anytime with last received ID to resume. Authentication is required.

🔗 Testing with Webhook.site

1.Go to webhook.site and copy your unique URL
2.Replace your-unique-url in the examples above
3.Run the curl command
4.Watch real-time events arrive at your webhook URL

📨 Webhook Response Format

Durablr forwards streaming chunks in real-time:

Stream Chunk (OpenAI example):

{
  "streamId": "7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f",
  "type": "chunk",
  "data": "data: {\"id\":\"chatcmpl-ABC123\",\"object\":\"chat.completion.chunk\",\"created\":1756648138,\"model\":\"gpt-4-0613\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" couldn\"},\"logprobs\":null,\"finish_reason\":null}]}\n\n",
  "timestamp": "2025-08-31T13:49:05.649Z"
}

Stream Completion:

{
  "streamId": "7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f",
  "type": "completed",
  "timestamp": "2025-08-31T13:49:15.123Z"
}

Notes:

• Each webhook call may contain multiple SSE chunks batched together
• Data is forwarded exactly as received from the source API
• Parse the data: lines to extract the actual JSON responses

🔒 Webhook Security

All webhooks include cryptographic signatures so you can verify they're authentic.

Security Headers:

X-Webhook-Signature: 8f3a2b1c9d4e5f6a... (HMAC-SHA256 hex)
X-Webhook-Timestamp: 2025-08-31T13:49:05.649Z

Verifying Signatures (Node.js):

const crypto = require('crypto');

function verifyWebhook(req) {
  const signature = req.headers['x-webhook-signature'];
  const apiKey = process.env.DURABLR_API_KEY;

  const hmac = crypto.createHmac('sha256', apiKey);
  hmac.update(JSON.stringify(req.body));
  const expected = hmac.digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Best Practices:

✓ Always verify signatures before processing webhook data
✓ Use timing-safe comparison to prevent timing attacks
✓ Store API keys in environment variables, never in code
✓ Use HTTPS webhook URLs to prevent interception
✓ Optionally check timestamps to reject old webhooks (prevent replay attacks)

⚙️ Management API

Monitor and control your streams programmatically

Get Active Streams

curl https://api.durablr.run/stream/active \
  -H "Authorization: Bearer YOUR_DURABLR_API_KEY"

{"activeStreams": ["7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f"], "count": 1}

Get Stream Details

curl https://api.durablr.run/stream/7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f \
  -H "Authorization: Bearer YOUR_DURABLR_API_KEY"

{"streamId": "7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f", "projectId": "your_project_id", "status": "active", "streamType": "webhook", "streamUrl": "https://...", "webhookUrl": "https://...", "createdAt": "2025-01-15T10:30:00Z"}

Stream statuses: active, completed, error, stopped

Stop a Stream

Streams auto-complete when the source finishes, so manual stopping is optional.

curl -X DELETE \
  https://api.durablr.run/stream/subscribe/7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f \
  -H "Authorization: Bearer YOUR_DURABLR_API_KEY"

{"message": "Stream stopped", "streamId": "7f8c9d2e-4b5a-1c3d-9e8f-2a1b3c4d5e6f"}

🌟 Use Cases

🤖

OpenAI Streaming

Handle long AI responses without timeouts

📊

Analytics Streams

Real-time analytics and metrics feeds

🔄

Data Processing

Long-running data transformation jobs

📈

Stock Feeds

Real-time financial data streams

📡

IoT Events

Device telemetry and sensor data

💬

Chat APIs

Streaming chat and messaging systems

Back to Home