> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/api-reference/reference/media.md). # Media 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 > 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. ````json {"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Media","description":"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."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["media:write"]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Personal Access Token","description":"Authenticate as a **user** with a personal access token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nPersonal access tokens act on behalf of the user that created them\nand are required by endpoints that perform user actions, such as\nreviewing builds and posting comments."},"oauth2":{"type":"oauth2","description":"Authenticate as a **user** via an OAuth 2.1 access token obtained\nthrough the authorization-code (+ PKCE) flow. Used by the CLI and by\nMCP clients/agents. The token acts on behalf of the authorizing user,\nlimited to the granted scopes and organizations.","flows":{"authorizationCode":{"authorizationUrl":"https://app.argos-ci.com/oauth/authorize","tokenUrl":"https://app.argos-ci.com/oauth/token","refreshUrl":"https://app.argos-ci.com/oauth/token","scopes":{"profile":"Read your Argos profile and the list of teams you belong to.","projects:read":"Read your projects, builds, screenshots, diffs, tests, and analytics.","projects:write":"Create and configure projects and their settings.","builds:write":"Create and upload builds and screenshots.","reviews:write":"Approve, reject, or dismiss build reviews and ignore changes.","comments:read":"Read build comments and threads.","comments:write":"Post, edit, and delete comments, add reactions, and manage subscriptions.","media:read":"Read the images and videos uploaded to your teams.","media:write":"Upload images and videos, and delete the ones already uploaded.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"Media":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the media"},"name":{"type":"string","description":"The media's name, and its identity within its pull request. Uploading the same name again adds a version."},"state":{"anyOf":[{"type":"string","enum":["before","after"],"description":"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`."},{"type":"null"}]},"description":{"description":"Prose shown under the media in the pull request comment.","type":["string","null"]},"stage":{"type":"string","enum":["staged","published"],"description":"`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`."},"branch":{"description":"Branch this media was uploaded for. Kept after publishing, as a record of where it came from.","type":["string","null"]},"prNumber":{"description":"Pull request this media is published to, or `null` while it is staged.","type":["number","null"]},"url":{"type":"string","format":"uri","description":"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."},"markdown":{"type":"string","description":"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."},"version":{"type":"number","description":"Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again."},"versionCount":{"type":"number","description":"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."},"fileUrl":{"type":"string","format":"uri","description":"URL of the image or video itself, for an agent that wants to look at it."},"posterUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Poster frame of a video, derived by the image CDN. Always `null` for images."},"contentType":{"type":"string","description":"Content type of the media"},"sizeBytes":{"type":"number","description":"Size of the media, in bytes"},"width":{"description":"Width, in pixels","type":["number","null"]},"height":{"description":"Height, in pixels","type":["number","null"]},"visibility":{"type":"string","enum":["team","public"],"description":"Who can open the media share page. `team` requires an Argos session with access to the owning account; `public` only requires the share URL."},"status":{"type":"string","enum":["pending","ready"],"description":"`pending` until the bytes are uploaded, then `ready`. There is no processing step — Argos serves the bytes it was given."},"expiresAt":{"description":"When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.","type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","name","state","description","stage","branch","prNumber","url","markdown","version","versionCount","fileUrl","posterUrl","contentType","sizeBytes","width","height","visibility","status","expiresAt","createdAt"],"additionalProperties":false,"description":"A standalone image or video uploaded to Argos"},"MediaUploadTarget":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL to POST the file to, as `multipart/form-data`."},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Form fields that must be appended **before** the file part, in order, for the upload to be accepted."}},"required":["url","fields"],"additionalProperties":false,"description":"Signed upload target"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/media":{"post":{"operationId":"createMedia","summary":"Create a media upload","description":"Register a standalone image or video and receive a signed target to upload it to.\n\nUploading takes three calls:\n\n1. `POST /media` — declare the file and get back an `upload` target.\n2. `POST` the file to `upload.url` as `multipart/form-data`, appending every entry of `upload.fields` **before** the `file` part.\n3. `POST /media/{mediaId}/finalize` — confirm the bytes landed.\n\nWhen `upload` comes back `null`, Argos already holds this exact file and steps 2 and 3 are unnecessary.\n\nPass `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.\n\nThe `argos media upload` CLI command does all of this in one step.","tags":["Media"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"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."},"state":{"anyOf":[{"type":"string","enum":["before","after"],"description":"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`."},{"type":"null"}]},"description":{"description":"Prose shown under the media in the managed pull request comment.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"contentType":{"description":"Content type of the media file","type":"string"},"size":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Size of the file in bytes. Checked against your plan's limit before the upload is signed."},"hash":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$","description":"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."},"visibility":{"description":"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.","anyOf":[{"type":"string","enum":["team","public"],"description":"Who can open the media share page. `team` requires an Argos session with access to the owning account; `public` only requires the share URL."},{"type":"null"}]},"project":{"description":"Project to upload to, as `owner/project`. Required with a personal access token; ignored with a project token, which already identifies its project.","type":["string","null"]},"prNumber":{"description":"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.","anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]},"branch":{"anyOf":[{"type":"string","minLength":1,"maxLength":255,"description":"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."},{"type":"null"}]}},"required":["name","contentType","size","hash"]}}}},"responses":{"201":{"description":"The registered media and where to upload it","content":{"application/json":{"schema":{"type":"object","properties":{"media":{"$ref":"#/components/schemas/Media"},"upload":{"anyOf":[{"$ref":"#/components/schemas/MediaUploadTarget"},{"type":"null"}],"description":"Where to send the bytes, or `null` when Argos already holds this exact file — in which case the media is ready and nothing needs uploading."}},"required":["media","upload"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```` ## Get a media > Retrieve a single media by its ID, including its share URL and ready-to-paste Markdown. ````json {"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Media","description":"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."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["media:read"]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Personal Access Token","description":"Authenticate as a **user** with a personal access token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nPersonal access tokens act on behalf of the user that created them\nand are required by endpoints that perform user actions, such as\nreviewing builds and posting comments."},"oauth2":{"type":"oauth2","description":"Authenticate as a **user** via an OAuth 2.1 access token obtained\nthrough the authorization-code (+ PKCE) flow. Used by the CLI and by\nMCP clients/agents. The token acts on behalf of the authorizing user,\nlimited to the granted scopes and organizations.","flows":{"authorizationCode":{"authorizationUrl":"https://app.argos-ci.com/oauth/authorize","tokenUrl":"https://app.argos-ci.com/oauth/token","refreshUrl":"https://app.argos-ci.com/oauth/token","scopes":{"profile":"Read your Argos profile and the list of teams you belong to.","projects:read":"Read your projects, builds, screenshots, diffs, tests, and analytics.","projects:write":"Create and configure projects and their settings.","builds:write":"Create and upload builds and screenshots.","reviews:write":"Approve, reject, or dismiss build reviews and ignore changes.","comments:read":"Read build comments and threads.","comments:write":"Post, edit, and delete comments, add reactions, and manage subscriptions.","media:read":"Read the images and videos uploaded to your teams.","media:write":"Upload images and videos, and delete the ones already uploaded.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"Media":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the media"},"name":{"type":"string","description":"The media's name, and its identity within its pull request. Uploading the same name again adds a version."},"state":{"anyOf":[{"type":"string","enum":["before","after"],"description":"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`."},{"type":"null"}]},"description":{"description":"Prose shown under the media in the pull request comment.","type":["string","null"]},"stage":{"type":"string","enum":["staged","published"],"description":"`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`."},"branch":{"description":"Branch this media was uploaded for. Kept after publishing, as a record of where it came from.","type":["string","null"]},"prNumber":{"description":"Pull request this media is published to, or `null` while it is staged.","type":["number","null"]},"url":{"type":"string","format":"uri","description":"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."},"markdown":{"type":"string","description":"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."},"version":{"type":"number","description":"Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again."},"versionCount":{"type":"number","description":"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."},"fileUrl":{"type":"string","format":"uri","description":"URL of the image or video itself, for an agent that wants to look at it."},"posterUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Poster frame of a video, derived by the image CDN. Always `null` for images."},"contentType":{"type":"string","description":"Content type of the media"},"sizeBytes":{"type":"number","description":"Size of the media, in bytes"},"width":{"description":"Width, in pixels","type":["number","null"]},"height":{"description":"Height, in pixels","type":["number","null"]},"visibility":{"type":"string","enum":["team","public"],"description":"Who can open the media share page. `team` requires an Argos session with access to the owning account; `public` only requires the share URL."},"status":{"type":"string","enum":["pending","ready"],"description":"`pending` until the bytes are uploaded, then `ready`. There is no processing step — Argos serves the bytes it was given."},"expiresAt":{"description":"When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.","type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","name","state","description","stage","branch","prNumber","url","markdown","version","versionCount","fileUrl","posterUrl","contentType","sizeBytes","width","height","visibility","status","expiresAt","createdAt"],"additionalProperties":false,"description":"A standalone image or video uploaded to Argos"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/media/{mediaId}":{"get":{"operationId":"getMedia","summary":"Get a media","description":"Retrieve a single media by its ID, including its share URL and ready-to-paste Markdown.","tags":["Media"],"parameters":[{"in":"path","name":"mediaId","schema":{"type":"string","description":"The media ID"},"required":true,"description":"The media ID"}],"responses":{"200":{"description":"Media details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```` ## Delete a media > Delete a media and the files behind it. Any share link or pull request embed pointing at it stops working immediately. ````json {"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Media","description":"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."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["media:write"]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Personal Access Token","description":"Authenticate as a **user** with a personal access token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nPersonal access tokens act on behalf of the user that created them\nand are required by endpoints that perform user actions, such as\nreviewing builds and posting comments."},"oauth2":{"type":"oauth2","description":"Authenticate as a **user** via an OAuth 2.1 access token obtained\nthrough the authorization-code (+ PKCE) flow. Used by the CLI and by\nMCP clients/agents. The token acts on behalf of the authorizing user,\nlimited to the granted scopes and organizations.","flows":{"authorizationCode":{"authorizationUrl":"https://app.argos-ci.com/oauth/authorize","tokenUrl":"https://app.argos-ci.com/oauth/token","refreshUrl":"https://app.argos-ci.com/oauth/token","scopes":{"profile":"Read your Argos profile and the list of teams you belong to.","projects:read":"Read your projects, builds, screenshots, diffs, tests, and analytics.","projects:write":"Create and configure projects and their settings.","builds:write":"Create and upload builds and screenshots.","reviews:write":"Approve, reject, or dismiss build reviews and ignore changes.","comments:read":"Read build comments and threads.","comments:write":"Post, edit, and delete comments, add reactions, and manage subscriptions.","media:read":"Read the images and videos uploaded to your teams.","media:write":"Upload images and videos, and delete the ones already uploaded.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/media/{mediaId}":{"delete":{"operationId":"deleteMedia","summary":"Delete a media","description":"Delete a media and the files behind it. Any share link or pull request embed pointing at it stops working immediately.","tags":["Media"],"parameters":[{"in":"path","name":"mediaId","schema":{"type":"string","description":"The media ID"},"required":true,"description":"The media ID"}],"responses":{"204":{"description":"Media deleted"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```` ## Update a staged media > 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. ````json {"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Media","description":"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."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["media:write"]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Personal Access Token","description":"Authenticate as a **user** with a personal access token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nPersonal access tokens act on behalf of the user that created them\nand are required by endpoints that perform user actions, such as\nreviewing builds and posting comments."},"oauth2":{"type":"oauth2","description":"Authenticate as a **user** via an OAuth 2.1 access token obtained\nthrough the authorization-code (+ PKCE) flow. Used by the CLI and by\nMCP clients/agents. The token acts on behalf of the authorizing user,\nlimited to the granted scopes and organizations.","flows":{"authorizationCode":{"authorizationUrl":"https://app.argos-ci.com/oauth/authorize","tokenUrl":"https://app.argos-ci.com/oauth/token","refreshUrl":"https://app.argos-ci.com/oauth/token","scopes":{"profile":"Read your Argos profile and the list of teams you belong to.","projects:read":"Read your projects, builds, screenshots, diffs, tests, and analytics.","projects:write":"Create and configure projects and their settings.","builds:write":"Create and upload builds and screenshots.","reviews:write":"Approve, reject, or dismiss build reviews and ignore changes.","comments:read":"Read build comments and threads.","comments:write":"Post, edit, and delete comments, add reactions, and manage subscriptions.","media:read":"Read the images and videos uploaded to your teams.","media:write":"Upload images and videos, and delete the ones already uploaded.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"Media":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the media"},"name":{"type":"string","description":"The media's name, and its identity within its pull request. Uploading the same name again adds a version."},"state":{"anyOf":[{"type":"string","enum":["before","after"],"description":"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`."},{"type":"null"}]},"description":{"description":"Prose shown under the media in the pull request comment.","type":["string","null"]},"stage":{"type":"string","enum":["staged","published"],"description":"`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`."},"branch":{"description":"Branch this media was uploaded for. Kept after publishing, as a record of where it came from.","type":["string","null"]},"prNumber":{"description":"Pull request this media is published to, or `null` while it is staged.","type":["number","null"]},"url":{"type":"string","format":"uri","description":"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."},"markdown":{"type":"string","description":"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."},"version":{"type":"number","description":"Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again."},"versionCount":{"type":"number","description":"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."},"fileUrl":{"type":"string","format":"uri","description":"URL of the image or video itself, for an agent that wants to look at it."},"posterUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Poster frame of a video, derived by the image CDN. Always `null` for images."},"contentType":{"type":"string","description":"Content type of the media"},"sizeBytes":{"type":"number","description":"Size of the media, in bytes"},"width":{"description":"Width, in pixels","type":["number","null"]},"height":{"description":"Height, in pixels","type":["number","null"]},"visibility":{"type":"string","enum":["team","public"],"description":"Who can open the media share page. `team` requires an Argos session with access to the owning account; `public` only requires the share URL."},"status":{"type":"string","enum":["pending","ready"],"description":"`pending` until the bytes are uploaded, then `ready`. There is no processing step — Argos serves the bytes it was given."},"expiresAt":{"description":"When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.","type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","name","state","description","stage","branch","prNumber","url","markdown","version","versionCount","fileUrl","posterUrl","contentType","sizeBytes","width","height","visibility","status","expiresAt","createdAt"],"additionalProperties":false,"description":"A standalone image or video uploaded to Argos"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/media/{mediaId}":{"patch":{"operationId":"updateMedia","summary":"Update a staged media","description":"Change a staged media's name, description or branch.\n\nStaged 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.\n\nOmitted 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.","tags":["Media"],"parameters":[{"in":"path","name":"mediaId","schema":{"type":"string","description":"The media ID"},"required":true,"description":"The media ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"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."},"description":{"description":"Prose shown under the media in the managed pull request comment.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"branch":{"anyOf":[{"type":"string","minLength":1,"maxLength":255,"description":"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."},{"type":"null"}]}}}}}},"responses":{"200":{"description":"The updated media","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```` ## List a media's versions > 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. ````json {"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Media","description":"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."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["media:read"]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Personal Access Token","description":"Authenticate as a **user** with a personal access token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nPersonal access tokens act on behalf of the user that created them\nand are required by endpoints that perform user actions, such as\nreviewing builds and posting comments."},"oauth2":{"type":"oauth2","description":"Authenticate as a **user** via an OAuth 2.1 access token obtained\nthrough the authorization-code (+ PKCE) flow. Used by the CLI and by\nMCP clients/agents. The token acts on behalf of the authorizing user,\nlimited to the granted scopes and organizations.","flows":{"authorizationCode":{"authorizationUrl":"https://app.argos-ci.com/oauth/authorize","tokenUrl":"https://app.argos-ci.com/oauth/token","refreshUrl":"https://app.argos-ci.com/oauth/token","scopes":{"profile":"Read your Argos profile and the list of teams you belong to.","projects:read":"Read your projects, builds, screenshots, diffs, tests, and analytics.","projects:write":"Create and configure projects and their settings.","builds:write":"Create and upload builds and screenshots.","reviews:write":"Approve, reject, or dismiss build reviews and ignore changes.","comments:read":"Read build comments and threads.","comments:write":"Post, edit, and delete comments, add reactions, and manage subscriptions.","media:read":"Read the images and videos uploaded to your teams.","media:write":"Upload images and videos, and delete the ones already uploaded.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"MediaVersion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of this version — what a comment's `mediaVersionId` points at."},"number":{"type":"number","description":"1-based, and what the UI calls the version. Increments each time the same name is uploaded again."},"fileUrl":{"type":"string","format":"uri","description":"URL of the image or video as it was at this version."},"posterUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Poster frame of a video. Always `null` for images."},"contentType":{"type":"string"},"sizeBytes":{"type":"number"},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"expiresAt":{"description":"When this version is deleted. Retention applies per version, so an old one ages out while the media and its share URL live on.","type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","number","fileUrl","posterUrl","contentType","sizeBytes","width","height","expiresAt","createdAt"],"additionalProperties":false,"description":"One uploaded version of a media"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/media/{mediaId}/versions":{"get":{"operationId":"listMediaVersions","summary":"List a media's versions","description":"A media's most recent uploaded versions, newest first, up to 100.\n\nA 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.\n\nWhen 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.","tags":["Media"],"parameters":[{"in":"path","name":"mediaId","schema":{"type":"string","description":"The media ID"},"required":true,"description":"The media ID"}],"responses":{"200":{"description":"The media's versions, newest first","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MediaVersion"}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```` ## Finalize a media upload > 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. ````json {"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Media","description":"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."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["media:write"]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Personal Access Token","description":"Authenticate as a **user** with a personal access token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nPersonal access tokens act on behalf of the user that created them\nand are required by endpoints that perform user actions, such as\nreviewing builds and posting comments."},"oauth2":{"type":"oauth2","description":"Authenticate as a **user** via an OAuth 2.1 access token obtained\nthrough the authorization-code (+ PKCE) flow. Used by the CLI and by\nMCP clients/agents. The token acts on behalf of the authorizing user,\nlimited to the granted scopes and organizations.","flows":{"authorizationCode":{"authorizationUrl":"https://app.argos-ci.com/oauth/authorize","tokenUrl":"https://app.argos-ci.com/oauth/token","refreshUrl":"https://app.argos-ci.com/oauth/token","scopes":{"profile":"Read your Argos profile and the list of teams you belong to.","projects:read":"Read your projects, builds, screenshots, diffs, tests, and analytics.","projects:write":"Create and configure projects and their settings.","builds:write":"Create and upload builds and screenshots.","reviews:write":"Approve, reject, or dismiss build reviews and ignore changes.","comments:read":"Read build comments and threads.","comments:write":"Post, edit, and delete comments, add reactions, and manage subscriptions.","media:read":"Read the images and videos uploaded to your teams.","media:write":"Upload images and videos, and delete the ones already uploaded.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"Media":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the media"},"name":{"type":"string","description":"The media's name, and its identity within its pull request. Uploading the same name again adds a version."},"state":{"anyOf":[{"type":"string","enum":["before","after"],"description":"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`."},{"type":"null"}]},"description":{"description":"Prose shown under the media in the pull request comment.","type":["string","null"]},"stage":{"type":"string","enum":["staged","published"],"description":"`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`."},"branch":{"description":"Branch this media was uploaded for. Kept after publishing, as a record of where it came from.","type":["string","null"]},"prNumber":{"description":"Pull request this media is published to, or `null` while it is staged.","type":["number","null"]},"url":{"type":"string","format":"uri","description":"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."},"markdown":{"type":"string","description":"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."},"version":{"type":"number","description":"Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again."},"versionCount":{"type":"number","description":"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."},"fileUrl":{"type":"string","format":"uri","description":"URL of the image or video itself, for an agent that wants to look at it."},"posterUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Poster frame of a video, derived by the image CDN. Always `null` for images."},"contentType":{"type":"string","description":"Content type of the media"},"sizeBytes":{"type":"number","description":"Size of the media, in bytes"},"width":{"description":"Width, in pixels","type":["number","null"]},"height":{"description":"Height, in pixels","type":["number","null"]},"visibility":{"type":"string","enum":["team","public"],"description":"Who can open the media share page. `team` requires an Argos session with access to the owning account; `public` only requires the share URL."},"status":{"type":"string","enum":["pending","ready"],"description":"`pending` until the bytes are uploaded, then `ready`. There is no processing step — Argos serves the bytes it was given."},"expiresAt":{"description":"When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.","type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","name","state","description","stage","branch","prNumber","url","markdown","version","versionCount","fileUrl","posterUrl","contentType","sizeBytes","width","height","visibility","status","expiresAt","createdAt"],"additionalProperties":false,"description":"A standalone image or video uploaded to Argos"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/media/{mediaId}/finalize":{"post":{"operationId":"finalizeMedia","summary":"Finalize a media upload","description":"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.","tags":["Media"],"parameters":[{"in":"path","name":"mediaId","schema":{"type":"string","description":"The media ID"},"required":true,"description":"The media ID"}],"responses":{"200":{"description":"The finalized media","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```` ## List a project's media > 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. ````json {"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Media","description":"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."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["media:read"]}],"components":{"securitySchemes":{"projectToken":{"type":"http","scheme":"bearer","bearerFormat":"Project Token","description":"Authenticate as a **project** with a project token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nYou can find your project token in your Argos project settings.\nProject tokens are used by CI and the SDK to create builds and\ndeployments."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"Personal Access Token","description":"Authenticate as a **user** with a personal access token.\n\nSend it as a bearer token in the `Authorization` header:\n\n```http\nAuthorization: Bearer \n```\n\nPersonal access tokens act on behalf of the user that created them\nand are required by endpoints that perform user actions, such as\nreviewing builds and posting comments."},"oauth2":{"type":"oauth2","description":"Authenticate as a **user** via an OAuth 2.1 access token obtained\nthrough the authorization-code (+ PKCE) flow. Used by the CLI and by\nMCP clients/agents. The token acts on behalf of the authorizing user,\nlimited to the granted scopes and organizations.","flows":{"authorizationCode":{"authorizationUrl":"https://app.argos-ci.com/oauth/authorize","tokenUrl":"https://app.argos-ci.com/oauth/token","refreshUrl":"https://app.argos-ci.com/oauth/token","scopes":{"profile":"Read your Argos profile and the list of teams you belong to.","projects:read":"Read your projects, builds, screenshots, diffs, tests, and analytics.","projects:write":"Create and configure projects and their settings.","builds:write":"Create and upload builds and screenshots.","reviews:write":"Approve, reject, or dismiss build reviews and ignore changes.","comments:read":"Read build comments and threads.","comments:write":"Post, edit, and delete comments, add reactions, and manage subscriptions.","media:read":"Read the images and videos uploaded to your teams.","media:write":"Upload images and videos, and delete the ones already uploaded.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"PageInfo":{"type":"object","properties":{"total":{"type":"number","description":"Total number of items"},"page":{"type":"number","description":"Current page number"},"perPage":{"type":"number","description":"Number of items per page"}},"required":["total","page","perPage"],"additionalProperties":false,"description":"Page information"},"Media":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the media"},"name":{"type":"string","description":"The media's name, and its identity within its pull request. Uploading the same name again adds a version."},"state":{"anyOf":[{"type":"string","enum":["before","after"],"description":"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`."},{"type":"null"}]},"description":{"description":"Prose shown under the media in the pull request comment.","type":["string","null"]},"stage":{"type":"string","enum":["staged","published"],"description":"`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`."},"branch":{"description":"Branch this media was uploaded for. Kept after publishing, as a record of where it came from.","type":["string","null"]},"prNumber":{"description":"Pull request this media is published to, or `null` while it is staged.","type":["number","null"]},"url":{"type":"string","format":"uri","description":"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."},"markdown":{"type":"string","description":"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."},"version":{"type":"number","description":"Which version this response describes: 1 for a first upload, incrementing each time the same name is uploaded again."},"versionCount":{"type":"number","description":"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."},"fileUrl":{"type":"string","format":"uri","description":"URL of the image or video itself, for an agent that wants to look at it."},"posterUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Poster frame of a video, derived by the image CDN. Always `null` for images."},"contentType":{"type":"string","description":"Content type of the media"},"sizeBytes":{"type":"number","description":"Size of the media, in bytes"},"width":{"description":"Width, in pixels","type":["number","null"]},"height":{"description":"Height, in pixels","type":["number","null"]},"visibility":{"type":"string","enum":["team","public"],"description":"Who can open the media share page. `team` requires an Argos session with access to the owning account; `public` only requires the share URL."},"status":{"type":"string","enum":["pending","ready"],"description":"`pending` until the bytes are uploaded, then `ready`. There is no processing step — Argos serves the bytes it was given."},"expiresAt":{"description":"When this version is deleted. Set from your plan's retention, counted from the upload rather than from the last view.","type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","name","state","description","stage","branch","prNumber","url","markdown","version","versionCount","fileUrl","posterUrl","contentType","sizeBytes","width","height","visibility","status","expiresAt","createdAt"],"additionalProperties":false,"description":"A standalone image or video uploaded to Argos"},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["error"],"additionalProperties":false,"description":"Error response"}}},"paths":{"/projects/{owner}/{project}/media":{"get":{"operationId":"listMedia","summary":"List a project's media","description":"List the standalone images and videos uploaded to a project, most recent first.\n\n`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.","tags":["Media"],"parameters":[{"in":"path","name":"owner","schema":{"type":"string","minLength":1},"required":true},{"in":"path","name":"project","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"perPage","schema":{"description":"Number of items per page (max 100)","type":"string"},"description":"Number of items per page (max 100)"},{"in":"query","name":"page","schema":{"description":"Page number","type":"string"},"description":"Page number"},{"in":"query","name":"branch","schema":{"description":"Only media uploaded for this branch, staged and published alike.","type":"string","minLength":1},"description":"Only media uploaded for this branch, staged and published alike."},{"in":"query","name":"prNumber","schema":{"description":"Only media published to this pull request.","type":"integer","minimum":1,"maximum":9007199254740991},"description":"Only media published to this pull request."},{"in":"query","name":"stage","schema":{"description":"Restrict to staged media (no pull request yet) or to published media.","type":"string","enum":["staged","published"]},"description":"Restrict to staged media (no pull request yet) or to published media."},{"in":"query","name":"search","schema":{"description":"Match media on their file name or slug.","type":"string"},"description":"Match media on their file name or slug."},{"in":"query","name":"type","schema":{"description":"Restrict to images or to videos.","type":"string","enum":["image","video"]},"description":"Restrict to images or to videos."}],"responses":{"200":{"description":"List of media","content":{"application/json":{"schema":{"type":"object","properties":{"pageInfo":{"$ref":"#/components/schemas/PageInfo"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Media"}}},"required":["pageInfo","results"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ```` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://argos-ci.com/docs/api-reference/reference/media.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.