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. |
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(...);
Source-System Specific Headers
Some Source Systems support additional headers to configure the request.
| Source System | Header | Description |
|---|---|---|
| Acumatica | Acumatica-Expand | A comma-delimited list of additional $expand properties to be passed to Acumatica.Examples: Acumatica-Expand: Employees or Acumatica-Expand: Employees,Equipments,UnionLocals. |
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