> 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/builds.md).

# Builds

Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow.

## Create a build

> Create a build and receive signed upload targets for its screenshots and Playwright traces. The response lists, for every file Argos doesn't already have, a secure \`postUrl\` with \`fields\` (or a legacy \`putUrl\`) to upload it to. Supports single and parallel builds.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Builds","description":"Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]}],"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 <project-token>\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."}},"schemas":{"Sha1Hash":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"SHA1 hash"},"GitBranch":{"type":"string","minLength":1},"Sha256Hash":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$","description":"SHA256 hash"},"ScreenshotUploadRequest":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/Sha256Hash"},"contentType":{"description":"Content type of the snapshot file","type":"string"}},"required":["key","contentType"],"description":"Screenshot file to upload"},"Build":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BuildId"},"number":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"The build number"},"head":{"description":"The head reference of the build","$ref":"#/components/schemas/BuildGitReference"},"base":{"anyOf":[{"$ref":"#/components/schemas/BuildGitReference"},{"type":"null"}],"description":"The base reference of the build"},"status":{"anyOf":[{"type":"string","enum":["accepted","rejected"]},{"type":"string","enum":["no-changes","changes-detected"]},{"type":"string","enum":["expired","pending","progress","error","aborted"]}],"description":"The status of the build"},"conclusion":{"anyOf":[{"type":"string","enum":["no-changes","changes-detected"]},{"type":"null"}],"description":"The conclusion of the build"},"stats":{"anyOf":[{"type":"object","properties":{"added":{"type":"number","description":"Added snapshots"},"removed":{"type":"number","description":"Removed snapshots"},"unchanged":{"type":"number","description":"Unchanged snapshots"},"changed":{"type":"number","description":"Changed snapshots"},"ignored":{"type":"number","description":"Ignored snapshots"},"failure":{"type":"number","description":"Failure screenshots"},"retryFailure":{"type":"number","description":"Retry failure screenshots"},"total":{"type":"number","description":"Total number of snapshots"}},"required":["added","removed","unchanged","changed","ignored","failure","retryFailure","total"],"additionalProperties":false},{"type":"null"}],"description":"Stats of the diffs present in the build"},"metadata":{"anyOf":[{"type":"object","properties":{"testReport":{"description":"Test suite report","type":"object","properties":{"status":{"type":"string","enum":["passed","failed","timedout","interrupted"],"description":"Status of the test suite"},"stats":{"type":"object","properties":{"startTime":{"description":"Date when the test suite started","type":"string"},"duration":{"description":"Duration of the test suite in milliseconds","type":"number"}},"additionalProperties":false}},"required":["status"],"additionalProperties":false}},"additionalProperties":false,"description":"Metadata associated to the build"},{"type":"null"}]},"url":{"type":"string","format":"uri","description":"The URL of the build"},"notification":{"anyOf":[{"type":"object","properties":{"description":{"type":"string"},"context":{"type":"string"},"github":{"type":"object","properties":{"state":{"type":"string","enum":["pending","success","error","failure"]}},"required":["state"],"additionalProperties":false},"gitlab":{"type":"object","properties":{"state":{"type":"string","enum":["pending","running","success","failed","canceled"]}},"required":["state"],"additionalProperties":false},"url":{"type":"string","format":"uri"}},"required":["description","context","github","gitlab","url"],"additionalProperties":false},{"type":"null"}],"description":"The notification payload for the build"}},"required":["id","number","head","base","status","conclusion","stats","metadata","url","notification"],"additionalProperties":false,"description":"Build"},"BuildId":{"type":"string","description":"A unique identifier for the build"},"BuildGitReference":{"type":"object","properties":{"sha":{"description":"The commit SHA","$ref":"#/components/schemas/Sha1Hash"},"branch":{"type":"string","description":"The branch name"}},"required":["sha","branch"],"additionalProperties":false,"description":"Git reference"},"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":{"/builds":{"post":{"operationId":"createBuild","summary":"Create a build","description":"Create a build and receive signed upload targets for its screenshots and Playwright traces. The response lists, for every file Argos doesn't already have, a secure `postUrl` with `fields` (or a legacy `putUrl`) to upload it to. Supports single and parallel builds.","tags":["Builds"],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"commit":{"description":"The commit the build is running on","$ref":"#/components/schemas/Sha1Hash"},"branch":{"description":"The branch the build is running on","$ref":"#/components/schemas/GitBranch"},"pwTraceKeys":{"description":"Keys of Playwright trace files","type":"array","items":{"$ref":"#/components/schemas/Sha256Hash"}},"name":{"description":"The name of the build (for multi-build setups)","anyOf":[{"type":"string"},{"type":"null"}]},"parallel":{"description":"Whether to run the build in parallel","anyOf":[{"type":"boolean"},{"type":"null"}]},"parallelNonce":{"description":"A unique nonce for the parallel build","anyOf":[{"type":"string"},{"type":"null"}]},"prNumber":{"description":"The pull request number","anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]},"prHeadCommit":{"description":"The head commit of the pull request","anyOf":[{"$ref":"#/components/schemas/Sha1Hash"},{"type":"null"}]},"referenceCommit":{"description":"The commit to use as a reference for the build","anyOf":[{"$ref":"#/components/schemas/Sha1Hash"},{"type":"null"}]},"referenceBranch":{"description":"The branch to use as a reference for the build","anyOf":[{"type":"string"},{"type":"null"}]},"parentCommits":{"description":"The parent commits of the build","anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Sha1Hash"}},{"type":"null"}]},"mode":{"description":"The mode in which the build is running","anyOf":[{"type":"string","enum":["ci","monitoring"]},{"type":"null"}]},"ciProvider":{"description":"The CI provider being used","anyOf":[{"type":"string"},{"type":"null"}]},"argosSdk":{"description":"The version of the Argos SDK being used","anyOf":[{"type":"string"},{"type":"null"}]},"runId":{"description":"The ID of the current run","anyOf":[{"type":"string"},{"type":"null"}]},"runAttempt":{"description":"The attempt number of the current run","anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]},"skipped":{"description":"Whether the build was skipped, not comparing anything and always succeeding","anyOf":[{"type":"boolean"},{"type":"null"}]},"mergeQueue":{"description":"Whether the build has been created in a merge queue","anyOf":[{"type":"boolean"},{"type":"null"}]},"mergeQueuePrNumbers":{"description":"Pull request numbers aggregated by the merge queue build. Requires `mergeQueue` to be `true`.","anyOf":[{"minItems":1,"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"null"}]},"subset":{"description":"Indicates whether this build contains only a subset of screenshots.\nThis is useful when a build is created from an incomplete test suite where some tests are skipped.","anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["commit","branch"]},{"anyOf":[{"type":"object","properties":{"screenshotKeys":{"type":"array","items":{"$ref":"#/components/schemas/Sha256Hash"},"deprecated":true,"description":"Keys of screenshot files"},"screenshots":{"not":{}}},"required":["screenshotKeys"]},{"type":"object","properties":{"screenshots":{"maxItems":5000,"type":"array","items":{"$ref":"#/components/schemas/ScreenshotUploadRequest"},"description":"Screenshot files to upload"},"screenshotKeys":{"not":{}}},"required":["screenshots"]}]}]}}}},"responses":{"201":{"description":"Result of build creation","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"$ref":"#/components/schemas/Build"},"screenshots":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"putUrl":{"type":"string","format":"uri","deprecated":true,"description":"Deprecated. Use postUrl and fields instead."}},"required":["key","putUrl"],"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string"},"postUrl":{"type":"string","format":"uri"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["key","postUrl","fields"],"additionalProperties":false}]}},"pwTraces":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"putUrl":{"type":"string","format":"uri","deprecated":true,"description":"Deprecated. Use postUrl and fields instead."}},"required":["key","putUrl"],"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string"},"postUrl":{"type":"string","format":"uri"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["key","postUrl","fields"],"additionalProperties":false}]}}},"required":["build","screenshots","pwTraces"],"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"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````

## Finalize parallel builds

> Mark every parallel shard sharing the given \`parallelNonce\` as complete. Once finalized, Argos compares the aggregated screenshots and starts processing the build.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Builds","description":"Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]}],"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 <project-token>\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."}},"schemas":{"Build":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BuildId"},"number":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"The build number"},"head":{"description":"The head reference of the build","$ref":"#/components/schemas/BuildGitReference"},"base":{"anyOf":[{"$ref":"#/components/schemas/BuildGitReference"},{"type":"null"}],"description":"The base reference of the build"},"status":{"anyOf":[{"type":"string","enum":["accepted","rejected"]},{"type":"string","enum":["no-changes","changes-detected"]},{"type":"string","enum":["expired","pending","progress","error","aborted"]}],"description":"The status of the build"},"conclusion":{"anyOf":[{"type":"string","enum":["no-changes","changes-detected"]},{"type":"null"}],"description":"The conclusion of the build"},"stats":{"anyOf":[{"type":"object","properties":{"added":{"type":"number","description":"Added snapshots"},"removed":{"type":"number","description":"Removed snapshots"},"unchanged":{"type":"number","description":"Unchanged snapshots"},"changed":{"type":"number","description":"Changed snapshots"},"ignored":{"type":"number","description":"Ignored snapshots"},"failure":{"type":"number","description":"Failure screenshots"},"retryFailure":{"type":"number","description":"Retry failure screenshots"},"total":{"type":"number","description":"Total number of snapshots"}},"required":["added","removed","unchanged","changed","ignored","failure","retryFailure","total"],"additionalProperties":false},{"type":"null"}],"description":"Stats of the diffs present in the build"},"metadata":{"anyOf":[{"type":"object","properties":{"testReport":{"description":"Test suite report","type":"object","properties":{"status":{"type":"string","enum":["passed","failed","timedout","interrupted"],"description":"Status of the test suite"},"stats":{"type":"object","properties":{"startTime":{"description":"Date when the test suite started","type":"string"},"duration":{"description":"Duration of the test suite in milliseconds","type":"number"}},"additionalProperties":false}},"required":["status"],"additionalProperties":false}},"additionalProperties":false,"description":"Metadata associated to the build"},{"type":"null"}]},"url":{"type":"string","format":"uri","description":"The URL of the build"},"notification":{"anyOf":[{"type":"object","properties":{"description":{"type":"string"},"context":{"type":"string"},"github":{"type":"object","properties":{"state":{"type":"string","enum":["pending","success","error","failure"]}},"required":["state"],"additionalProperties":false},"gitlab":{"type":"object","properties":{"state":{"type":"string","enum":["pending","running","success","failed","canceled"]}},"required":["state"],"additionalProperties":false},"url":{"type":"string","format":"uri"}},"required":["description","context","github","gitlab","url"],"additionalProperties":false},{"type":"null"}],"description":"The notification payload for the build"}},"required":["id","number","head","base","status","conclusion","stats","metadata","url","notification"],"additionalProperties":false,"description":"Build"},"BuildId":{"type":"string","description":"A unique identifier for the build"},"BuildGitReference":{"type":"object","properties":{"sha":{"description":"The commit SHA","$ref":"#/components/schemas/Sha1Hash"},"branch":{"type":"string","description":"The branch name"}},"required":["sha","branch"],"additionalProperties":false,"description":"Git reference"},"Sha1Hash":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"SHA1 hash"},"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":{"/builds/finalize":{"post":{"operationId":"finalizeBuilds","summary":"Finalize parallel builds","description":"Mark every parallel shard sharing the given `parallelNonce` as complete. Once finalized, Argos compares the aggregated screenshots and starts processing the build.","tags":["Builds"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"parallelNonce":{"type":"string","minLength":1}},"required":["parallelNonce"]}}}},"responses":{"200":{"description":"Result of build finalization","content":{"application/json":{"schema":{"type":"object","properties":{"builds":{"type":"array","items":{"$ref":"#/components/schemas/Build"}}},"required":["builds"],"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"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````

## Find an eligible baseline from a list of commits

> Find the build eligible to be used as a baseline among a list of commits. Useful when no Git provider is connected: the CLI can send the candidate ancestor commits and let Argos pick the closest one that has an eligible (complete, valid, approved and not rejected) baseline build.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Builds","description":"Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]}],"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 <project-token>\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."}},"schemas":{"Sha1Hash":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"SHA1 hash"},"Build":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BuildId"},"number":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"The build number"},"head":{"description":"The head reference of the build","$ref":"#/components/schemas/BuildGitReference"},"base":{"anyOf":[{"$ref":"#/components/schemas/BuildGitReference"},{"type":"null"}],"description":"The base reference of the build"},"status":{"anyOf":[{"type":"string","enum":["accepted","rejected"]},{"type":"string","enum":["no-changes","changes-detected"]},{"type":"string","enum":["expired","pending","progress","error","aborted"]}],"description":"The status of the build"},"conclusion":{"anyOf":[{"type":"string","enum":["no-changes","changes-detected"]},{"type":"null"}],"description":"The conclusion of the build"},"stats":{"anyOf":[{"type":"object","properties":{"added":{"type":"number","description":"Added snapshots"},"removed":{"type":"number","description":"Removed snapshots"},"unchanged":{"type":"number","description":"Unchanged snapshots"},"changed":{"type":"number","description":"Changed snapshots"},"ignored":{"type":"number","description":"Ignored snapshots"},"failure":{"type":"number","description":"Failure screenshots"},"retryFailure":{"type":"number","description":"Retry failure screenshots"},"total":{"type":"number","description":"Total number of snapshots"}},"required":["added","removed","unchanged","changed","ignored","failure","retryFailure","total"],"additionalProperties":false},{"type":"null"}],"description":"Stats of the diffs present in the build"},"metadata":{"anyOf":[{"type":"object","properties":{"testReport":{"description":"Test suite report","type":"object","properties":{"status":{"type":"string","enum":["passed","failed","timedout","interrupted"],"description":"Status of the test suite"},"stats":{"type":"object","properties":{"startTime":{"description":"Date when the test suite started","type":"string"},"duration":{"description":"Duration of the test suite in milliseconds","type":"number"}},"additionalProperties":false}},"required":["status"],"additionalProperties":false}},"additionalProperties":false,"description":"Metadata associated to the build"},{"type":"null"}]},"url":{"type":"string","format":"uri","description":"The URL of the build"},"notification":{"anyOf":[{"type":"object","properties":{"description":{"type":"string"},"context":{"type":"string"},"github":{"type":"object","properties":{"state":{"type":"string","enum":["pending","success","error","failure"]}},"required":["state"],"additionalProperties":false},"gitlab":{"type":"object","properties":{"state":{"type":"string","enum":["pending","running","success","failed","canceled"]}},"required":["state"],"additionalProperties":false},"url":{"type":"string","format":"uri"}},"required":["description","context","github","gitlab","url"],"additionalProperties":false},{"type":"null"}],"description":"The notification payload for the build"}},"required":["id","number","head","base","status","conclusion","stats","metadata","url","notification"],"additionalProperties":false,"description":"Build"},"BuildId":{"type":"string","description":"A unique identifier for the build"},"BuildGitReference":{"type":"object","properties":{"sha":{"description":"The commit SHA","$ref":"#/components/schemas/Sha1Hash"},"branch":{"type":"string","description":"The branch name"}},"required":["sha","branch"],"additionalProperties":false,"description":"Git reference"},"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":{"/baseline":{"post":{"operationId":"findBaseline","summary":"Find an eligible baseline from a list of commits","description":"Find the build eligible to be used as a baseline among a list of commits. Useful when no Git provider is connected: the CLI can send the candidate ancestor commits and let Argos pick the closest one that has an eligible (complete, valid, approved and not rejected) baseline build.","tags":["Builds"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"commits":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/Sha1Hash"},"description":"The commits to look for an eligible baseline, ordered from the closest to the furthest ancestor. The first commit with an eligible baseline wins."},"name":{"default":"default","description":"The name of the build to find a baseline for.","type":"string","minLength":1},"mode":{"default":"ci","description":"The mode of the build to find a baseline for.","type":"string","enum":["ci","monitoring"]}},"required":["commits"]}}}},"responses":{"200":{"description":"The eligible baseline build, or null when none is found","content":{"application/json":{"schema":{"type":"object","properties":{"baseline":{"anyOf":[{"$ref":"#/components/schemas/Build"},{"type":"null"}],"description":"The eligible baseline build found among the commits, or null when none is found."}},"required":["baseline"],"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"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````

## Update a build

> Add screenshots to an existing build and update its metadata. Used to push the screenshots of a parallel shard, identified by \`parallelIndex\` and \`parallelTotal\`.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Builds","description":"Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]}],"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 <project-token>\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."}},"schemas":{"BuildId":{"type":"string","description":"A unique identifier for the build"},"ScreenshotInput":{"type":"object","properties":{"key":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$"},"name":{"type":"string"},"baseName":{"description":"Name(s) to compare this screenshot against, instead of its own name. An array is tried in order: the first name that exists in the baseline wins, which lets a new screenshot fall back to an existing one.","anyOf":[{"anyOf":[{"type":"string"},{"minItems":1,"type":"array","items":{"type":"string"}}]},{"type":"null"}]},"parentName":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","properties":{"$schema":{"description":"Ignored. Can be set to get completions, validations and documentation in some editors.","type":"string"},"url":{"description":"The URL of the page that was screenshotted","anyOf":[{"type":"string"},{"type":"null"}]},"previewUrl":{"description":"An URL to an accessible preview of the screenshot","anyOf":[{"type":"string"},{"type":"null"}]},"viewport":{"anyOf":[{"type":"object","properties":{"width":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The width of the viewport"},"height":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The height of the viewport"}},"required":["width","height"],"description":"The viewport dimensions when the screenshot was taken"},{"type":"null"}]},"colorScheme":{"description":"The color scheme when the screenshot was taken","anyOf":[{"type":"string","enum":["light","dark"]},{"type":"null"}]},"mediaType":{"description":"The media type when the screenshot was taken","anyOf":[{"type":"string","enum":["screen","print"]},{"type":"null"}]},"test":{"anyOf":[{"type":"object","properties":{"id":{"description":"The unique identifier of the test","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string","description":"The title of the test"},"titlePath":{"type":"array","items":{"type":"string"},"description":"The path of titles leading to the test"},"retries":{"description":"The number of retries for the test","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"retry":{"description":"The current retry count","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"repeat":{"description":"The repeat count for the test","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"location":{"description":"The location of the test in the source code","type":"object","properties":{"file":{"type":"string","description":"The located file"},"line":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The line number in the file"},"column":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The column number in the file"}},"required":["file","line","column"]},"annotations":{"description":"Annotations associated to the test","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of annotation"},"description":{"description":"The description of the annotation","type":"string"},"location":{"description":"The location of the annotation in the source code","type":"object","properties":{"file":{"type":"string","description":"The located file"},"line":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The line number in the file"},"column":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The column number in the file"}},"required":["file","line","column"]}},"required":["type"],"description":"A test annotation"}},"tags":{"description":"Tags associated to the test","type":"array","items":{"type":"string"}}},"required":["title","titlePath"],"description":"The test that generated the screenshot"},{"type":"null"}]},"browser":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","description":"The name of the browser"},"version":{"type":"string","description":"The version of the browser"}},"required":["name","version"],"description":"The browser that generated the screenshot"},{"type":"null"}]},"automationLibrary":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation library"},"version":{"type":"string","description":"The version of the automation library"}},"required":["name","version"],"description":"The automation library that generated the screenshot"},"sdk":{"type":"object","properties":{"name":{"type":"string","description":"The name of the Argos SDK"},"version":{"type":"string","description":"The version of the Argos SDK"}},"required":["name","version"],"description":"The Argos SDK that generated the screenshot"},"story":{"description":"Storybook story metadata","anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the story"},"tags":{"description":"Tags attached to the story","type":"array","items":{"type":"string"}},"mode":{"description":"Story mode","type":"string"},"play":{"description":"True if the story has a play function","type":"boolean"}},"required":["id"],"description":"Storybook story metadata"},{"type":"null"}]},"tags":{"description":"Tags associated to the screenshot","type":"array","items":{"type":"string"}}},"required":["automationLibrary","sdk"],"description":"Metadata about a screenshot"},{"type":"null"}]},"pwTraceKey":{"anyOf":[{"type":"string","pattern":"^[A-Fa-f0-9]{64}$"},{"type":"null"}]},"threshold":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]},"contentType":{"description":"Content type of the snapshot file","type":"string"}},"required":["key","name"],"description":"Screenshot input"},"BuildMetadata":{"description":"Build metadata","type":"object","properties":{"testReport":{"description":"Test suite report","type":"object","properties":{"status":{"type":"string","enum":["passed","failed","timedout","interrupted"],"description":"Status of the test suite"},"stats":{"type":"object","properties":{"startTime":{"description":"Date when the test suite started","type":"string"},"duration":{"description":"Duration of the test suite in milliseconds","type":"number"}}}},"required":["status"]}}},"Build":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BuildId"},"number":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"The build number"},"head":{"description":"The head reference of the build","$ref":"#/components/schemas/BuildGitReference"},"base":{"anyOf":[{"$ref":"#/components/schemas/BuildGitReference"},{"type":"null"}],"description":"The base reference of the build"},"status":{"anyOf":[{"type":"string","enum":["accepted","rejected"]},{"type":"string","enum":["no-changes","changes-detected"]},{"type":"string","enum":["expired","pending","progress","error","aborted"]}],"description":"The status of the build"},"conclusion":{"anyOf":[{"type":"string","enum":["no-changes","changes-detected"]},{"type":"null"}],"description":"The conclusion of the build"},"stats":{"anyOf":[{"type":"object","properties":{"added":{"type":"number","description":"Added snapshots"},"removed":{"type":"number","description":"Removed snapshots"},"unchanged":{"type":"number","description":"Unchanged snapshots"},"changed":{"type":"number","description":"Changed snapshots"},"ignored":{"type":"number","description":"Ignored snapshots"},"failure":{"type":"number","description":"Failure screenshots"},"retryFailure":{"type":"number","description":"Retry failure screenshots"},"total":{"type":"number","description":"Total number of snapshots"}},"required":["added","removed","unchanged","changed","ignored","failure","retryFailure","total"],"additionalProperties":false},{"type":"null"}],"description":"Stats of the diffs present in the build"},"metadata":{"anyOf":[{"type":"object","properties":{"testReport":{"description":"Test suite report","type":"object","properties":{"status":{"type":"string","enum":["passed","failed","timedout","interrupted"],"description":"Status of the test suite"},"stats":{"type":"object","properties":{"startTime":{"description":"Date when the test suite started","type":"string"},"duration":{"description":"Duration of the test suite in milliseconds","type":"number"}},"additionalProperties":false}},"required":["status"],"additionalProperties":false}},"additionalProperties":false,"description":"Metadata associated to the build"},{"type":"null"}]},"url":{"type":"string","format":"uri","description":"The URL of the build"},"notification":{"anyOf":[{"type":"object","properties":{"description":{"type":"string"},"context":{"type":"string"},"github":{"type":"object","properties":{"state":{"type":"string","enum":["pending","success","error","failure"]}},"required":["state"],"additionalProperties":false},"gitlab":{"type":"object","properties":{"state":{"type":"string","enum":["pending","running","success","failed","canceled"]}},"required":["state"],"additionalProperties":false},"url":{"type":"string","format":"uri"}},"required":["description","context","github","gitlab","url"],"additionalProperties":false},{"type":"null"}],"description":"The notification payload for the build"}},"required":["id","number","head","base","status","conclusion","stats","metadata","url","notification"],"additionalProperties":false,"description":"Build"},"BuildGitReference":{"type":"object","properties":{"sha":{"description":"The commit SHA","$ref":"#/components/schemas/Sha1Hash"},"branch":{"type":"string","description":"The branch name"}},"required":["sha","branch"],"additionalProperties":false,"description":"Git reference"},"Sha1Hash":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"SHA1 hash"},"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":{"/builds/{buildId}":{"put":{"operationId":"updateBuild","summary":"Update a build","description":"Add screenshots to an existing build and update its metadata. Used to push the screenshots of a parallel shard, identified by `parallelIndex` and `parallelTotal`.","tags":["Builds"],"parameters":[{"in":"path","name":"buildId","schema":{"$ref":"#/components/schemas/BuildId"},"required":true,"description":"A unique identifier for the build"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"screenshots":{"type":"array","items":{"$ref":"#/components/schemas/ScreenshotInput"}},"parallel":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"parallelTotal":{"anyOf":[{"type":"integer","minimum":-1,"maximum":9007199254740991},{"type":"null"}]},"parallelIndex":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]},"final":{"description":"Only used for non-parallel builds. Indicates that this is the last request of the build, so Argos can finalize it. A build whose screenshots are too large to fit in a single request can split them across several sequential requests, leaving `final` falsy on every request but the last. Defaults to `true`.","anyOf":[{"type":"boolean"},{"type":"null"}]},"metadata":{"$ref":"#/components/schemas/BuildMetadata"}},"required":["screenshots"]}}}},"responses":{"200":{"description":"Result of build update","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"$ref":"#/components/schemas/Build"}},"required":["build"],"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"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````

## List a project's builds

> List the builds of a project, most recent first. Results are paginated. Use \`search\` to match builds by name, branch or commit, and \`distinctName\` to return only the latest build per name and commit.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Builds","description":"Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["projects: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 <project-token>\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 <personal-access-token>\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.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"Sha1Hash":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"SHA1 hash"},"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"},"Build":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BuildId"},"number":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"The build number"},"head":{"description":"The head reference of the build","$ref":"#/components/schemas/BuildGitReference"},"base":{"anyOf":[{"$ref":"#/components/schemas/BuildGitReference"},{"type":"null"}],"description":"The base reference of the build"},"status":{"anyOf":[{"type":"string","enum":["accepted","rejected"]},{"type":"string","enum":["no-changes","changes-detected"]},{"type":"string","enum":["expired","pending","progress","error","aborted"]}],"description":"The status of the build"},"conclusion":{"anyOf":[{"type":"string","enum":["no-changes","changes-detected"]},{"type":"null"}],"description":"The conclusion of the build"},"stats":{"anyOf":[{"type":"object","properties":{"added":{"type":"number","description":"Added snapshots"},"removed":{"type":"number","description":"Removed snapshots"},"unchanged":{"type":"number","description":"Unchanged snapshots"},"changed":{"type":"number","description":"Changed snapshots"},"ignored":{"type":"number","description":"Ignored snapshots"},"failure":{"type":"number","description":"Failure screenshots"},"retryFailure":{"type":"number","description":"Retry failure screenshots"},"total":{"type":"number","description":"Total number of snapshots"}},"required":["added","removed","unchanged","changed","ignored","failure","retryFailure","total"],"additionalProperties":false},{"type":"null"}],"description":"Stats of the diffs present in the build"},"metadata":{"anyOf":[{"type":"object","properties":{"testReport":{"description":"Test suite report","type":"object","properties":{"status":{"type":"string","enum":["passed","failed","timedout","interrupted"],"description":"Status of the test suite"},"stats":{"type":"object","properties":{"startTime":{"description":"Date when the test suite started","type":"string"},"duration":{"description":"Duration of the test suite in milliseconds","type":"number"}},"additionalProperties":false}},"required":["status"],"additionalProperties":false}},"additionalProperties":false,"description":"Metadata associated to the build"},{"type":"null"}]},"url":{"type":"string","format":"uri","description":"The URL of the build"},"notification":{"anyOf":[{"type":"object","properties":{"description":{"type":"string"},"context":{"type":"string"},"github":{"type":"object","properties":{"state":{"type":"string","enum":["pending","success","error","failure"]}},"required":["state"],"additionalProperties":false},"gitlab":{"type":"object","properties":{"state":{"type":"string","enum":["pending","running","success","failed","canceled"]}},"required":["state"],"additionalProperties":false},"url":{"type":"string","format":"uri"}},"required":["description","context","github","gitlab","url"],"additionalProperties":false},{"type":"null"}],"description":"The notification payload for the build"}},"required":["id","number","head","base","status","conclusion","stats","metadata","url","notification"],"additionalProperties":false,"description":"Build"},"BuildId":{"type":"string","description":"A unique identifier for the build"},"BuildGitReference":{"type":"object","properties":{"sha":{"description":"The commit SHA","$ref":"#/components/schemas/Sha1Hash"},"branch":{"type":"string","description":"The branch name"}},"required":["sha","branch"],"additionalProperties":false,"description":"Git reference"},"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}/builds":{"get":{"operationId":"listBuilds","summary":"List a project's builds","description":"List the builds of a project, most recent first. Results are paginated. Use `search` to match builds by name, branch or commit, and `distinctName` to return only the latest build per name and commit.","tags":["Builds"],"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":"head","schema":{"type":"string","minLength":1}},{"in":"query","name":"headSha","schema":{"$ref":"#/components/schemas/Sha1Hash"}},{"in":"query","name":"search","schema":{"description":"Search builds by name, branch (substring) or commit (prefix).","type":"string","minLength":1},"description":"Search builds by name, branch (substring) or commit (prefix)."},{"in":"query","name":"distinctName","schema":{"description":"Only return the latest builds created, unique by name and commit.","type":"string"},"description":"Only return the latest builds created, unique by name and commit."}],"responses":{"200":{"description":"List of builds","content":{"application/json":{"schema":{"type":"object","properties":{"pageInfo":{"$ref":"#/components/schemas/PageInfo"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Build"}}},"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"}}}}}}}}}
````

## Get a build

> Retrieve a single build by its number within a project, including its status and metadata.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Builds","description":"Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["projects: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 <project-token>\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 <personal-access-token>\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.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"BuildNumber":{"description":"The build number","type":"string"},"Build":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/BuildId"},"number":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"The build number"},"head":{"description":"The head reference of the build","$ref":"#/components/schemas/BuildGitReference"},"base":{"anyOf":[{"$ref":"#/components/schemas/BuildGitReference"},{"type":"null"}],"description":"The base reference of the build"},"status":{"anyOf":[{"type":"string","enum":["accepted","rejected"]},{"type":"string","enum":["no-changes","changes-detected"]},{"type":"string","enum":["expired","pending","progress","error","aborted"]}],"description":"The status of the build"},"conclusion":{"anyOf":[{"type":"string","enum":["no-changes","changes-detected"]},{"type":"null"}],"description":"The conclusion of the build"},"stats":{"anyOf":[{"type":"object","properties":{"added":{"type":"number","description":"Added snapshots"},"removed":{"type":"number","description":"Removed snapshots"},"unchanged":{"type":"number","description":"Unchanged snapshots"},"changed":{"type":"number","description":"Changed snapshots"},"ignored":{"type":"number","description":"Ignored snapshots"},"failure":{"type":"number","description":"Failure screenshots"},"retryFailure":{"type":"number","description":"Retry failure screenshots"},"total":{"type":"number","description":"Total number of snapshots"}},"required":["added","removed","unchanged","changed","ignored","failure","retryFailure","total"],"additionalProperties":false},{"type":"null"}],"description":"Stats of the diffs present in the build"},"metadata":{"anyOf":[{"type":"object","properties":{"testReport":{"description":"Test suite report","type":"object","properties":{"status":{"type":"string","enum":["passed","failed","timedout","interrupted"],"description":"Status of the test suite"},"stats":{"type":"object","properties":{"startTime":{"description":"Date when the test suite started","type":"string"},"duration":{"description":"Duration of the test suite in milliseconds","type":"number"}},"additionalProperties":false}},"required":["status"],"additionalProperties":false}},"additionalProperties":false,"description":"Metadata associated to the build"},{"type":"null"}]},"url":{"type":"string","format":"uri","description":"The URL of the build"},"notification":{"anyOf":[{"type":"object","properties":{"description":{"type":"string"},"context":{"type":"string"},"github":{"type":"object","properties":{"state":{"type":"string","enum":["pending","success","error","failure"]}},"required":["state"],"additionalProperties":false},"gitlab":{"type":"object","properties":{"state":{"type":"string","enum":["pending","running","success","failed","canceled"]}},"required":["state"],"additionalProperties":false},"url":{"type":"string","format":"uri"}},"required":["description","context","github","gitlab","url"],"additionalProperties":false},{"type":"null"}],"description":"The notification payload for the build"}},"required":["id","number","head","base","status","conclusion","stats","metadata","url","notification"],"additionalProperties":false,"description":"Build"},"BuildId":{"type":"string","description":"A unique identifier for the build"},"BuildGitReference":{"type":"object","properties":{"sha":{"description":"The commit SHA","$ref":"#/components/schemas/Sha1Hash"},"branch":{"type":"string","description":"The branch name"}},"required":["sha","branch"],"additionalProperties":false,"description":"Git reference"},"Sha1Hash":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"SHA1 hash"},"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}/builds/{buildNumber}":{"get":{"operationId":"getBuild","summary":"Get a build","description":"Retrieve a single build by its number within a project, including its status and metadata.","tags":["Builds"],"parameters":[{"in":"path","name":"owner","schema":{"type":"string","minLength":1},"required":true},{"in":"path","name":"project","schema":{"type":"string","minLength":1},"required":true},{"in":"path","name":"buildNumber","schema":{"$ref":"#/components/schemas/BuildNumber"},"required":true,"description":"The build number"}],"responses":{"200":{"description":"Build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"}}}},"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 build's screenshot diffs

> List the screenshot diffs of a build, with pagination. Each diff compares a baseline screenshot to the one captured by the build. Each diff also carries its test's flakiness metrics and, when it is a change, its ignore state and occurrence count — so you can tell whether a change is worth reviewing or is just a flaky one. Use \`needsReview\` to return only the diffs that require review.

````json
{"openapi":"3.2.0","info":{"title":"Argos API","version":"2.0.0"},"tags":[{"name":"Builds","description":"Create, finalize, update, and inspect visual testing builds, including their screenshot diffs. This is the core of the visual testing workflow."}],"servers":[{"url":"https://api.argos-ci.com/v2","description":"API Endpoint"}],"security":[{"projectToken":[]},{"personalAccessToken":[]},{"oauth2":["projects: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 <project-token>\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 <personal-access-token>\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.","account:admin":"Manage organization settings and members."}}}}},"schemas":{"BuildNumber":{"description":"The build number","type":"string"},"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"},"SnapshotDiff":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the snapshot diff"},"name":{"type":"string","description":"Name of the snapshot diff"},"status":{"type":"string","enum":["pending","removed","failure","added","changed","unchanged","retryFailure","ignored"],"description":"Status of the snapshot diff"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Similarity score between snapshots"},"group":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Grouping key for the snapshot diff"},"parentName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Parent name of the snapshot (usually the story id)"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"URL of the diff image"},"base":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the snapshot"},"name":{"type":"string","description":"Name of the snapshot"},"metadata":{"anyOf":[{"type":"object","properties":{"$schema":{"description":"Ignored. Can be set to get completions, validations and documentation in some editors.","type":"string"},"url":{"description":"The URL of the page that was screenshotted","anyOf":[{"type":"string"},{"type":"null"}]},"previewUrl":{"description":"An URL to an accessible preview of the screenshot","anyOf":[{"type":"string"},{"type":"null"}]},"viewport":{"anyOf":[{"type":"object","properties":{"width":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The width of the viewport"},"height":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The height of the viewport"}},"required":["width","height"],"additionalProperties":false,"description":"The viewport dimensions when the screenshot was taken"},{"type":"null"}]},"colorScheme":{"description":"The color scheme when the screenshot was taken","anyOf":[{"type":"string","enum":["light","dark"]},{"type":"null"}]},"mediaType":{"description":"The media type when the screenshot was taken","anyOf":[{"type":"string","enum":["screen","print"]},{"type":"null"}]},"test":{"anyOf":[{"type":"object","properties":{"id":{"description":"The unique identifier of the test","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string","description":"The title of the test"},"titlePath":{"type":"array","items":{"type":"string"},"description":"The path of titles leading to the test"},"retries":{"description":"The number of retries for the test","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"retry":{"description":"The current retry count","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"repeat":{"description":"The repeat count for the test","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"location":{"description":"The location of the test in the source code","type":"object","properties":{"file":{"type":"string","description":"The located file"},"line":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The line number in the file"},"column":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The column number in the file"}},"required":["file","line","column"],"additionalProperties":false},"annotations":{"description":"Annotations associated to the test","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of annotation"},"description":{"description":"The description of the annotation","type":"string"},"location":{"description":"The location of the annotation in the source code","type":"object","properties":{"file":{"type":"string","description":"The located file"},"line":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The line number in the file"},"column":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The column number in the file"}},"required":["file","line","column"],"additionalProperties":false}},"required":["type"],"additionalProperties":false,"description":"A test annotation"}},"tags":{"description":"Tags associated to the test","type":"array","items":{"type":"string"}}},"required":["title","titlePath"],"additionalProperties":false,"description":"The test that generated the screenshot"},{"type":"null"}]},"browser":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","description":"The name of the browser"},"version":{"type":"string","description":"The version of the browser"}},"required":["name","version"],"additionalProperties":false,"description":"The browser that generated the screenshot"},{"type":"null"}]},"automationLibrary":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation library"},"version":{"type":"string","description":"The version of the automation library"}},"required":["name","version"],"additionalProperties":false,"description":"The automation library that generated the screenshot"},"sdk":{"type":"object","properties":{"name":{"type":"string","description":"The name of the Argos SDK"},"version":{"type":"string","description":"The version of the Argos SDK"}},"required":["name","version"],"additionalProperties":false,"description":"The Argos SDK that generated the screenshot"},"story":{"description":"Storybook story metadata","anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the story"},"tags":{"description":"Tags attached to the story","type":"array","items":{"type":"string"}},"mode":{"description":"Story mode","type":"string"},"play":{"description":"True if the story has a play function","type":"boolean"}},"required":["id"],"additionalProperties":false,"description":"Storybook story metadata"},{"type":"null"}]},"tags":{"description":"Tags associated to the screenshot","type":"array","items":{"type":"string"}}},"required":["automationLibrary","sdk"],"additionalProperties":false,"description":"Metadata about a screenshot"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Width of the screenshot in pixels"},"height":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Height of the screenshot in pixels"},"url":{"type":"string","format":"uri","description":"Public URL of the snapshot"},"contentType":{"type":"string","description":"Content type of the snapshot file"}},"required":["id","name","metadata","width","height","url","contentType"],"additionalProperties":false,"description":"Snapshot associated to a diff"},{"type":"null"}]},"head":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the snapshot"},"name":{"type":"string","description":"Name of the snapshot"},"metadata":{"anyOf":[{"type":"object","properties":{"$schema":{"description":"Ignored. Can be set to get completions, validations and documentation in some editors.","type":"string"},"url":{"description":"The URL of the page that was screenshotted","anyOf":[{"type":"string"},{"type":"null"}]},"previewUrl":{"description":"An URL to an accessible preview of the screenshot","anyOf":[{"type":"string"},{"type":"null"}]},"viewport":{"anyOf":[{"type":"object","properties":{"width":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The width of the viewport"},"height":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The height of the viewport"}},"required":["width","height"],"additionalProperties":false,"description":"The viewport dimensions when the screenshot was taken"},{"type":"null"}]},"colorScheme":{"description":"The color scheme when the screenshot was taken","anyOf":[{"type":"string","enum":["light","dark"]},{"type":"null"}]},"mediaType":{"description":"The media type when the screenshot was taken","anyOf":[{"type":"string","enum":["screen","print"]},{"type":"null"}]},"test":{"anyOf":[{"type":"object","properties":{"id":{"description":"The unique identifier of the test","anyOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string","description":"The title of the test"},"titlePath":{"type":"array","items":{"type":"string"},"description":"The path of titles leading to the test"},"retries":{"description":"The number of retries for the test","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"retry":{"description":"The current retry count","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"repeat":{"description":"The repeat count for the test","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"location":{"description":"The location of the test in the source code","type":"object","properties":{"file":{"type":"string","description":"The located file"},"line":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The line number in the file"},"column":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The column number in the file"}},"required":["file","line","column"],"additionalProperties":false},"annotations":{"description":"Annotations associated to the test","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of annotation"},"description":{"description":"The description of the annotation","type":"string"},"location":{"description":"The location of the annotation in the source code","type":"object","properties":{"file":{"type":"string","description":"The located file"},"line":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The line number in the file"},"column":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The column number in the file"}},"required":["file","line","column"],"additionalProperties":false}},"required":["type"],"additionalProperties":false,"description":"A test annotation"}},"tags":{"description":"Tags associated to the test","type":"array","items":{"type":"string"}}},"required":["title","titlePath"],"additionalProperties":false,"description":"The test that generated the screenshot"},{"type":"null"}]},"browser":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","description":"The name of the browser"},"version":{"type":"string","description":"The version of the browser"}},"required":["name","version"],"additionalProperties":false,"description":"The browser that generated the screenshot"},{"type":"null"}]},"automationLibrary":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation library"},"version":{"type":"string","description":"The version of the automation library"}},"required":["name","version"],"additionalProperties":false,"description":"The automation library that generated the screenshot"},"sdk":{"type":"object","properties":{"name":{"type":"string","description":"The name of the Argos SDK"},"version":{"type":"string","description":"The version of the Argos SDK"}},"required":["name","version"],"additionalProperties":false,"description":"The Argos SDK that generated the screenshot"},"story":{"description":"Storybook story metadata","anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique ID of the story"},"tags":{"description":"Tags attached to the story","type":"array","items":{"type":"string"}},"mode":{"description":"Story mode","type":"string"},"play":{"description":"True if the story has a play function","type":"boolean"}},"required":["id"],"additionalProperties":false,"description":"Storybook story metadata"},{"type":"null"}]},"tags":{"description":"Tags associated to the screenshot","type":"array","items":{"type":"string"}}},"required":["automationLibrary","sdk"],"additionalProperties":false,"description":"Metadata about a screenshot"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Width of the screenshot in pixels"},"height":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Height of the screenshot in pixels"},"url":{"type":"string","format":"uri","description":"Public URL of the snapshot"},"contentType":{"type":"string","description":"Content type of the snapshot file"}},"required":["id","name","metadata","width","height","url","contentType"],"additionalProperties":false,"description":"Snapshot associated to a diff"},{"type":"null"}]},"test":{"anyOf":[{"$ref":"#/components/schemas/Test"},{"type":"null"}]},"change":{"anyOf":[{"$ref":"#/components/schemas/Change"},{"type":"null"}]}},"required":["id","name","status","score","group","parentName","url","base","head","test","change"],"additionalProperties":false,"description":"Snapshot diff"},"Test":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the test"},"name":{"type":"string","description":"Name of the test"},"buildName":{"type":"string","description":"Name of the build the test belongs to"},"metrics":{"$ref":"#/components/schemas/TestMetrics"}},"required":["id","name","buildName","metrics"],"additionalProperties":false,"description":"Test associated to a diff, with flakiness metrics to help decide whether a change is worth reviewing."},"TestMetrics":{"type":"object","properties":{"total":{"type":"number","description":"Number of builds in which this test ran over the metrics period."},"changes":{"type":"number","description":"Number of times the test changed (produced a diff) over the metrics period."},"uniqueChanges":{"type":"number","description":"Number of changes that were seen only once over the metrics period. A high ratio of unique changes is a strong flakiness signal."},"stability":{"type":"number","description":"Ratio of builds without a change, between 0 and 1. `1` means the test never changed."},"consistency":{"type":"number","description":"How consistent the changes are, between 0 and 1. `1` means changes repeat the same way; a low value means changes are erratic."},"flakiness":{"type":"number","description":"Overall flakiness score between 0 and 1, derived from stability and consistency. `0` means stable, `1` means highly flaky."}},"required":["total","changes","uniqueChanges","stability","consistency","flakiness"],"additionalProperties":false,"description":"Flakiness metrics of a test over the requested period."},"Change":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the change (a test + fingerprint pair). Use it with the ignore/unignore endpoints."},"ignored":{"type":"boolean","description":"Whether this change is currently ignored. Ignored changes no longer require review and are automatically approved."},"occurrences":{"type":"number","description":"Number of times this change has been seen over the metrics period. A high count for a recurring change is a strong flakiness signal."}},"required":["id","ignored","occurrences"],"additionalProperties":false,"description":"A test change: a specific visual difference (fingerprint) of a test that can be ignored to silence flaky changes."},"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}/builds/{buildNumber}/diffs":{"get":{"operationId":"listBuildDiffs","summary":"List a build's screenshot diffs","description":"List the screenshot diffs of a build, with pagination. Each diff compares a baseline screenshot to the one captured by the build. Each diff also carries its test's flakiness metrics and, when it is a change, its ignore state and occurrence count — so you can tell whether a change is worth reviewing or is just a flaky one. Use `needsReview` to return only the diffs that require review.","tags":["Builds"],"parameters":[{"in":"path","name":"owner","schema":{"type":"string","minLength":1},"required":true},{"in":"path","name":"project","schema":{"type":"string","minLength":1},"required":true},{"in":"path","name":"buildNumber","schema":{"$ref":"#/components/schemas/BuildNumber"},"required":true,"description":"The build number"},{"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":"needsReview","schema":{"description":"Only return diffs that require review. Matches `changed`, `added`, and `removed`, except `removed` is excluded for subset builds.","type":"string"},"description":"Only return diffs that require review. Matches `changed`, `added`, and `removed`, except `removed` is excluded for subset builds."},{"in":"query","name":"metricsPeriod","schema":{"default":"LAST_7_DAYS","description":"Period over which the test flakiness metrics are computed.","type":"string","enum":["LAST_24_HOURS","LAST_3_DAYS","LAST_7_DAYS","LAST_30_DAYS","LAST_90_DAYS"]},"description":"Period over which the test flakiness metrics are computed."}],"responses":{"200":{"description":"List of screenshot diffs","content":{"application/json":{"schema":{"type":"object","properties":{"pageInfo":{"$ref":"#/components/schemas/PageInfo"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SnapshotDiff"}}},"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"}}}},"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/builds.md?ask=<question>&goal=<endgoal>
```

`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.