---
title: "Atlas API Documentation"
---

# Atlas API Documentation

Atlas provides an API for a **subset of features** available. For questions
or requests for new API features please email [support@hashicorp.com](mailto:support@hashicorp.com).

## Available Endpoints

These are the currently supported API endpoints for each product:

### Vagrant

- [Boxes](/help/api/vagrant/boxes)
- [Box Versions](/help/api/vagrant/box-versions)
- [Box Providers](/help/api/vagrant/box-providers)

### Packer

- [Build configurations](/help/api/packer/build-configurations)
- [Build configuration versions](/help/api/packer/build-configuration-versions)
- [Builds](/help/api/packer/builds)

### Terraform

- [Environments](/help/api/terraform/environments)
- [Runs](/help/api/terraform/runs)
- [States](/help/api/terraform/states)

## Authentication

All requests must be authenticated with an `X-Atlas-Token` HTTP header. This 
token can be generated or revoked on the [account tokens page](/settings/tokens). 
Your token will have access to all resources your account has access to.

For organization level resources, we recommend creating a separate user account
that can be added to the organization with the specific privilege level
required.

## Response Codes

Standard HTTP response codes are returned. `404 Not Found`
codes are returned for all resources that a user does not have access to,
as well as for resources that don't exist. This is done to avoid a
potential attacker discovering the existence of a resource.

## Errors

Errors are returned in JSON format:

    {
      "errors": {
        "name": [
          "has already been taken"
        ]
      }
    }

## Versioning

The API currently resides under the `/v1` prefix. Future APIs
will increment this version leaving the `/v1` API intact, though
in the future certain features may be deprecated. In that case,
ample notice to migrate to the new API will be provided.

## Content Type

The API accepts namespaced attributes in either
JSON or `application/x-www-form-urlencoded`. We recommend
using JSON, but for simplicity form style requests are supported.

Below is an equivalent example with both styles using `curl`.

### JSON Request Example

    $ cat variables.json
    {
      "variables": {
          "desired_capacity": "15",
          "foo": "bar"
      }
    }
    $ curl %{ATLAS_URL}/api/v1/environments/%{DEFAULT_USERNAME}/test/variables \
        -X PUT \
        -H 'Content-Type: application/json' \
        -d @variables.json \
        -H "X-Atlas-Token: $ATLAS_TOKEN"

### Form URL Encoded Example

    $ curl %{ATLAS_URL}/api/v1/environments/%{DEFAULT_USERNAME}/test/variables \
        -X PUT \
        -d variables[foo]='bar' \
        -d variables[desired_capacity]='15' \
        -H "X-Atlas-Token: $ATLAS_TOKEN"