Headers

Agave API supports HTTP headers in both requests and responses.

Request Headers

Agave API uses HTTP request headers to authorize and configure API requests:

Header	"Link Token" Requests	All Other Requests	Description
API-Version	Required	Required	The API Version you are using. The current version is "2021-11-21".
Client-Id	Required	Required	Your Client Identifier, which is always a 36-character UUID. Email api-support@agaveapi.com if you need one.
Client-Secret	Required	Required	Your Client Secret, which is a 40-character string. Email api-support@agaveapi.com if you need one.
Account-Token	Not Applicable	Required	The unique Account Token associated with your User.
Project-Id	Not Applicable	Optional	For Construction Project Management and Field Services source systems, you need to provide this header with an Agave-provided Project UUID to let us know which project should be used.
Session	Not Applicable	Optional	Primarily for front-end single-page applications, the Session header can be sent instead of Client-Id, Client-Secret, and Account-Token. Learn more.
Include-Source-Data	Not Applicable	Optional	If set to true, Agave API will include the raw data from the Source System. Learn More. Default value: false.
Ignore-Prohibited-Fields	Not Applicable	Optional	If set to true, Agave API will not return an error when you pass a prohibited field during CREATE or UPDATE operations (for example, passing a field that the source system does not support). Default value: false.

Example "Link Token" request:

curl --head https://api.agaveapi.com/link/create \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: 53b2b9cb-9828-5197-8fe8-ed91f623b135' \
     --header 'Client-Secret: FwRIpg6ezHuGBOMFxT30suIbkkHtAq67BQWpLTeN'

Example non-"Link Token" request:

curl --head https://api.agaveapi.com/projects \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: 53b2b9cb-9828-5197-8fe8-ed91f623b135' \
     --header 'Client-Secret: FwRIpg6ezHuGBOMFxT30suIbkkHtAq67BQWpLTeN' \
     --header 'Account-Token: 2FwppFrITHMpt3F7vfNQmJw7xYymcQ3tdXw6Uk0n'

Example request with a Link Session:

const axios = require('axios');
axios.get(
    'https://api.agaveapi.com/projects',
    {
      headers: {
        'API-Version': '2021-11-21',
        'Session': '22u2760J7I7eIQiCFcnAMIRyJi3edRKaHs9yei2R'
      }
    }
).then(...);

Response Headers

Agave API will return the following response headers for all API requests:

Header	Description
Agave-Request-Id	Each response has a unique request identifier. If you need our help troubleshooting a specific request, providing us with the request identifier will ensure the fastest possible resolution.
Agave-Data-Retrieved-At	The date/time in ISO-8601 format that the data was retrieved from the Source System.
Agave-Warnings	Sometimes, our application encounters non-critical issues with processing your request. We will indicate any such warnings as a header to help you with debugging. Example: 'Content-Type' header changed from 'application/x-www-form-urlencoded' to 'application/json'.
X-RateLimit-Limit	The number of requests allowed in a 60-second window. See rate limits for more info.
X-RateLimit-Remaining	The number of requests remaining in a 60-second window before returning a 429 error. See Rate Limits for more info.

Example response headers for the request in the above section:

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Mon, 03 Jan 2022 21:47:18 GMT
Agave-Request-Id: 7ab5f180b096390c1e9b253f4ff7a8c5
Agave-Data-Retrieved-At: Mon Jan 03 2022 21:47:18 GMT+0000
X-RateLimit-Limit: 1000
X-RateLimit-Limit-Remaining: 999
Access-Control-Allow-Origin: *
X-Content-Type-Options: nosniff