---
id: http-headers
slug: /apis/conventions/http-headers
title: 'HTTP Headers'
description: 'The Authorization, Content-Type and Accept headers required by every Agility API request, and what each one controls.'
sidebar_label: 'HTTP Headers'
sidebar_position: 3
tags: ['api', 'conventions', 'headers', 'json']
---

The Agility APIs can speak both XML and JSON. This documentation shows JSON exclusively, which
means every request needs to say so explicitly.

## The Three Headers You Always Send

```bash title="Canonical request shape"
curl "https://V1Host/V1Instance/api_endpoint_here" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
```

| Header          | Value                              | Purpose                                                                       |
| --------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
| `Authorization` | scheme-dependent — see below       | Identifies the caller. Required on every request.                              |
| `Content-Type`  | `application/json`                 | Tells the server what media type the **request body** is in.                   |
| `Accept`        | `application/json`                 | Tells the server what media type to **respond** with.                          |

`Content-Type` only matters when you are sending a body, so it is strictly required on `POST`
requests. Sending it on a `GET` is harmless and keeps client code uniform.

:::warning Omitting `Accept` gets you XML
Several endpoints default to XML when no `Accept` header is supplied. If you are parsing a
response and finding angle brackets where you expected braces, check that `Accept:
application/json` is actually reaching the server.
:::

:::warning `Content-Type` must be exact
A misspelled or unrecognized value is rejected outright rather than defaulted. Send
`application/json` exactly.
:::

## The `Authorization` Header

The value depends on the authentication scheme you are using. See
[Authentication](/getting-started/authentication) for the full treatment. In brief:

```bash title="HTTP Basic"
# base64 of "username:password"
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="
```

```bash title="Access token"
-H "Authorization: Bearer <access-token>"
```

:::note Older on-premises instances may expect the bare token
Send `Authorization: Bearer <access-token>`. If an older on-premises instance returns a `401`,
try the header with no scheme prefix (`Authorization: <access-token>`) before assuming the
token itself is invalid. See [Authentication](/getting-started/authentication).
:::

## Other Headers Worth Knowing

| Header             | When it applies                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `Accept-Encoding`  | `gzip` is supported and worth enabling — query responses are frequently large.                 |
| `Accept-Language`  | Influences localized values. See [Localization (loc-2.v1)](/apis/loc-2-v1).                    |

## Related Topics

- [Base URL](/apis/conventions/base-url) — what to prepend to the endpoint path
- [Errors](/apis/conventions/errors) — what comes back when a header is wrong
- [Authentication](/getting-started/authentication)