Skip to main content

HTTP Headers

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​

Canonical request shape
curl "https://V1Host/V1Instance/api_endpoint_here" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
HeaderValuePurpose
Authorizationscheme-dependent — see belowIdentifies the caller. Required on every request.
Content-Typeapplication/jsonTells the server what media type the request body is in.
Acceptapplication/jsonTells 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 for the full treatment. In brief:

HTTP Basic
# base64 of "username:password"
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="
Access token
-H "Authorization: Bearer <access-token>"
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.

Other Headers Worth Knowing​

HeaderWhen it applies
Accept-Encodinggzip is supported and worth enabling — query responses are frequently large.
Accept-LanguageInfluences localized values. See Localization (loc-2.v1).