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 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.
Authenticate as a project with a project token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <project-token>
You can find your project token in your Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.
Result of build creation
Invalid parameters
Unauthorized
Conflict
Server error
POST /v2/builds HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 379
{
"commit": "text",
"branch": "text",
"pwTraceKeys": [
"text"
],
"name": null,
"parallel": null,
"parallelNonce": null,
"prNumber": 1,
"prHeadCommit": "text",
"referenceCommit": "text",
"referenceBranch": null,
"parentCommits": [
"text"
],
"mode": "ci",
"ciProvider": null,
"argosSdk": null,
"runId": null,
"runAttempt": 1,
"skipped": null,
"mergeQueue": null,
"mergeQueuePrNumbers": [
1
],
"subset": null,
"screenshots": null
}{
"build": {
"id": "12345",
"number": 42,
"head": {
"sha": "text",
"branch": "text"
},
"base": {
"sha": "text",
"branch": "text"
},
"status": "accepted",
"conclusion": "no-changes",
"stats": {
"added": 1,
"removed": 1,
"unchanged": 1,
"changed": 1,
"ignored": 1,
"failure": 1,
"retryFailure": 1,
"total": 1
},
"metadata": {
"testReport": {
"status": "passed",
"stats": {
"startTime": "text",
"duration": 1
}
}
},
"url": "https://example.com",
"notification": {
"description": "text",
"context": "text",
"github": {
"state": "pending"
},
"gitlab": {
"state": "pending"
},
"origin": {
"status": "queued",
"conclusion": "success"
},
"url": "https://example.com"
}
},
"screenshots": [
{
"key": "text"
}
],
"pwTraces": [
{
"key": "text"
}
]
}Mark every parallel shard sharing the given parallelNonce as complete. Once finalized, Argos compares the aggregated screenshots and starts processing the build.
Authenticate as a project with a project token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <project-token>
You can find your project token in your Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.
Result of build finalization
Invalid parameters
Unauthorized
Forbidden
Not found
Conflict
Server error
POST /v2/builds/finalize HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 24
{
"parallelNonce": "text"
}{
"builds": [
{
"id": "12345",
"number": 42,
"head": {
"sha": "text",
"branch": "text"
},
"base": {
"sha": "text",
"branch": "text"
},
"status": "accepted",
"conclusion": "no-changes",
"stats": {
"added": 1,
"removed": 1,
"unchanged": 1,
"changed": 1,
"ignored": 1,
"failure": 1,
"retryFailure": 1,
"total": 1
},
"metadata": {
"testReport": {
"status": "passed",
"stats": {
"startTime": "text",
"duration": 1
}
}
},
"url": "https://example.com",
"notification": {
"description": "text",
"context": "text",
"github": {
"state": "pending"
},
"gitlab": {
"state": "pending"
},
"origin": {
"status": "queued",
"conclusion": "success"
},
"url": "https://example.com"
}
}
]
}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.
Authenticate as a project with a project token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <project-token>
You can find your project token in your Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.
The commits to look for an eligible baseline, ordered from the closest to the furthest ancestor. The first commit with an eligible baseline wins.
The name of the build to find a baseline for.
defaultThe mode of the build to find a baseline for.
ciPossible values: The eligible baseline build, or null when none is found
Invalid parameters
Unauthorized
Server error
POST /v2/baseline HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 49
{
"commits": [
"text"
],
"name": "default",
"mode": "ci"
}{
"baseline": {
"id": "12345",
"number": 42,
"head": {
"sha": "text",
"branch": "text"
},
"base": {
"sha": "text",
"branch": "text"
},
"status": "accepted",
"conclusion": "no-changes",
"stats": {
"added": 1,
"removed": 1,
"unchanged": 1,
"changed": 1,
"ignored": 1,
"failure": 1,
"retryFailure": 1,
"total": 1
},
"metadata": {
"testReport": {
"status": "passed",
"stats": {
"startTime": "text",
"duration": 1
}
}
},
"url": "https://example.com",
"notification": {
"description": "text",
"context": "text",
"github": {
"state": "pending"
},
"gitlab": {
"state": "pending"
},
"origin": {
"status": "queued",
"conclusion": "success"
},
"url": "https://example.com"
}
}
}Add screenshots to an existing build and update its metadata. Used to push the screenshots of a parallel shard, identified by parallelIndex and parallelTotal.
Authenticate as a project with a project token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <project-token>
You can find your project token in your Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.
A unique identifier for the build
12345Only 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.
Result of build update
Invalid parameters
Unauthorized
Forbidden
Not found
Conflict
Server error
PUT /v2/builds/{buildId} HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 966
{
"screenshots": [
{
"key": "text",
"name": "text",
"baseName": "home.png",
"parentName": null,
"metadata": {
"$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json",
"url": null,
"previewUrl": null,
"viewport": {
"width": 1,
"height": 1
},
"colorScheme": "light",
"mediaType": "screen",
"test": {
"id": null,
"title": "text",
"titlePath": [
"text"
],
"retries": 1,
"retry": 1,
"repeat": 1,
"location": {
"file": "text",
"line": 1,
"column": 1
},
"annotations": [
{
"type": "text",
"description": "text",
"location": {
"file": "text",
"line": 1,
"column": 1
}
}
],
"tags": [
"text"
]
},
"browser": {
"name": "text",
"version": "text"
},
"automationLibrary": {
"name": "text",
"version": "text"
},
"sdk": {
"name": "text",
"version": "text"
},
"story": {
"id": "text",
"tags": [
"text"
],
"mode": "text",
"play": true
},
"capture": {
"index": 1
},
"tags": [
"text"
]
},
"pwTraceKey": "text",
"threshold": 1,
"contentType": "text"
}
],
"parallel": null,
"parallelTotal": 1,
"parallelIndex": 1,
"final": null,
"metadata": {
"testReport": {
"status": "passed",
"stats": {
"startTime": "text",
"duration": 1
}
}
}
}{
"build": {
"id": "12345",
"number": 42,
"head": {
"sha": "text",
"branch": "text"
},
"base": {
"sha": "text",
"branch": "text"
},
"status": "accepted",
"conclusion": "no-changes",
"stats": {
"added": 1,
"removed": 1,
"unchanged": 1,
"changed": 1,
"ignored": 1,
"failure": 1,
"retryFailure": 1,
"total": 1
},
"metadata": {
"testReport": {
"status": "passed",
"stats": {
"startTime": "text",
"duration": 1
}
}
},
"url": "https://example.com",
"notification": {
"description": "text",
"context": "text",
"github": {
"state": "pending"
},
"gitlab": {
"state": "pending"
},
"origin": {
"status": "queued",
"conclusion": "success"
},
"url": "https://example.com"
}
}
}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.
Authenticate as a project with a project token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <project-token>
You can find your project token in your Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.
Number of items per page (max 100)
Page number
SHA1 hash
^[0-9a-f]{40}$Search builds by name, branch (substring) or commit (prefix).
Only return the latest builds created, unique by name and commit.
List of builds
Invalid parameters
Unauthorized
Forbidden
Not found
Server error
GET /v2/projects/{owner}/{project}/builds HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"pageInfo": {
"total": 1,
"page": 1,
"perPage": 1
},
"results": [
{
"id": "12345",
"number": 42,
"head": {
"sha": "text",
"branch": "text"
},
"base": {
"sha": "text",
"branch": "text"
},
"status": "accepted",
"conclusion": "no-changes",
"stats": {
"added": 1,
"removed": 1,
"unchanged": 1,
"changed": 1,
"ignored": 1,
"failure": 1,
"retryFailure": 1,
"total": 1
},
"metadata": {
"testReport": {
"status": "passed",
"stats": {
"startTime": "text",
"duration": 1
}
}
},
"url": "https://example.com",
"notification": {
"description": "text",
"context": "text",
"github": {
"state": "pending"
},
"gitlab": {
"state": "pending"
},
"origin": {
"status": "queued",
"conclusion": "success"
},
"url": "https://example.com"
}
}
]
}Retrieve a single build by its number within a project, including its status and metadata.
Authenticate as a project with a project token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <project-token>
You can find your project token in your Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.
The build number
42Build
Build
A unique identifier for the build
12345The build number
42The status of the build
The conclusion of the build
The URL of the build
Invalid parameters
Unauthorized
Forbidden
Not found
Server error
GET /v2/projects/{owner}/{project}/builds/{buildNumber} HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "12345",
"number": 42,
"head": {
"sha": "text",
"branch": "text"
},
"base": {
"sha": "text",
"branch": "text"
},
"status": "accepted",
"conclusion": "no-changes",
"stats": {
"added": 1,
"removed": 1,
"unchanged": 1,
"changed": 1,
"ignored": 1,
"failure": 1,
"retryFailure": 1,
"total": 1
},
"metadata": {
"testReport": {
"status": "passed",
"stats": {
"startTime": "text",
"duration": 1
}
}
},
"url": "https://example.com",
"notification": {
"description": "text",
"context": "text",
"github": {
"state": "pending"
},
"gitlab": {
"state": "pending"
},
"origin": {
"status": "queued",
"conclusion": "success"
},
"url": "https://example.com"
}
}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.
Authenticate as a project with a project token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <project-token>
You can find your project token in your Argos project settings. Project tokens are used by CI and the SDK to create builds and deployments.
The build number
42Number of items per page (max 100)
Page number
Only return diffs that require review. Matches changed, added, and removed, except removed is excluded for subset builds.
Period over which the test flakiness metrics are computed.
LAST_7_DAYSPossible values: List of screenshot diffs
Invalid parameters
Unauthorized
Not found
Server error
GET /v2/projects/{owner}/{project}/builds/{buildNumber}/diffs HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"pageInfo": {
"total": 1,
"page": 1,
"perPage": 1
},
"results": [
{
"id": "text",
"name": "text",
"status": "pending",
"score": null,
"group": null,
"parentName": null,
"url": "https://example.com",
"base": {
"id": "text",
"name": "text",
"metadata": {
"$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json",
"url": null,
"previewUrl": null,
"viewport": {
"width": 1,
"height": 1
},
"colorScheme": "light",
"mediaType": "screen",
"test": {
"id": null,
"title": "text",
"titlePath": [
"text"
],
"retries": 1,
"retry": 1,
"repeat": 1,
"location": {
"file": "text",
"line": 1,
"column": 1
},
"annotations": [
{
"type": "text",
"description": "text",
"location": {
"file": "text",
"line": 1,
"column": 1
}
}
],
"tags": [
"text"
]
},
"browser": {
"name": "text",
"version": "text"
},
"automationLibrary": {
"name": "text",
"version": "text"
},
"sdk": {
"name": "text",
"version": "text"
},
"story": {
"id": "text",
"tags": [
"text"
],
"mode": "text",
"play": true
},
"capture": {
"index": 1
},
"tags": [
"text"
]
},
"width": null,
"height": null,
"url": "https://example.com",
"contentType": "text"
},
"head": {
"id": "text",
"name": "text",
"metadata": {
"$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json",
"url": null,
"previewUrl": null,
"viewport": {
"width": 1,
"height": 1
},
"colorScheme": "light",
"mediaType": "screen",
"test": {
"id": null,
"title": "text",
"titlePath": [
"text"
],
"retries": 1,
"retry": 1,
"repeat": 1,
"location": {
"file": "text",
"line": 1,
"column": 1
},
"annotations": [
{
"type": "text",
"description": "text",
"location": {
"file": "text",
"line": 1,
"column": 1
}
}
],
"tags": [
"text"
]
},
"browser": {
"name": "text",
"version": "text"
},
"automationLibrary": {
"name": "text",
"version": "text"
},
"sdk": {
"name": "text",
"version": "text"
},
"story": {
"id": "text",
"tags": [
"text"
],
"mode": "text",
"play": true
},
"capture": {
"index": 1
},
"tags": [
"text"
]
},
"width": null,
"height": null,
"url": "https://example.com",
"contentType": "text"
},
"test": {
"id": "text",
"name": "text",
"buildName": "text",
"metrics": {
"total": 1,
"changes": 1,
"uniqueChanges": 1,
"stability": 1,
"consistency": 1,
"flakiness": 1
}
},
"change": {
"id": "text",
"ignored": true,
"occurrences": 1
}
}
]
}Start receiving notifications about a build — new comments, reviews, and status changes. Clears a previous explicit unsubscription.
Authenticate as a user with a personal access token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <personal-access-token>
Personal access tokens act on behalf of the user that created them and are required by endpoints that perform user actions, such as reviewing builds and posting comments.
The build number
42Subscribed
A notification subscription.
Whether the authenticated user now receives notifications for this resource.
Invalid parameters
Unauthorized
Forbidden
Not found
Server error
POST /v2/projects/{owner}/{project}/builds/{buildNumber}/subscription HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"subscribed": true
}Stop receiving notifications about a build. Recorded as an intentional unsubscription, so Argos will not auto-subscribe you to it again.
Authenticate as a user with a personal access token.
Send it as a bearer token in the Authorization header:
Authorization: Bearer <personal-access-token>
Personal access tokens act on behalf of the user that created them and are required by endpoints that perform user actions, such as reviewing builds and posting comments.
The build number
42Unsubscribed
A notification subscription.
Whether the authenticated user now receives notifications for this resource.
Invalid parameters
Unauthorized
Forbidden
Not found
Server error
DELETE /v2/projects/{owner}/{project}/builds/{buildNumber}/subscription HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"subscribed": true
}Last updated
Was this helpful?