Aphex Data API V1

Aphex Product Team Updated by Aphex Product Team

This is the V1 Aphex Data API. Looking for the latest version for your setup? Find the info here.

Overview

Teams using Aphex generate vast amounts of data that would normally get wiped off whiteboards or stored in spreadsheets, never seeing the light of day. The Aphex Data API is designed to help you maximise the value of your data by providing access to the true story of what did, and didn't happen on site.

The Aphex Data API is available on the Aphex Enterprise plan

Structure

The API is designed to be called daily. Calling will provide you a list of task events, ordered chronologically, that you can use to reconstruct the data held in Aphex.

Events are generated by users creating, updating and deleting tasks as well as attaching day level delay and resource allocation.

The events are structured so that you can apply them directly to your copy of the tasks, giving you an up-to-date view on what did and didn't happen across all of your projects.

Calling the API

Calling the API is as simple as making a HTTP GET request to our endpoint https://europe-west2-aphex-prod.cloudfunctions.net/apiTaskEvents

To fetch the events since you last called we support the following query parameter:

  • startAfter : The most recent eventId from the events you've received.
    • For subsequent calls, this value can also be found on the nextStartAfter property at the root of the previous response
    • Calls that omit this parameter will return from the Organisation's first event

Along with the call you must include a custom header, x-api-key, with your organisation API key which was provided to you as part of your enterprise onboarding.

An example:

curl -X GET -H 'x-api-key: 6fa9a827da2ca37ae4057e4ae861c6b3' https://europe-west2-aphex-prod.cloudfunctions.net/apiTaskEvents?startAfter=57e4ae861c6b3

Make sure you use HTTPS and not HTTP - our API rejects requests made over HTTP, since this sends your API Key over the internet in plain text.

API Response

The response from the API is a chronological list of events.

There are 3 event types:

  1. TaskCreated : Triggered when a user creates a task. Contains the created task.
  2. TaskUpdated : Triggered when a user updates a task, attaches a delay or updates the resource allocation. Contains the full task.
  3. TaskDeleted : Triggered when a user deletes a task. Contains the id of the deleted task.

Task Created

Any task created will return an event payload similar to below.

{
"data": [
{
"task": {
"name": "New Task",
"ownerEmail": "e.williams@aphex.co",
"ownerName": "Elliot Williams",
"delays": [
{
name: "Awaiting Access",
category: "Scope Change",
date: 1614902400000,
},
{
name: "Awaiting Access",
category: "Scope Change",
date: 1614934200000,
}
],
"externalId": "",
"successors": [fasdwr4gen2nbReyLP2N],
"parentId": "",
"id": "6LFkmZqBmdA4oByyLP2N",
"projectName": "Aphex Fire",
"start": 1614211200000,
"location": "",
"materialResources": {},
"calendar": "Five Day",
"labourResources": {
"Carpenters": 4,
},
"duration": 1,
"contractor": "",
"plantResources": {
"100T Excavator": 2,
},
"projectId": "U2qmd9CVWG0k5EvFxlp9",
"end": 1614297600000,
"wbsPath": "",
"shift": "day"
},
"apiVersion": "v1",
"type": "TaskCreated",
"createdAt": 1614587767389,
"eventId": "FO8097npw2KzZaFoya1O"
}, // ...
],
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",
}

Task Updated

Any task updated will return an event payload similar to below.

{
"data": [
{
"task": {
"name": "New Task",
"ownerEmail": "e.williams@aphex.co",
"ownerName": "Elliot Williams",
"delays": [
{
name: "Awaiting Access",
category: "Scope Change",
date: 1614902400000,
},
{
name: "Awaiting Access",
category: "Scope Change",
date: 1614934200000,
}
],
"externalId": "",
"successors": [fasdwr4gen2nbReyLP2N],
"parentId": "",
"id": "6LFkmZqBmdA4oByyLP2N",
"projectName": "Aphex Fire",
"start": 1614211200000,
"location": "",
"materialResources": {},
"calendar": "Five Day",
"labourResources": {
"Carpenters": 4,
},
"duration": 1,
"contractor": "",
"plantResources": {
"100T Excavator": 2,
},
"projectId": "U2qmd9CVWG0k5EvFxlp9",
"end": 1614297600000,
"wbsPath": "",
"shift": "day"
},
"apiVersion": "v1",
"type": "TaskCreated",
"createdAt": 1614587767389,
"eventId": "FO8097npw2KzZaFoya1O"
}, // ...
],
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",
}

Task Deleted

Any task deleted will return an event payload similar to below.

{
"data": [
{
"task": { "id": "8xH9q2IptPRYnYDMjc3J" },
"apiVersion": "v1",
"type": "TaskDeleted",
"createdAt": 1614587776549,
"eventId": "HLoT3X3nyCAbGFDdcXdQ"
},
],
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",
}

API Limits

We place limits on our API to ensure its availability and responsiveness. The limits are;

  • Responses have a page limit of 4000 events
  • Organisations have a daily limit of 20,000 task events per day

If you find this limit restrictive please contact us at hello@aphex.co and we can adjust your limit to something more suitable.

HTTP Response Codes

  • 200 OK - your data will be in the body of the response
  • 204 No Data - your request returned no data
  • 400 Bad Request - double check your query parameters
  • 401 Unauthorized - double check your API key is included in the x-api-key header
  • 403 Forbidden - ensure you are making a GET request
  • 503 Service Unavailable - Likely you've breached the daily organisation limit. Don't worry you can call tomorrow passing the most recent startAfter you've received to date.

Reach out to hello@aphex.co if you need any assistance or have other ways you would like to access your data.

How did we do?

Aphex Data API V2

Contact