All Collections
API, Integrations, Import & Export
The Runn API
API v1 Changelog
API v1 Changelog
I
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.

v1.0.0

URL

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

Pagination

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

Identifiers

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

Before:

/v0/people/156ocz

After:

/people/123

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.

Before:

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

After:

[
  {"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

Before: 

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

After:

[{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

Unreleased

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

New

  • 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

Related Articles
API v0 Changelog
Changelog
FAQs on API
API v1 (Beta)
Q1 Updates
Did this answer your question?