curl -X POST https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build \
-H "x-api-key: $STREAMPIXEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"}'
const res = await fetch(
'https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build',
{
method: 'POST',
headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ buildId: '66a0b1c2d3e4f5a6b7c8d9e0' }),
}
);
if (res.status === 409) console.log('not processed yet:', (await res.json()).message);
import os, requests
r = requests.post(
"https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build",
headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]},
json={"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"},
)
print(r.status_code, r.json())
{
"projectId": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "Showroom",
"region": "Europe",
"enabled": true,
"buildId": "66a0b1c2d3e4f5a6b7c8d9e0",
"changed": true,
"queued": true,
"previousBuildStatus": "Ready",
"note": "Distribution to the region's streaming servers is queued; poll GET /projects/{id}/files/{fileId}/status until it is Approved."
}
{
"projectId": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "Showroom",
"region": "Europe",
"enabled": true,
"buildId": "665a2b3c4d5e6f7a8b9c0e1f",
"changed": false,
"queued": false,
"previousBuildStatus": "Approved",
"note": "This build is already active and approved; nothing was changed. Send {\"redistribute\": true} to copy it to the region's streaming servers again."
}
{
"code": "CONFLICT",
"message": "Build is \"Extracting & Scanning\" and cannot be set active yet. It must have been processed (Ready or Approved); failed or rejected builds need a new upload.",
"status": "Extracting & Scanning"
}
Set Active Build
Make a processed build the one viewers get: the API equivalent of Set Active in the dashboard.
POST
/
api
/
v1
/
projects
/
{projectId}
/
active-build
curl -X POST https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build \
-H "x-api-key: $STREAMPIXEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"}'
const res = await fetch(
'https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build',
{
method: 'POST',
headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ buildId: '66a0b1c2d3e4f5a6b7c8d9e0' }),
}
);
if (res.status === 409) console.log('not processed yet:', (await res.json()).message);
import os, requests
r = requests.post(
"https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build",
headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]},
json={"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"},
)
print(r.status_code, r.json())
{
"projectId": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "Showroom",
"region": "Europe",
"enabled": true,
"buildId": "66a0b1c2d3e4f5a6b7c8d9e0",
"changed": true,
"queued": true,
"previousBuildStatus": "Ready",
"note": "Distribution to the region's streaming servers is queued; poll GET /projects/{id}/files/{fileId}/status until it is Approved."
}
{
"projectId": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "Showroom",
"region": "Europe",
"enabled": true,
"buildId": "665a2b3c4d5e6f7a8b9c0e1f",
"changed": false,
"queued": false,
"previousBuildStatus": "Approved",
"note": "This build is already active and approved; nothing was changed. Send {\"redistribute\": true} to copy it to the region's streaming servers again."
}
{
"code": "CONFLICT",
"message": "Build is \"Extracting & Scanning\" and cannot be set active yet. It must have been processed (Ready or Approved); failed or rejected builds need a new upload.",
"status": "Extracting & Scanning"
}
Choose which build the project serves. The build is marked
Ready, the project is switched on, and distribution to the region’s streaming servers is queued. Viewers get the new build once it reaches Approved; poll Build Status for that.
Scope:
control. Team members need the Uploader role or above: deploying a build is a build job, not a project change. Limited to 30 control calls per minute per account.Only a build the pipeline has finished processing can be set active: status
Ready, Approved, Distribute or Distributing to Servers. A build still downloading or scanning is refused with 409; a failed or rejected build needs a new upload.Idempotent. Posting the build that is already live and approved changes nothing: the response has
changed: false and queued: false, and the project is switched on if it was off. Send redistribute: true to copy that build to the region’s streaming servers again, for example after a server was rebuilt.Path parameters
string
required
The project.
Headers
string
required
An API key issued with the
control scope.Request body
string
required
The build to activate:
uploadId from Upload File, or id from List Builds.boolean
default:"false"
Copy the build to the region’s streaming servers again even when it is already the live, approved build.
Response
string
The build now being distributed.
boolean
false when the build was already live and the project already on.boolean
true: distribution was queued. false: the build is already live and nothing was copied.string
The build’s status before this call.
boolean
Always
true: setting a build active switches the project on.string
What to do next.
curl -X POST https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build \
-H "x-api-key: $STREAMPIXEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"}'
const res = await fetch(
'https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build',
{
method: 'POST',
headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ buildId: '66a0b1c2d3e4f5a6b7c8d9e0' }),
}
);
if (res.status === 409) console.log('not processed yet:', (await res.json()).message);
import os, requests
r = requests.post(
"https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build",
headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]},
json={"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"},
)
print(r.status_code, r.json())
{
"projectId": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "Showroom",
"region": "Europe",
"enabled": true,
"buildId": "66a0b1c2d3e4f5a6b7c8d9e0",
"changed": true,
"queued": true,
"previousBuildStatus": "Ready",
"note": "Distribution to the region's streaming servers is queued; poll GET /projects/{id}/files/{fileId}/status until it is Approved."
}
{
"projectId": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "Showroom",
"region": "Europe",
"enabled": true,
"buildId": "665a2b3c4d5e6f7a8b9c0e1f",
"changed": false,
"queued": false,
"previousBuildStatus": "Approved",
"note": "This build is already active and approved; nothing was changed. Send {\"redistribute\": true} to copy it to the region's streaming servers again."
}
{
"code": "CONFLICT",
"message": "Build is \"Extracting & Scanning\" and cannot be set active yet. It must have been processed (Ready or Approved); failed or rejected builds need a new upload.",
"status": "Extracting & Scanning"
}
Errors
| Status | code | Cause |
|---|---|---|
400 | VALIDATION_FAILED | buildId missing or not a 24-character id. |
403 | API_KEY_SCOPE | The key was issued without control. |
403 | — | The project belongs to another account, or the team role cannot edit projects. |
404 | NOT_FOUND | No such project, or no such build on it. |
409 | CONFLICT | The build has not been processed yet, or failed. |
429 | RATE_LIMITED | More than 30 control calls in a minute. |
A full release from CI
1
Upload
Upload File with
autoRelease: false; keep the uploadId.2
Wait for processing
Poll Build Status until
state is ready_for_activation, or listen for the build.ready webhook (build.saving fires earlier, while the build is still being processed — activating then is refused with 409).3
Activate
Call this endpoint with the
uploadId.4
Wait for distribution
Poll Build Status until
state is live. Optionally End Sessions so current viewers reconnect onto the new build.