Create a media upload

Register a standalone image or video and receive a signed target to upload it to. Uploading takes three calls: 1. `POST /media` — declare the file and get back an `upload` target. 2. `POST` the file to `upload.url` as `multipart/form-data`, appending every entry of `upload.fields` **before** the `file` part. 3. `POST /media/{mediaId}/finalize` — confirm the bytes landed. When `upload` comes back `null`, Snapvisor already holds this exact file and steps 2 and 3 are unnecessary. Pass `prNumber` when the pull request already exists, or `branch` when it does not. A media uploaded against a branch is **staged**: it has its share URL immediately, and the moment a pull request opens for that branch Snapvisor attaches it and posts the comment — nothing has to come back and connect the two. Use it when you have a standalone screenshot or screen recording, outside a CI build, to attach to a branch or pull request.

Uploading takes three calls:

POST /media — declare the file and get back an upload target.
POST the file to upload.url as multipart/form-data, appending every entry of upload.fields before the file part.
POST /media/{mediaId}/finalize — confirm the bytes landed.

When upload comes back null, Snapvisor already holds this exact file and steps 2 and 3 are unnecessary.

Pass prNumber when the pull request already exists, or branch when it does not. A media uploaded against a branch is staged: it has its share URL immediately, and the moment a pull request opens for that branch Snapvisor attaches it and posts the comment — nothing has to come back and connect the two.

Use it when you have a standalone screenshot or screen recording, outside a CI build, to attach to a branch or pull request.

Authorization

AuthorizationBearer <token>

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

You can find your project token in your Snapvisor project settings. Project tokens are used by CI and the SDK to create builds and deployments.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

File name, used for display and as the Markdown alt text. Also the media's identity: uploading the same name on the same pull request adds a version rather than creating a second media.

Length1 <= length <= 255

state?|null

description?|

Prose shown under the media in the managed pull request comment.

contentType*string

Content type of the media file

size*integer

Size of the file in bytes. Checked against your plan's limit before the upload is signed.

Range1 <= value <= 9007199254740991

hash*string

SHA-256 of the file contents, hex encoded. Uploading the same file twice is free: Snapvisor recognizes the hash and skips the transfer, and byte-identical bytes do not create a new version.

Match^[A-Fa-f0-9]{64}$

visibility?|

Who can open the media share page. team requires a signed-in session with access to the owning account; public only requires the share URL. Omit it — the usual case — and the media follows its project's visibility: public for a public project, team for a private one. team requires a paid plan.

project?|

Project to upload to, as owner/project. Required with a personal access token; ignored with a project token, which already identifies its project.

prNumber?|

Pull request this media belongs to. Snapvisor maintains a single comment on it listing every media uploaded, editing it in place rather than posting a new one each time — attaching a media to a pull request and showing it there are the same act, not two. Also part of the media's identity: uploading the same name again on this pull request adds a version.

branch?|null

Response Body

`application/json`

curl -X POST "https://example.com/media" \  -H "Content-Type: application/json" \  -d '{    "name": "before.png",    "contentType": "string",    "size": 1,    "hash": "string"  }'

{  "media": {    "id": "string",    "name": "string",    "state": "before",    "description": "string",    "stage": "staged",    "branch": "string",    "prNumber": 0,    "url": "http://example.com",    "markdown": "string",    "version": 0,    "versionCount": 0,    "fileUrl": "http://example.com",    "posterUrl": "http://example.com",    "contentType": "string",    "sizeBytes": 0,    "width": 0,    "height": 0,    "visibility": "team",    "status": "pending",    "expiresAt": "string",    "createdAt": "string"  },  "upload": {    "url": "http://example.com",    "fields": {      "property1": "string",      "property2": "string"    }  }}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`