General API Parameters – CDD Support

API GET requests utilize query parameters using standard HTTP syntax. Parameters may be specified in any order. Lists are separated by commas.

GET /api/v1/vaults/23/protocols?projects=24888,45466&page_size=500&offset=2000

When a request body will be used, you must change to a POST request made to <original url>/query. This can happen if the parameters become too large for query parameters or if json is preferred for specifying the parameters. GET requests will no longer be accepted with a body.

POST /api/v1/vaults/23/protocols/query
with body:
{
  "projects": [24888,45466],
  "page_size": 500,
  "offset": 2000
}

This documentation section describes parameters that are valid for all calls; individual calls define additional ones.

General Parameters (all optional).

These two parameters define the scope of the query. The default is to query all accessible projects and none of the public datasets.

projects	comma-separated list of project ids
data_sets	comma-separated list of public dataset ids

General Parameters for set-retrieval calls (all optional):

async	if set, do an asynchronous export (see below) Note: This is strongly recommended any time you want to download more than page_size results
offset	The index of the first object actually returned. Defaults to 0.
page_size	The maximum number of objects to return in this call. Default is 50, maximum is 1000.

Asynchronous responses

When retrieving large data sets (i.e. larger than the maximum page size), we strongly recommend doing an asynchronous request. This uses the existing export mechanism which allows you to download all requested data in one go.

Example:

curl -H X-CDD-Token:$TOKEN 'https://app.collaborativedrug.com/api/v1/vaults/23/protocols?async=true'

Result:

{"id":18765,"status":"new"}

Data is then retrieved using the Async Export.

Date formats

The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20".

You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.