Distribute File API

Distribute a build to streaming servers

post

Trigger distribution of an uploaded build file to the streaming servers in the project's configured region. Distribution is asynchronous — a 200 response means the process has been triggered, not completed. Use webhooks to track progress.

Body

application/json

apiKeystringRequired

Your API authentication key

userIdstringRequired

Your Streampixel user ID

projectIdstringRequired

The unique identifier of your Streampixel project

uploadIdstringRequired

The unique identifier of the uploaded build file (returned from upload-file)

Responses

200

Distribution triggered successfully

application/json

successbooleanOptionalExample: true

uploadIdstringOptionalExample: 665a2b3c4d5e6f7a8b9c0e1f

regionstring · enumOptional

Region the build is being distributed to

Example: us-east-1Possible values:

messagestringOptionalExample: File distribution triggered successfully

400

Bad request — missing fields or file has no URL

application/json

401

Unauthorized — invalid user or API key

application/json

403

Forbidden — access denied to project

application/json

404

Not found — project or file does not exist

application/json

429

Rate limit exceeded — 1 request per 2 minutes per user

application/json

500

Internal server error

application/json

post

/projects/distribute-file

HTTPcURLJavaScriptPython

POST /pixelStripeApi/projects/distribute-file HTTP/1.1
Host: api.streampixel.io
Content-Type: application/json
Accept: */*
Content-Length: 138

{
  "apiKey": "your-api-key",
  "userId": "664f1a2b3c4d5e6f7a8b9c0d",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f"
}

{
  "success": true,
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "region": "us-east-1",
  "message": "File distribution triggered successfully"
}

Overview

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

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).

Distribution is asynchronous. A 200 response means the process has been triggered, not completed. Use Webhooks to track when distribution finishes.

Prerequisites

Before calling this endpoint, ensure:

• The build has been uploaded via the 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

Code Examples

cURL

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"
  }'

JavaScript

Python

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

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.

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 with autoRelease: false

2. Listen for build.approved via Webhooks

3. Run your own validation/checks, then call this endpoint to distribute

4. Listen for build.distributing to confirm

Node.js

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);

Python

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 to track status