# Distribute File API

{% openapi src="<https://4054772100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUAxFCxNtDJTPCgUnSsK1%2Fuploads%2Fgit-blob-2a23140791b57b4d43d3eb7a3a5ef34462c26407%2Fopenapi.json?alt=media>" path="/projects/distribute-file" method="post" %}
[openapi.json](https://4054772100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUAxFCxNtDJTPCgUnSsK1%2Fuploads%2Fgit-blob-2a23140791b57b4d43d3eb7a3a5ef34462c26407%2Fopenapi.json?alt=media)
{% endopenapi %}

## Overview

Push an uploaded build to Streampixel's streaming servers manually.

{% hint style="info" %}
If you uploaded with `autoRelease: true` (the default), builds are distributed automatically after approval — you **don't need this endpoint**. Use it only when `autoRelease` is `false` or when you want to re-distribute a previous build (e.g., rolling back to an older version).
{% endhint %}

{% hint style="info" %}
Distribution is **asynchronous**. A `200` response means the process has been triggered, not completed. Use [Webhooks](https://docs.streampixel.io/resources/api-reference/webhooks) to track when distribution finishes.
{% endhint %}

## Prerequisites

Before calling this endpoint, ensure:

* The build has been **uploaded** via the [Upload File API](https://docs.streampixel.io/resources/api-reference/upload-file-api)
* The build has finished processing (has a valid URL)
* Your project is **enabled** (not disabled by an admin)
* You have a valid [API Key](https://docs.streampixel.io/resources/api-reference/api-authentication)

## Code Examples

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.streampixel.io/pixelStripeApi/projects/distribute-file \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
    "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
    "apiKey": "your-api-key",
    "userId": "663d0a1b2c3e4f5a6b7c8d9e"
  }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  'https://api.streampixel.io/pixelStripeApi/projects/distribute-file',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      projectId: '664f1a2b3c4d5e6f7a8b9c0d',
      uploadId: '665a2b3c4d5e6f7a8b9c0e1f',
      apiKey: 'your-api-key',
      userId: '663d0a1b2c3e4f5a6b7c8d9e',
    }),
  }
);

const data = await response.json();
console.log(data);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.post(
    'https://api.streampixel.io/pixelStripeApi/projects/distribute-file',
    json={
        'projectId': '664f1a2b3c4d5e6f7a8b9c0d',
        'uploadId': '665a2b3c4d5e6f7a8b9c0e1f',
        'apiKey': 'your-api-key',
        'userId': '663d0a1b2c3e4f5a6b7c8d9e',
    }
)

print(response.json())
```

{% endtab %}
{% endtabs %}

## How Distribution Works

1. **Validation** — Streampixel verifies your API key, project ownership, and that the file exists
2. **Region routing** — The build is routed to your project's configured region
3. **Queue** — The distribution task is added to the processing queue
4. **Streaming servers** — The build is pushed to servers and becomes available for streaming

### Supported Regions

| Region         | Description            |
| -------------- | ---------------------- |
| `us-east-1`    | United States (East)   |
| `europe`       | Europe                 |
| `asia-pacific` | Asia Pacific (default) |

## Rate Limiting

{% hint style="warning" %}
This endpoint is rate-limited to **1 request per 2 minutes per user** (not per project). If you manage multiple projects, the limit applies across all of them.
{% endhint %}

## Automated Pipeline with Webhooks

If you upload with `autoRelease: false`, you can combine Webhooks and this endpoint for a controlled CI/CD flow:

1. Upload a build via the [Upload File API](https://docs.streampixel.io/resources/api-reference/upload-file-api) with `autoRelease: false`
2. Listen for `build.approved` via [Webhooks](https://docs.streampixel.io/resources/api-reference/webhooks)
3. Run your own validation/checks, then call this endpoint to distribute
4. Listen for `build.distributing` to confirm

{% tabs %}
{% tab title="Node.js" %}
{% code lineNumbers="true" %}

```javascript
const express = require('express');
const app = express();

app.use(express.json());

const API_KEY = process.env.STREAMPIXEL_API_KEY;
const USER_ID = process.env.STREAMPIXEL_USER_ID;

app.post('/webhooks/streampixel', async (req, res) => {
  const { event, projectId, uploadId } = req.body;

  if (event === 'build.approved') {
    console.log(`Build ${uploadId} approved. Distributing...`);

    await fetch(
      'https://api.streampixel.io/pixelStripeApi/projects/distribute-file',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ projectId, uploadId, apiKey: API_KEY, userId: USER_ID }),
      }
    );
  }

  res.status(200).json({ received: true });
});

app.listen(3000);
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code lineNumbers="true" %}

```python
from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

API_KEY = os.environ['STREAMPIXEL_API_KEY']
USER_ID = os.environ['STREAMPIXEL_USER_ID']

@app.route('/webhooks/streampixel', methods=['POST'])
def handle_webhook():
    payload = request.get_json()

    if payload.get('event') == 'build.approved':
        print(f"Build {payload['uploadId']} approved. Distributing...")

        requests.post(
            'https://api.streampixel.io/pixelStripeApi/projects/distribute-file',
            json={
                'projectId': payload['projectId'],
                'uploadId': payload['uploadId'],
                'apiKey': API_KEY,
                'userId': USER_ID,
            }
        )

    return jsonify({"received": True}), 200

if __name__ == '__main__':
    app.run(port=3000)
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Troubleshooting

| Problem                         | Solution                                                                                                            |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `Unauthorized: Invalid API Key` | Regenerate your API key from the dashboard Settings page                                                            |
| `Access denied`                 | Verify you own the project and it's not disabled                                                                    |
| `File not found in project`     | Double-check the `uploadId` — it must belong to the specified project                                               |
| `File has no URL`               | The upload is still processing. Wait for it to complete before distributing                                         |
| `Rate limit exceeded`           | Wait the indicated seconds before retrying (limit: 1 req / 2 min / user)                                            |
| Triggered but not live          | Distribution is async. Use [Webhooks](https://docs.streampixel.io/resources/api-reference/webhooks) to track status |