API v1 Changelog
Written by Ingo Schommer
Updated over a week ago

See API v1 usage instructions. The API v1 is still in beta, hence this changelog a living document.



The base URL for using API v1 is https://api.runn.io (this has changed from v0)

Note: Refer to “Accounts > Settings > API” for your specific API endpoint URL, it might differ from the above.

Accept-Version Header

We now require passing an Accept-Version header, specifying the version of the API you’d like to use. Example: Accept-Version: 1.0.0


Changed from page-based to cursor-based pagination. Instead of per_page, use limit. Instead of page, use the cursor provided as nextCursor in the previous API response


We've switched from hashids to numeric identifiers to identify resources.





In order to convert existing references to the new format, we have provided a /legacy-id endpoint. To convert the example above, use the following request:

GET /legacy-id/people/156ocz

You also have the option to convert these values locally for better performance. Here's an example Python implementation, which you can adapt to a programming language of your choice (using one of the many implementations on hashids.org)

Naming Format

  • Changed all property and parameter names from lower snakecase to camelcase: person_id becomes personId

  • Changed endpoint paths from snakecase to dashcase. Example: GET /v0/time_offs becomes GET /time-offs

Request and Response Structure

  • Dropped the /v0 prefix on paths

  • Changed HTTP verbs from PUT to PATCH

  • Collection endpoint results are nested in a {values: []} object

References Format

Changed references format on all endpoints.


"My Name": {"external_id": "My ID"},
"My Other Name": {"external_id": "My Other ID"}


{"referenceName": "My Name", "externalId": "My ID"},
{"referenceName": "My Other Name", "externalId": "My Other ID"}

Tags Format

Changed tags format on all endpoints. Retrieve tag identifiers from GET /project-tags


["My Tag", "My Other Tag"]


[{id: 1}, {id: 2}]

Endpoint Specific Changes

  • GET /invitations: sentDate attribute renamed to sentAt

  • POST /actuals: No longer allows clearing phases with empty strings, requires phaseId=null

  • POST /actuals: No longer auto-fills gaps (autofill=true)

  • GET /actuals: Date filtering parameters renamed to minDate and maxDate

  • GET /actuals: No longer returns updated_at or origin_data

  • GET /assignments: Renamed date filtering parameters to startDate and endDate

  • GET /assignments: No longer returns total_minutes, use Reporting API instead

  • GET /assignments: Renamed active to isActive

  • GET /clients: Removed include_archived filter

  • GET /clients, POST /clients: Removed projects

  • GET /clients: Renamed url to website

  • GET /clients, POST /clients, PATCH /clients: Renamed archived to isArchived

  • GET /contracts: Changed rostered_days to availableDays (keyed by weekday name)

  • GET /milestones, POST /milestones, DELETE /milestones: Moved into /projects/:id/milestones subresource

  • GET /milestones: Renamed date filtering parameters to startDate and endDate

  • GET /people: Moved role_id and role_name to GET /people/:id/contracts/current

  • GET /people, GET /people/:id: Moved team_id and team to GET /people/:id/teams

  • GET /people, GET /people/:id: Moved current_contract to GET /people/:id/contracts/current

  • GET /people, GET /people/:id: Moved projects to GET /people/:id/projects, removed include_projects parameter

  • GET /people, GET /people/:id: Moved skills to GET /people/:id/skills

  • GET /people: Removed include_placeholders option, use GET /placeholders

  • GET /people/:id: Moved assignments to GET /people/:id/assignments, removed include_assignments, start and end parameters

  • GET /people/:id: Moved actuals to GET /people/:id/actuals, removed include_actuals, start and end parameters

  • GET /people/:id: Moved skills to GET /people/:id/skills, removed skills_unstable

  • GET /people/:id: Moved time_offs to GET /people/:id/time-offs

  • GET /people/:id: Moved holidays_unstable to GET /people/:id/time-offs/holidays

  • GET /people, GET /people/:id: Rename people_notes to notes

  • GET /people: Renamed archived to isArchived

  • POST /people: Removed role_name, use role_id

  • GET /phases: Moved to GET /projects/:id/phases

  • POST /placeholders : Create placeholders so you can then create assignments for placeholders on projects (retaining functionality from v0)

  • GET /project_notes: Moved to GET /projects/:id/notes

  • POST /project_notes: Moved to POST /projects/:id/notes

  • POST /project_notes: Removed ability to set user_id, defaults to “API” user

  • GET /projects: Includes template projects by default (filter manually based on isTemplate property)

  • GET /projects/:id: Moved assignments to GET /projects/:id/assignments, removed include_assignments option

  • GET /projects/:id: Moved actuals to GET /projects/:id/actuals, removed include_actuals option

  • GET /projects/:id: Moved milestones to GET /projects/:id/milestones

  • GET /projects/:id: Moved other_expenses to GET /projects/:id/other-expenses

  • GET /projects/:id: Moved project_rates to GET /projects/:id/project-rates

  • GET /projects/:id: Moved phases to GET /projects/:id/phases

  • GET /projects/:id: Moved timesheet_locked_to to GET /projects/:id/timesheet-lock

  • GET /projects/:id/people - retaining functionality from v0

  • POST /projects, PATCH /projects/:id: Removed project_rates

  • POST /projects, PATCH /projects/:id: Renamed confirmed to isConfirmed

  • POST /projects/:id/project-rates and PATCH /projects/:id/project-rates

  • PUT /projects/:id/lock_timesheets: Moved to PATCH /projects/:id/timesheet-lock

  • GET /rate-cards: Changed blended_rate_hourly and blended_rate_daily to blendedRate and rateType

  • GET /rate-cards: Renamed archived to isArchived

  • POST /roles, PATCH /roles: Changed people to personIds

  • POST /skills/:id/people - retaining functionality from v0

  • GET /teams, POST /teams, PATCH /teams/:id: Removed people, use /people/:id/teams to identify and modify team membership

  • GET /time-offs: Removed type, split into separate subresources: GET /time-offs/leave, GET /time-offs/rostered-off.

  • GET /time_offs/holidays_unstable: Moved to GET /time-offs/holidays

  • GET /users: Changed permissions from serialised JSON strings to an actual object


We’re still working on these endpoints:

  • POST /invitations: Requires fromUser (no longer defaulting to first admin)

  • GET /placeholders

  • GET /people-tags/:id See all people who have this tag

  • GET /clients/:id/projects

  • GET /projects/:id/budget-roles

  • POST /projects/:id/other-expenses and PATCH /projects/:id/other-expenses/:id


  • GET /assignments: isTemplate and active

  • /custom-fields endpoints

  • Add customFields to GET /people/:id and GET /projects/:id

  • List public holidays separately from people through /holiday-groups

  • GET /projects: isTemplate, expensesBudget

  • GET /rate-cards: List projectIds

  • New reports API: GET /reports/*

  • /project-tags endpoints

Did this answer your question?