api-reference

description	Learn how to authenticate and make requests to the Argos REST API to create builds, fetch results, and automate your visual testing workflow.
icon	book-open

Introduction

The Argos API is organized around REST. It has predictable, resource-oriented URLs, accepts and returns JSON-encoded payloads, and uses standard HTTP response codes, authentication, and verbs.

Most of the time you'll interact with Argos through one of the SDKs or the CLI, which call this API for you. You can also call it directly to build your own integrations.

Base URL

All requests are made to the following base URL:

https://api.argos-ci.com/v2

{% hint style="info" %} The API is served over HTTPS only. Requests made over plain HTTP will fail. {% endhint %}

Authentication

The Argos API authenticates requests with a bearer token. Add an Authorization header to every request, using your token as the credential:

Authorization: Bearer <your-token>

In most cases this is a project token, which you can find in your project settings on argos-ci.com. A project token grants access to a single project, so it's safe to use in your CI environment.

{% hint style="warning" %} Your token carries the ability to create and update builds in your project. Keep it secret: store it as a CI secret or environment variable, and never commit it to version control or expose it in client-side code. {% endhint %}

Some endpoints act on behalf of a user rather than a project — for example, submitting a review, posting a comment, or resolving a thread. These require a personal access token, which is attributed to your Argos user and checked against your project permissions. You can create one in your personal settings on argos-ci.com.

Requests without a valid token return a 401 Unauthorized response.

Making a request

Here's a complete example that fetches the project associated with your token:

{% tabs %} {% tab title="cURL" %}

curl https://api.argos-ci.com/v2/project \
  -H "Authorization: Bearer $ARGOS_TOKEN"

{% endtab %}

{% tab title="JavaScript" %}

const response = await fetch("https://api.argos-ci.com/v2/project", {
  headers: {
    Authorization: `Bearer ${process.env.ARGOS_TOKEN}`,
  },
});

const project = await response.json();

{% endtab %} {% endtabs %}

Response codes

Argos uses conventional HTTP response codes to indicate the success or failure of a request. In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that resulted from the information provided (for example, a missing token, an invalid parameter, or a resource that doesn't exist).
• Codes in the 5xx range indicate an error on Argos's side.

Status	Meaning
200 OK	The request succeeded.
201 Created	The resource was created (for example, a new build).
400 Bad Request	The request was malformed or a parameter was invalid.
401 Unauthorized	The token is missing or invalid.
403 Forbidden	The token is valid but doesn't have access to this resource.
404 Not Found	The requested resource doesn't exist.
409 Conflict	The request conflicts with the current state of the resource.
429 Too Many Requests	You've hit the rate limit.
500 Internal Server Error	Something went wrong on Argos's side.
503 Service Unavailable	Argos is temporarily unavailable.

See Errors for the shape of error responses and how to handle them.

OpenAPI specification

The full API is described by an OpenAPI 3.1 specification. You can download it to generate clients or explore the API in your favorite tooling:

https://api.argos-ci.com/v2/openapi.yaml

Next steps

Topic	Link
Pagination — page through large lists of results.	Pagination
Rate limits — understand request limits and headers.	Rate limits
Errors — handle error responses gracefully.	Errors