REST API

Operating has an open REST API you can find here:

https://operating.readme.io/reference/overview

Pagination on the report endpoints

The four report endpoints can return a lot of data in one response:

• /v1/reports/people-actual

• /v1/reports/people-planned

• /v1/reports/projects-actual

• /v1/reports/projects-planned

You can ask for the data one page at a time. Add the limit query parameter to set how many people or projects you get per page. The value must be a whole number from 1 to 200.

When you set limit, the response shape changes. Instead of a bare array of time blocks, you get an object with two keys:

• data — the usual array of time blocks, with only that page of people or projects in each block.

• meta.nextCursor — the cursor for the next page. Pass this value in the after query parameter to get the next page. The value is null when there are no more pages.

Pagination is optional. If you leave limit out, the endpoint returns the bare array as before.

The after parameter needs limit. If you send after on its own, the request fails with a validation error.

Site and role history, position groups, assignments and project notes

The full request and response formats for these resources are in the API reference.

• /person-site-assignments — a person's site over time. Each assignment has a site and a from date, and together they cover every date with exactly one site. When you create an assignment, it starts on its from date (today if you leave from out) and the period before it ends the day before. When you change from, the period before it moves with it. When you delete an assignment, the period next to it grows to fill the gap. A person's only assignment can't be deleted.

• The person siteId field is deprecated. Writing it replaces the person's whole site history with one site for all dates. To change a person's site from a given date, create a person site assignment.

• /competence-role-assignments — a person's roles over time. Each assignment has a from and a through date, and a null date means the period has no start or no end. A person has one primary role on each date. When you create a primary assignment, the current primary role ends the day before its from date, and Operating sets the through date of a primary assignment from the next one. Additional roles can have any date range.

• /position-group-assignments — the Groups a position belongs to, separate from the Groups of its project. You can list them (filtered by positionId or groupId), create one with a positionId and a groupId, read one, and delete one.

• /assignments supports list, read and create. To move a person to another position, set assignedPersonId on the position.

• /project-notes — dated notes on a project. Each note has a projectId, a noteText and a noteDate (YYYY-MM-DD). You can list notes, filtered by projectId and by createdSince, createdBefore, updatedSince and updatedBefore and paged with limit and after. You can also create, read, update and delete a note. A new note needs all three fields, and noteText can't be empty.