Uploads API

Your media library: upload and list images, videos, audio and fonts.

View as Markdown

On this page

Authenticate with a personal token as Authorization: Bearer pxp_...; the operations are also MCP tools unless noted. The full machine-readable definition is in the OpenAPI specification.

Operation	Method and path	Scope
List uploads	`GET /uploads`	`overlays:read`
Upload media file	`POST /uploads`	`uploads:write`
Delete upload	`DELETE /uploads/{uploadId}`	`uploads:write`
Rename upload	`PATCH /uploads/{uploadId}`	`uploads:write`

Operations

List uploads

GET/api/v1/uploads

Lists your media library (images, video, audio, fonts) with urls usable as image/media sources in layer settings.

Scope: overlays:read (Read overlays) · MCP tool: list_uploads · Notes: read only

Name	In	Type	Required	Description
`kind`	query	`image`, `audio`, `video`, `font`, `all`	optional
`limit`	query	integer	optional	1 to 250
`offset`	query	integer	optional	At least 0
`overlayId`	query	string	optional	Optional: the library of this overlay's owner (shared overlays). Up to 64 characters

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/uploads" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const res = await fetch('https://pxstudio.cloud/api/v1/uploads', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Upload media file

POST/api/v1/uploads

Uploads one file as the raw request body (Content-Type = the file type: image/png, image/jpeg, image/gif, image/webp, video/mp4, video/webm, audio/, font/). Query: name (display name), overlayId (upload into a shared overlay owner's library). Returns the url to use in layer settings. REST only.

Scope: uploads:write (Upload media) · MCP tool: none (REST only)

Name	In	Type	Required	Description
`name`	query	string	optional	Up to 120 characters
`overlayId`	query	string	optional	Optional: upload for this shared overlay (counts against the owner's storage). Up to 64 characters

Send the raw file bytes as the request body. The type is detected from the content; SVG is not accepted.

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/uploads" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png

JavaScript

import { readFile } from 'node:fs/promises';

const res = await fetch('https://pxstudio.cloud/api/v1/uploads', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'image/png',
  },
  body: await readFile('logo.png'),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Delete upload

DELETE/api/v1/uploads/{uploadId}

DESTRUCTIVE: deletes a file from your media library. A file that a widget still uses answers 409 upload_in_use; send force:true to delete it anyway (the widget then shows nothing there). Owner only. Cannot be undone.

Scope: uploads:write (Upload media) · MCP tool: delete_upload · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`uploadId`	path	integer	required	Upload id (from list_uploads). At least 1
`force`	query	boolean	optional	Delete even if a widget still uses the file

Terminal

curl -X DELETE "https://pxstudio.cloud/api/v1/uploads/<uploadId>" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const uploadId = '<uploadId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/uploads/${uploadId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Rename upload

PATCH/api/v1/uploads/{uploadId}

Changes the display name of a file in your media library. Widgets keep using the file. Owner only.

Scope: uploads:write (Upload media) · MCP tool: rename_upload

Name	In	Type	Required	Description
`uploadId`	path	integer	required	Upload id (from list_uploads). At least 1
`name`	body	string	required	Up to 120 characters

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/uploads/<uploadId>" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "..." }'

JavaScript

const uploadId = '<uploadId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/uploads/${uploadId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: "..." }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Was this page helpful?