# API Documentation

Source: [API Docs | Acelerun Technologies](https://www.acelerun.com/es/docs/api/)

Language: es

Welcome to the Acelerun API documentation. Our API allows you to programmatically manage your streams, viewers, and recordings.

**Base URL:** `https://api.acelerun.com/v1`

## Introduction

The Acelerun API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The API supports all major streaming protocols: `webrtc`, `srt`, `hls`, `ll-hls`, `icecast`, and `shoutcast`.

## Authentication

Authenticate your API requests using your API key in the Authorization header:

```
curl -X GET "https://api.acelerun.com/v1/streams" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Your API keys can be found in your [dashboard](https://www.acelerun.com/es/signup/). You can generate multiple API keys for different environments (development, staging, production).

## Errors

Acelerun uses conventional HTTP response codes to indicate the success or failure of API requests:

| Code | Description |
| --- | --- |
| 200 | Success — Request was successful |
| 400 | Bad Request — Invalid parameters |
| 401 | Unauthorized — Invalid or missing API key |
| 404 | Not Found — Resource does not exist |
| 429 | Rate Limited — Too many requests (100 req/min) |
| 500 | Server Error — Something went wrong on our end |

All error responses include a JSON body with `error` and `message` fields.

```
{
  "error": "invalid_request",
  "message": "The 'protocol' field is required"
}
```

## Create Stream

Create a new live stream.

POST `/streams`

```
curl -X POST "https://api.acelerun.com/v1/streams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Live Stream","protocol":"webrtc"}'
```

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| name | string | Yes | Name of the stream (max 255 chars) |
| protocol | string | Yes | Protocol: webrtc, srt, hls, ll-hls, icecast, shoutcast |
| recording | boolean | No | Enable recording (default: false) |
| region | string | No | Preferred region: na, eu, apac, mena (default: auto) |
| max_viewers | integer | No | Maximum concurrent viewers (plan limit applies) |
| webhook_url | string | No | URL to receive webhook notifications |

### Response

```
{
  "id": "str_abc123def456",
  "name": "My Live Stream",
  "protocol": "webrtc",
  "status": "idle",
  "recording": false,
  "region": "auto",
  "ingest_url": "webrtc://ingest.acelerun.com/str_abc123def456",
  "created_at": "2026-03-24T10:30:00Z"
}
```

## Get Stream

Retrieve details of a specific stream.

GET `/streams/:id`

```
curl -X GET "https://api.acelerun.com/v1/streams/str_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```
{
  "id": "str_abc123def456",
  "name": "My Live Stream",
  "protocol": "webrtc",
  "status": "live",
  "viewer_count": 1247,
  "bitrate": 4500,
  "resolution": "1920x1080",
  "uptime_seconds": 3600,
  "created_at": "2026-03-24T10:30:00Z"
}
```

## List Streams

List all streams in your account.

GET `/streams`

| Parameter | Type | Description |
| --- | --- | --- |
| status | string | Filter by status: idle, live, ended |
| protocol | string | Filter by protocol |
| limit | integer | Number of results (default: 25, max: 100) |
| offset | integer | Pagination offset |

## Update Stream

Update an existing stream.

PUT `/streams/:id`

```
curl -X PUT "https://api.acelerun.com/v1/streams/str_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Stream Name","recording":true}'
```

## Delete Stream

Delete a stream. This action is irreversible.

DELETE `/streams/:id`

```
curl -X DELETE "https://api.acelerun.com/v1/streams/str_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Get Playback URL

Get the WebRTC or SRT playback URL for a stream.

GET `/streams/:id/playback`

### Response

```
{
  "stream_id": "str_abc123def456",
  "protocol": "webrtc",
  "playback_url": "https://play.acelerun.com/str_abc123def456",
  "whep_url": "https://whep.acelerun.com/str_abc123def456",
  "expires_at": "2026-03-25T10:30:00Z"
}
```

## Get HLS URL

Get the HLS/LL-HLS playback URL for broad device compatibility.

GET `/streams/:id/hls`

### Response

```
{
  "stream_id": "str_abc123def456",
  "hls_url": "https://cdn.acelerun.com/str_abc123def456/master.m3u8",
  "ll_hls_url": "https://cdn.acelerun.com/str_abc123def456/ll-master.m3u8",
  "thumbnail_url": "https://cdn.acelerun.com/str_abc123def456/thumb.jpg"
}
```

## List Recordings

List all recordings for your account or a specific stream.

GET `/recordings`

| Parameter | Type | Description |
| --- | --- | --- |
| stream_id | string | Filter recordings by stream ID |
| limit | integer | Number of results (default: 25) |
| offset | integer | Pagination offset |

### Response

```
{
  "data": [
    {
      "id": "rec_xyz789",
      "stream_id": "str_abc123def456",
      "duration_seconds": 3600,
      "size_bytes": 1073741824,
      "download_url": "https://storage.acelerun.com/rec_xyz789.mp4",
      "created_at": "2026-03-24T11:30:00Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}
```

## Get Recording

Retrieve details of a specific recording.

GET `/recordings/:id`

## Delete Recording

Delete a recording. This action is irreversible and the recording file will be permanently removed.

DELETE `/recordings/:id`

## Webhooks

Configure webhooks to receive real-time notifications about stream events. Set the `webhook_url` when creating a stream, or configure it globally in your dashboard.

### Events

- `stream.started` Stream went live
- `stream.ended` Stream ended
- `stream.recording.ready` Recording is available for download
- `viewer.joined` A viewer joined the stream
- `viewer.left` A viewer left the stream
- `stream.error` Stream encountered an error

### Webhook Payload

```
{
  "event": "stream.started",
  "stream_id": "str_abc123def456",
  "timestamp": "2026-03-24T10:30:00Z",
  "data": {
    "name": "My Live Stream",
    "protocol": "webrtc",
    "viewer_count": 0
  }
}
```

Webhooks are sent as `POST` requests with a JSON body. Your endpoint should respond with a `200` status code. Failed deliveries are retried up to 3 times with exponential backoff.

## Need Help?

If you have questions about the API, contact us at [support@acelerun.com](mailto:support@acelerun.com)
