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. Some endpoints support `Project-Id: *` to return all project-level records globally. More details here.
`Company-Id`	Not Applicable	Optional	If the user has granted you cross-company access, you need to provide this header with an Agave-provided Company UUID to let us know which company should be used. To get the list of companies, use the /link/companies endpoint. To require cross-company access in Agave Link, see here.
`Include-Source-Data`	Not Applicable	Optional	If set to `true`, Agave API will include the raw data from the Source System. You can also pass in a comma-delimited list of fields to limit what is returned (example: `source_field_1,source_field_2,source_field_3`). Learn More. Default value: `false`.
`Include-Source-Data-Path`	Not Applicable	Optional	If set to `true`, the `source_data` object will include a `path` key which is either the API path, or the raw SQL query executed to fetch the data. Default value: `true`.
`Exclude-Source-Data`	Not Applicable	Optional	You can use this header to specify a list of fields that want Agave to exclude from the Source Data (example: `BankAcct,RoutingId`). Learn More.
`Async-Request`	Not Applicable	Optional	If set to `true`, the request will be processed asynchronously by Agave. You will get an immediate `202 Accepted` response, with a `Agave-Async-Request-Id` header value that can be used to periodically poll Agave for the results. Learn More. 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`.
`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.
`If-None-Match`	Not Applicable	Optional	When downloading files through our Storage Proxy, an `ETag` response header is returned. You can use it as the value of `If-None-Match` request header in subsequent calls to avoid downloading the same file again.

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'.`
`Agave-RateLimit-Total`	The number of requests allowed in a 60-second window. See rate limits for more info.
`Agave-RateLimit-Remaining`	The number of requests remaining in a 60-second window before returning a 429 error. See Rate Limits for more info.
`\{SourceSystem\}-RateLimit-Total`	The total number of requests that can be made to the Source System until rate limits reset, which is typically 60 seconds.
`\{SourceSystem\}-RateLimit-Remaining`	The remaining number of requests that can be made to the Source System until rate limits reset.
`\{SourceSystem\}-RateLimit-ResetsAtTimestamp`	The UNIX timestamp at which point Source System rate limits will reset.
`Agave-Async-Request-Id`	If this is an Async Request, this header will include an Agave-generated UUID that you can use with the /async-requests/{id} endpoint to retrieve the results.
`Agave-Async-Request-State`	The state of an Async Request. Possible values are `pending`, `running`, `executed`, and `failure`.
`Agave-Async-Request-Started-At`	The timestamp showing when an Async Request was started.
`Agave-Async-Request-Finished-At`	The timestamp showing when an Async Request finished executing.
`Agave-Async-Request-Expires-At`	The timestamp showing when an Async Request will expire. You will not be able to retrieve the results of that Request after this time.
`ETag`	This header is only set when downloading files through our Storage Proxy. You can use it as the value of `If-None-Match` request header in subsequent calls to avoid downloading the same file again.

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
Agave-RateLimit-Total: 600
Agave-RateLimit-Remaining: 598
Procore-RateLimit-Total: 3600
Procore-RateLimit-Remaining: 3561
Procore-RateLimit-ResetsAtTimestamp: 1681282869
Access-Control-Allow-Origin: *
X-Content-Type-Options: nosniff

Headers

Request Headers​

Response Headers​

Request Headers

Response Headers