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

post

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.

Authorizations

projectToken

AuthorizationstringRequired

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

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

Body

application/json

and

anyOptional

or

Responses

201

Result of build creation

application/json

400

Invalid parameters

application/json

401

Unauthorized

application/json

409

Conflict

application/json

500

Server error

application/json

post/builds

HTTPcURLJavaScriptPython

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

{
  "commit": "text",
  "branch": "text",
  "pwTraceKeys": [
    "text"
  ],
  "name": "text",
  "parallel": true,
  "parallelNonce": "text",
  "prNumber": 1,
  "prHeadCommit": "text",
  "referenceCommit": "text",
  "referenceBranch": "text",
  "parentCommits": [
    "text"
  ],
  "mode": "ci",
  "ciProvider": "text",
  "argosSdk": "text",
  "runId": "text",
  "runAttempt": 1,
  "skipped": true,
  "mergeQueue": true,
  "mergeQueuePrNumbers": [
    1
  ],
  "subset": true,
  "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"
      },
      "url": "https://example.com"
    }
  },
  "screenshots": [
    {
      "key": "text"
    }
  ],
  "pwTraces": [
    {
      "key": "text"
    }
  ]
}

Finalize parallel builds

post

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

Authorizations

projectToken

AuthorizationstringRequired

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

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

Body

application/json

parallelNoncestring · min: 1Required

Responses

200

Result of build finalization

application/json

400

Invalid parameters

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

409

Conflict

application/json

500

Server error

application/json

post/builds/finalize

HTTPcURLJavaScriptPython

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"
        },
        "url": "https://example.com"
      }
    }
  ]
}

Find an eligible baseline from a list of commits

post

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.

Authorizations

projectToken

AuthorizationstringRequired

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

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

Body

application/json

commitsstring[] · min: 1Required

The commits to look for an eligible baseline, ordered from the closest to the furthest ancestor. The first commit with an eligible baseline wins.

namestring · min: 1Optional

The name of the build to find a baseline for.

Default: default

modestring · enumOptional

The mode of the build to find a baseline for.

Default: ciPossible values:

Responses

200

The eligible baseline build, or null when none is found

application/json

400

Invalid parameters

application/json

401

Unauthorized

application/json

500

Server error

application/json

post/baseline

HTTPcURLJavaScriptPython

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"
      },
      "url": "https://example.com"
    }
  }
}

Update a build

put

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

Authorizations

projectToken

AuthorizationstringRequired

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

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

Path parameters

buildIdstringRequired

A unique identifier for the build

Example: 12345

Body

application/json

parallelboolean · nullableOptional

parallelTotalinteger · min: -1 · max: 9007199254740991 · nullableOptional

parallelIndexinteger · min: 1 · max: 9007199254740991 · nullableOptional

finalboolean · nullableOptional

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.

Responses

200

Result of build update

application/json

400

Invalid parameters

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

409

Conflict

application/json

500

Server error

application/json

put/builds/{buildId}

HTTPcURLJavaScriptPython

PUT /v2/builds/{buildId} HTTP/1.1
Host: api.argos-ci.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 948

{
  "screenshots": [
    {
      "key": "text",
      "name": "text",
      "baseName": "text",
      "parentName": "text",
      "metadata": {
        "$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json",
        "url": "text",
        "previewUrl": "text",
        "viewport": {
          "width": 1,
          "height": 1
        },
        "colorScheme": "light",
        "mediaType": "screen",
        "test": {
          "id": "text",
          "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
        },
        "tags": [
          "text"
        ]
      },
      "pwTraceKey": "text",
      "threshold": 1,
      "contentType": "text"
    }
  ],
  "parallel": true,
  "parallelTotal": 1,
  "parallelIndex": 1,
  "final": true,
  "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"
      },
      "url": "https://example.com"
    }
  }
}

List a project's builds

get

List the builds of a project, most recent first. Results are paginated. Use distinctName to return only the latest build per name and commit.

Authorizations

projectTokenpersonalAccessToken

AuthorizationstringRequired

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

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

Path parameters

ownerstring · min: 1Required

projectstring · min: 1Required

Query parameters

perPagestringOptional

Number of items per page (max 100)

pagestringOptional

Page number

headstring · min: 1Optional

headShastringOptional

SHA1 hash

Pattern: ^[0-9a-f]{40}$

distinctNamestringOptional

Only return the latest builds created, unique by name and commit.

Responses

200

List of builds

application/json

400

Invalid parameters

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

500

Server error

application/json

get/projects/{owner}/{project}/builds

HTTPcURLJavaScriptPython

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"
        },
        "url": "https://example.com"
      }
    }
  ]
}

Get a build

get

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

Authorizations

projectTokenpersonalAccessToken

AuthorizationstringRequired

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

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

Path parameters

ownerstring · min: 1Required

projectstring · min: 1Required

buildNumberstringRequired

The build number

Example: 42

Responses

200

Build

application/json

Build

idstringRequired

A unique identifier for the build

Example: 12345

numberanyRequired

The build number

Example: 42

statusany ofRequired

The status of the build

string · enumOptionalPossible values:

or

string · enumOptionalPossible values:

or

string · enumOptionalPossible values:

conclusionstring · enum · nullableRequired

The conclusion of the build

Possible values:

urlstring · uriRequired

The URL of the build

400

Invalid parameters

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

500

Server error

application/json

get/projects/{owner}/{project}/builds/{buildNumber}

HTTPcURLJavaScriptPython

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"
    },
    "url": "https://example.com"
  }
}

List a build's screenshot diffs

get

List the screenshot diffs of a build, with pagination. Each diff compares a baseline screenshot to the one captured by the build. Use onlyChanged to return only the diffs that require review.

Authorizations

projectTokenpersonalAccessToken

AuthorizationstringRequired

Authenticate as a project with a project token.

Send it as a bearer token in the Authorization header:

Authorization: Bearer <project-token>

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

Path parameters

ownerstring · min: 1Required

projectstring · min: 1Required

buildNumberstringRequired

The build number

Example: 42

Query parameters

perPagestringOptional

Number of items per page (max 100)

pagestringOptional

Page number

needsReviewstringOptional

Only return diffs that require review. Matches changed, added, and removed, except removed is excluded for subset builds.

Responses

200

List of screenshot diffs

application/json

400

Invalid parameters

application/json

401

Unauthorized

application/json

404

Not found

application/json

500

Server error

application/json

get/projects/{owner}/{project}/builds/{buildNumber}/diffs

HTTPcURLJavaScriptPython

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": 1,
      "group": "text",
      "parentName": "text",
      "url": "https://example.com",
      "base": {
        "id": "text",
        "name": "text",
        "metadata": {
          "$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json",
          "url": "text",
          "previewUrl": "text",
          "viewport": {
            "width": 1,
            "height": 1
          },
          "colorScheme": "light",
          "mediaType": "screen",
          "test": {
            "id": "text",
            "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
          },
          "tags": [
            "text"
          ]
        },
        "width": 1,
        "height": 1,
        "url": "https://example.com",
        "contentType": "text"
      },
      "head": {
        "id": "text",
        "name": "text",
        "metadata": {
          "$schema": "https://api.argos-ci.com/v2/screenshot-metadata.json",
          "url": "text",
          "previewUrl": "text",
          "viewport": {
            "width": 1,
            "height": 1
          },
          "colorScheme": "light",
          "mediaType": "screen",
          "test": {
            "id": "text",
            "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
          },
          "tags": [
            "text"
          ]
        },
        "width": 1,
        "height": 1,
        "url": "https://example.com",
        "contentType": "text"
      }
    }
  ]
}