Retrieving Records

When only one ID is specified, the response is { data: {object} }. When multiple IDs are specified, the response is { data: [{object1}, {object2}, … {objectn}] }.

You can query a maximum of 10 IDs at a time. Property keys and what they represent are listed in the API Property Reference in your Celoxis account.

To fetch a task with ID 123:

curl -g -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: bearer YourTokenHere' \
  'https://app.celoxis.com/psa/api/v2/tasks/123'

To fetch tasks with IDs 123, 456 and 789:

curl -g -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: bearer YourTokenHere' \
  'https://app.celoxis.com/psa/api/v2/tasks/123,456,789'

Fetching tasks including baseline and earned-value fields in a list query:

curl -g -X GET \
  -H 'Authorization: bearer YourTokenHere' \
  -G --data-urlencode 'fields=["id","name","baselineStart","cpi","spi"]' \
  'https://app.celoxis.com/psa/api/v2/tasks'

List queries work like reports in Celoxis: you can filter, sort and page the results.

The response is a JSON object in the following format: { data: [{object1}, {object2}, … {objectN}], totalRecords: M, nextPage: Z } where totalRecords is the total number of records returned by the query and nextPage is the number of the next page of records if there is more data to be fetched.

Pass a JSON object as the filter query parameter on the API request. Each key is a property and each value is the filter for that property. This filter fetches tasks:

{
  "name": "^5",
  "custom_city": [
    "Chicago",
    "New York"
  ],
  "project.deadline": "Next Month",
  "project.custom_bid": "Won"
}

The above filter will fetch tasks whose 1) name starts with 5 2) custom attribute City (formula key city) is one of Chicago or New York 3) project's deadline is next month and 4) project's custom field (formula key bid) has the value Won. Property keys are listed in the API Property Reference in your Celoxis account.

To sort the results, pass sort as a query parameter on the API request. Use a comma-separated list of field keys. Append /desc to a key to sort it in descending order.

For example, /api/v2/tasks?sort=project.name,plannedStart/desc sorts tasks by project name, then by planned start in descending order. Sortable fields are marked in the API Property Reference in your Celoxis account.

A list request returns at most 250 records. To fetch a later page, pass page on the API request, for example /api/v2/tasks?page=2.

By default, most columns are returned. Baseline and earned-value fields (such as baselineStart, baselineFinish, cpi, spi and related metrics) are excluded from list responses unless you request them with fields. To return only the columns you need, pass fields as a query parameter — a JSON array of field keys. This works for list queries and for fetching by ID. The id and url properties are always included.

Field keys are listed in the API Property Reference in your Celoxis account. For most columns, use the key as shown. For association columns (such as User or Project on a time entry), that table uses __data_ as a separator. In the fields parameter, replace that with a dot — for example user.name rather than user.__data_name. The response still uses the shorter key (for example user).

To include association data instead of only the association link, add the association columns you need to the fields array (for example user.name, project.name).

Fetch time entries for project 1234, returning only id, date, hours, comments, time code, state, and user and project details:

curl -g -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: bearer YourTokenHere' \
  -G --data-urlencode 'fields=["id","date","hours","comments","timeCode","state","user.name","project.name"]' \
  --data-urlencode 'filter={"project.id":"1234"}' \
  'https://app.celoxis.com/psa/api/v2/timeEntries'

Fetch the 2nd page of tasks whose name starts with Joy, including project name and deadline:

curl -g -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: bearer YourTokenHere' \
  -G --data-urlencode 'filter={"name":"^Joy","project.deadline":"Next Week"}' \
  --data-urlencode 'fields=["id","name","project.name","project.deadline"]' \
  'https://app.celoxis.com/psa/api/v2/tasks?page=2'

To fetch details of associations of an entity:

Fetch all predecessors of a task whose ID is 12345:

curl -g -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: bearer YourTokenHere' \
  'https://app.celoxis.com/psa/api/v2/tasks/12345/predecessors'