Learn how to authenticate and make requests to the Argos REST API to create builds, fetch results, and automate your visual testing workflow.
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.
All requests are made to the following base URL:
https://api.argos-ci.com/v2The API is served over HTTPS only. Requests made over plain HTTP will fail.
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.
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.
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.
Here's a complete example that fetches the project associated with your token:
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.
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.
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:
Last updated
Was this helpful?
Was this helpful?
curl https://api.argos-ci.com/v2/project \
-H "Authorization: Bearer $ARGOS_TOKEN"const response = await fetch("https://api.argos-ci.com/v2/project", {
headers: {
Authorization: `Bearer ${process.env.ARGOS_TOKEN}`,
},
});
const project = await response.json();https://api.argos-ci.com/v2/openapi.yaml