Ctrlk
discordx-twitter
For the complete documentation index, see llms.txt. This page is also available as Markdown.

image-playMedia

Upload standalone images and videos, with no build or test run behind them, and get back a shareable URL plus ready-to-paste Markdown. Built for embedding a screenshot or a screen recording in the pull request an agent just opened.

Create a media upload

post

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, Argos 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 Argos attaches it and posts the comment — nothing has to come back and connect the two.

The argos media upload CLI command does all of this in one step.

Authorizations
AuthorizationstringRequired

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 Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.

Body
namestring · min: 1 · max: 255Required

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.

Example: before.png
statestring · enum · nullableOptional

Which half of a before/after pair this media is, so the two can be shown side by side and compared. Inferred from a file name ending in -before or -after.

Possible values:
descriptionstring · max: 2000 · nullableOptional

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

contentTypestringRequired

Content type of the media file

sizeinteger · min: 1 · max: 9007199254740991Required

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

hashstringRequired

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

Pattern: ^[A-Fa-f0-9]{64}$
visibilitystring · enum · nullableOptional

Who can open the media share page. team requires an Argos 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.

Possible values:
projectstring · nullableOptional

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

Example: acme/web
prNumberinteger · min: 1 · max: 9007199254740991 · nullableOptional

Pull request this media belongs to. Argos 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.

branchstring · min: 1 · max: 255 · nullableOptional

Branch this media belongs to. Upload against a branch when the pull request does not exist yet: the media is staged until one opens for that branch, and Argos publishes it — and posts the comment — on its own at that point. No GitHub connection is needed to name a branch.

Example: feat/checkout
Responses
201

The registered media and where to upload it

application/json
post/media
POST /v2/media HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "name": "before.png",
  "state": "before",
  "description": "text",
  "contentType": "text",
  "size": 1,
  "hash": "text",
  "visibility": "team",
  "project": "acme/web",
  "prNumber": 1,
  "branch": "feat/checkout"
}
{
  "media": {
    "id": "text",
    "name": "text",
    "state": "before",
    "description": null,
    "stage": "staged",
    "branch": null,
    "prNumber": null,
    "url": "https://example.com",
    "markdown": "text",
    "version": 1,
    "versionCount": 1,
    "fileUrl": "https://example.com",
    "posterUrl": "https://example.com",
    "contentType": "text",
    "sizeBytes": 1,
    "width": null,
    "height": null,
    "visibility": "team",
    "status": "pending",
    "expiresAt": null,
    "createdAt": "text"
  },
  "upload": {
    "url": "https://example.com",
    "fields": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }
}

Get a media

get

Retrieve a single media by its ID, including its share URL and ready-to-paste Markdown.

Authorizations
AuthorizationstringRequired

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 Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.

Path parameters
mediaIdstringRequired

The media ID

Responses
200

Media details

application/json

A standalone image or video uploaded to Argos

idstringRequired

Unique identifier of the media

namestringRequired

The media's name, and its identity within its pull request. Uploading the same name again adds a version.

statestring · enum · nullableRequired

Which half of a before/after pair this media is, so the two can be shown side by side and compared. Inferred from a file name ending in -before or -after.

Possible values:
descriptionstring · nullableRequired

Prose shown under the media in the pull request comment.

stagestring · enumRequired

staged while the media is only attached to a branch, published once a pull request is attached and Argos lists it in that pull request's comment. A media attached to neither is staged.

Possible values:
branchstring · nullableRequired

Branch this media was uploaded for. Kept after publishing, as a record of where it came from.

prNumbernumber · nullableRequired

Pull request this media is published to, or null while it is staged.

urlstring · uriRequired

Share page URL. This is the link to put in a pull request or a chat message, and it keeps working across versions — it always shows the newest one.

markdownstringRequired

Ready-to-paste Markdown: the picture — the image itself, or a video's poster frame — embedded from the CDN and linked to the share page. Embed this rather than building your own from url: that is an HTML page, and an image embed pointing at it renders as a broken image.

versionnumberRequired

Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again.

versionCountnumberRequired

How many uploaded versions this media has. Above 1, GET /media/{mediaId}/versions lists them — which is how a comment's mediaVersionId resolves to the file it was written against.

fileUrlstring · uriRequired

URL of the image or video itself, for an agent that wants to look at it.

posterUrlstring · uri · nullableRequired

Poster frame of a video, derived by the image CDN. Always null for images.

contentTypestringRequired

Content type of the media

sizeBytesnumberRequired

Size of the media, in bytes

widthnumber · nullableRequired

Width, in pixels

heightnumber · nullableRequired

Height, in pixels

visibilitystring · enumRequired

Who can open the media share page. team requires an Argos session with access to the owning account; public only requires the share URL.

Possible values:
statusstring · enumRequired

pending until the bytes are uploaded, then ready. There is no processing step — Argos serves the bytes it was given.

Possible values:
expiresAtstring · nullableRequired

When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.

createdAtstringRequired
get/media/{mediaId}
GET /v2/media/{mediaId} HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "state": "before",
  "description": null,
  "stage": "staged",
  "branch": null,
  "prNumber": null,
  "url": "https://example.com",
  "markdown": "text",
  "version": 1,
  "versionCount": 1,
  "fileUrl": "https://example.com",
  "posterUrl": "https://example.com",
  "contentType": "text",
  "sizeBytes": 1,
  "width": null,
  "height": null,
  "visibility": "team",
  "status": "pending",
  "expiresAt": null,
  "createdAt": "text"
}

Delete a media

delete

Delete a media and the files behind it. Any share link or pull request embed pointing at it stops working immediately.

Authorizations
AuthorizationstringRequired

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 Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.

Path parameters
mediaIdstringRequired

The media ID

Responses
204

Media deleted

No content
delete/media/{mediaId}
DELETE /v2/media/{mediaId} HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a staged media

patch

Change a staged media's name, description or branch.

Staged media only. A media's name and branch are its identity — what decides whether the next upload of that name is a new version or a new media, and which pull request will publish it — and once it is published that identity is what the pull request comment is built from and what a reviewer's comments hang off. Editing it there would rewrite history rather than correct a staged media.

Omitted fields are left alone. description and branch accept null to clear them; name is required and has no cleared state. Clearing a staged media's branch leaves it attached to nothing, so no pull request will ever publish it.

Authorizations
AuthorizationstringRequired

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 Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.

Path parameters
mediaIdstringRequired

The media ID

Body
namestring · min: 1 · max: 255Optional

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.

Example: before.png
descriptionstring · max: 2000 · nullableOptional

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

branchstring · min: 1 · max: 255 · nullableOptional

Branch this media belongs to. Upload against a branch when the pull request does not exist yet: the media is staged until one opens for that branch, and Argos publishes it — and posts the comment — on its own at that point. No GitHub connection is needed to name a branch.

Example: feat/checkout
Responses
200

The updated media

application/json

A standalone image or video uploaded to Argos

idstringRequired

Unique identifier of the media

namestringRequired

The media's name, and its identity within its pull request. Uploading the same name again adds a version.

statestring · enum · nullableRequired

Which half of a before/after pair this media is, so the two can be shown side by side and compared. Inferred from a file name ending in -before or -after.

Possible values:
descriptionstring · nullableRequired

Prose shown under the media in the pull request comment.

stagestring · enumRequired

staged while the media is only attached to a branch, published once a pull request is attached and Argos lists it in that pull request's comment. A media attached to neither is staged.

Possible values:
branchstring · nullableRequired

Branch this media was uploaded for. Kept after publishing, as a record of where it came from.

prNumbernumber · nullableRequired

Pull request this media is published to, or null while it is staged.

urlstring · uriRequired

Share page URL. This is the link to put in a pull request or a chat message, and it keeps working across versions — it always shows the newest one.

markdownstringRequired

Ready-to-paste Markdown: the picture — the image itself, or a video's poster frame — embedded from the CDN and linked to the share page. Embed this rather than building your own from url: that is an HTML page, and an image embed pointing at it renders as a broken image.

versionnumberRequired

Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again.

versionCountnumberRequired

How many uploaded versions this media has. Above 1, GET /media/{mediaId}/versions lists them — which is how a comment's mediaVersionId resolves to the file it was written against.

fileUrlstring · uriRequired

URL of the image or video itself, for an agent that wants to look at it.

posterUrlstring · uri · nullableRequired

Poster frame of a video, derived by the image CDN. Always null for images.

contentTypestringRequired

Content type of the media

sizeBytesnumberRequired

Size of the media, in bytes

widthnumber · nullableRequired

Width, in pixels

heightnumber · nullableRequired

Height, in pixels

visibilitystring · enumRequired

Who can open the media share page. team requires an Argos session with access to the owning account; public only requires the share URL.

Possible values:
statusstring · enumRequired

pending until the bytes are uploaded, then ready. There is no processing step — Argos serves the bytes it was given.

Possible values:
expiresAtstring · nullableRequired

When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.

createdAtstringRequired
patch/media/{mediaId}
PATCH /v2/media/{mediaId} HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "name": "before.png",
  "description": "text",
  "branch": "feat/checkout"
}
{
  "id": "text",
  "name": "text",
  "state": "before",
  "description": null,
  "stage": "staged",
  "branch": null,
  "prNumber": null,
  "url": "https://example.com",
  "markdown": "text",
  "version": 1,
  "versionCount": 1,
  "fileUrl": "https://example.com",
  "posterUrl": "https://example.com",
  "contentType": "text",
  "sizeBytes": 1,
  "width": null,
  "height": null,
  "visibility": "team",
  "status": "pending",
  "expiresAt": null,
  "createdAt": "text"
}

List a media's versions

get

A media's most recent uploaded versions, newest first, up to 100.

A separate call because it is rarely needed: a media usually has one version, and the media itself already carries the newest one flattened onto it. Check versionCount first — at 1 there is nothing here you do not already have.

When you do need it, it is because a comment carries the mediaVersionId it was written against. A pin describes a spot on those bytes, so feedback written on an earlier upload has to be read against that upload — match the id here to get its file.

Authorizations
AuthorizationstringRequired

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 Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.

Path parameters
mediaIdstringRequired

The media ID

Responses
200

The media's versions, newest first

application/json

One uploaded version of a media

idstringRequired

Unique identifier of this version — what a comment's mediaVersionId points at.

numbernumberRequired

1-based, and what the UI calls the version. Increments each time the same name is uploaded again.

fileUrlstring · uriRequired

URL of the image or video as it was at this version.

posterUrlstring · uri · nullableRequired

Poster frame of a video. Always null for images.

contentTypestringRequired
sizeBytesnumberRequired
widthnumber · nullableRequired
heightnumber · nullableRequired
expiresAtstring · nullableRequired

When this version is deleted. Retention applies per version, so an old one ages out while the media and its share URL live on.

createdAtstringRequired
get/media/{mediaId}/versions
GET /v2/media/{mediaId}/versions HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "text",
    "number": 1,
    "fileUrl": "https://example.com",
    "posterUrl": "https://example.com",
    "contentType": "text",
    "sizeBytes": 1,
    "width": null,
    "height": null,
    "expiresAt": null,
    "createdAt": "text"
  }
]

Finalize a media upload

post

Confirm that a media version's bytes have been uploaded. Argos reads the object back to check the file is what it claims to be, records an image's dimensions, bills it to the screenshot meter, and updates the managed pull request comment. There is no processing step: the media is usable the moment this returns.

Authorizations
AuthorizationstringRequired

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 Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.

Path parameters
mediaIdstringRequired

The media ID

Responses
200

The finalized media

application/json

A standalone image or video uploaded to Argos

idstringRequired

Unique identifier of the media

namestringRequired

The media's name, and its identity within its pull request. Uploading the same name again adds a version.

statestring · enum · nullableRequired

Which half of a before/after pair this media is, so the two can be shown side by side and compared. Inferred from a file name ending in -before or -after.

Possible values:
descriptionstring · nullableRequired

Prose shown under the media in the pull request comment.

stagestring · enumRequired

staged while the media is only attached to a branch, published once a pull request is attached and Argos lists it in that pull request's comment. A media attached to neither is staged.

Possible values:
branchstring · nullableRequired

Branch this media was uploaded for. Kept after publishing, as a record of where it came from.

prNumbernumber · nullableRequired

Pull request this media is published to, or null while it is staged.

urlstring · uriRequired

Share page URL. This is the link to put in a pull request or a chat message, and it keeps working across versions — it always shows the newest one.

markdownstringRequired

Ready-to-paste Markdown: the picture — the image itself, or a video's poster frame — embedded from the CDN and linked to the share page. Embed this rather than building your own from url: that is an HTML page, and an image embed pointing at it renders as a broken image.

versionnumberRequired

Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again.

versionCountnumberRequired

How many uploaded versions this media has. Above 1, GET /media/{mediaId}/versions lists them — which is how a comment's mediaVersionId resolves to the file it was written against.

fileUrlstring · uriRequired

URL of the image or video itself, for an agent that wants to look at it.

posterUrlstring · uri · nullableRequired

Poster frame of a video, derived by the image CDN. Always null for images.

contentTypestringRequired

Content type of the media

sizeBytesnumberRequired

Size of the media, in bytes

widthnumber · nullableRequired

Width, in pixels

heightnumber · nullableRequired

Height, in pixels

visibilitystring · enumRequired

Who can open the media share page. team requires an Argos session with access to the owning account; public only requires the share URL.

Possible values:
statusstring · enumRequired

pending until the bytes are uploaded, then ready. There is no processing step — Argos serves the bytes it was given.

Possible values:
expiresAtstring · nullableRequired

When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.

createdAtstringRequired
post/media/{mediaId}/finalize
POST /v2/media/{mediaId}/finalize HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "state": "before",
  "description": null,
  "stage": "staged",
  "branch": null,
  "prNumber": null,
  "url": "https://example.com",
  "markdown": "text",
  "version": 1,
  "versionCount": 1,
  "fileUrl": "https://example.com",
  "posterUrl": "https://example.com",
  "contentType": "text",
  "sizeBytes": 1,
  "width": null,
  "height": null,
  "visibility": "team",
  "status": "pending",
  "expiresAt": null,
  "createdAt": "text"
}

List a project's media

get

List the standalone images and videos uploaded to a project, most recent first.

branch and prNumber are what this is usually for: everything uploaded for the work in hand, whether or not a pull request exists yet. branch covers both — a media keeps its branch after publishing — so it stays a single query across the moment the pull request opens.

Authorizations
AuthorizationstringRequired

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 Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.

Path parameters
ownerstring · min: 1Required
projectstring · min: 1Required
Query parameters
perPagestringOptional

Number of items per page (max 100)

pagestringOptional

Page number

branchstring · min: 1Optional

Only media uploaded for this branch, staged and published alike.

Example: feat/checkout
prNumberinteger · min: 1 · max: 9007199254740991Optional

Only media published to this pull request.

stagestring · enumOptional

Restrict to staged media (no pull request yet) or to published media.

Possible values:
searchstringOptional

Match media on their file name or slug.

typestring · enumOptional

Restrict to images or to videos.

Possible values:
Responses
200

List of media

application/json
get/projects/{owner}/{project}/media
GET /v2/projects/{owner}/{project}/media HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pageInfo": {
    "total": 1,
    "page": 1,
    "perPage": 1
  },
  "results": [
    {
      "id": "text",
      "name": "text",
      "state": "before",
      "description": null,
      "stage": "staged",
      "branch": null,
      "prNumber": null,
      "url": "https://example.com",
      "markdown": "text",
      "version": 1,
      "versionCount": 1,
      "fileUrl": "https://example.com",
      "posterUrl": "https://example.com",
      "contentType": "text",
      "sizeBytes": 1,
      "width": null,
      "height": null,
      "visibility": "team",
      "status": "pending",
      "expiresAt": null,
      "createdAt": "text"
    }
  ]
}

Last updated

Was this helpful?