# API Reference

The Streampixel API lets you automate build management and integrate Streampixel into your CI/CD pipelines, internal tools, or custom platforms.

## Base URL

```
https://api.streampixel.io/pixelStripeApi
```

## Authentication

All API requests require an **API Key** passed in the request body. See [API Authentication](https://docs.streampixel.io/resources/api-reference/api-authentication) for setup.

## Endpoints

| Method | Endpoint                    | Description                                       |
| ------ | --------------------------- | ------------------------------------------------- |
| `POST` | `/projects/upload-file`     | Upload a packaged UE build (`.zip`) to a project  |
| `POST` | `/projects/distribute-file` | Distribute an uploaded build to streaming servers |

{% content-ref url="api-reference/upload-file-api" %}
[upload-file-api](https://docs.streampixel.io/resources/api-reference/upload-file-api)
{% endcontent-ref %}

{% content-ref url="api-reference/distribute-file-api" %}
[distribute-file-api](https://docs.streampixel.io/resources/api-reference/distribute-file-api)
{% endcontent-ref %}

## Webhooks

Receive real-time HTTP notifications when build pipeline events occur — uploads, approvals, rejections, and distribution.

{% content-ref url="api-reference/webhooks" %}
[webhooks](https://docs.streampixel.io/resources/api-reference/webhooks)
{% endcontent-ref %}

## Quick Start

{% hint style="info" %}
Before making API calls, you'll need three things from your Streampixel dashboard: an **API Key**, your **User ID**, and a **Project ID**. See the guides below.
{% endhint %}

{% content-ref url="api-reference/api-authentication" %}
[api-authentication](https://docs.streampixel.io/resources/api-reference/api-authentication)
{% endcontent-ref %}

{% content-ref url="api-reference/finding-your-user-and-project-ids" %}
[finding-your-user-and-project-ids](https://docs.streampixel.io/resources/api-reference/finding-your-user-and-project-ids)
{% endcontent-ref %}

## Typical Workflow

1. **Upload** a `.zip` build via the [Upload File API](https://docs.streampixel.io/resources/api-reference/upload-file-api) with `autoRelease: true`
2. **Wait** for approval — listen via [Webhooks](https://docs.streampixel.io/resources/api-reference/webhooks) for `build.approved`
3. The build is **automatically distributed** to streaming servers

{% hint style="info" %}
When `autoRelease` is `true` (the default), distribution happens automatically after approval — you don't need to call the Distribute API.
{% endhint %}

### When to Use the Distribute File API

The [Distribute File API](https://docs.streampixel.io/resources/api-reference/distribute-file-api) is only needed when:

* You uploaded with `autoRelease: false` and want to distribute manually
* You want to **re-distribute a previous build** (e.g., rolling back to an older version)

## Rate Limits

| Endpoint                    | Limit                            |
| --------------------------- | -------------------------------- |
| `/projects/distribute-file` | 1 request per 2 minutes per user |

## Error Format

All error responses return a JSON object with a `message` field:

```json
{
  "message": "Description of what went wrong"
}
```

Common HTTP status codes:

| Code  | Meaning                                     |
| ----- | ------------------------------------------- |
| `200` | Success                                     |
| `400` | Bad request — missing or invalid parameters |
| `401` | Unauthorized — invalid API key or user ID   |
| `403` | Forbidden — access denied to the resource   |
| `404` | Not found — project or file doesn't exist   |
| `429` | Rate limit exceeded                         |
| `500` | Internal server error                       |