• Add support for adding people to a skill
• Improved performance for GET /projects
• Improved PATCH /project-tags to support removal

• Added tags on response to GET /projects
• Added includePlaceholders filter for GET /people
• Added GET /projects/:id/people
• Replaced GET /milestones with GET /projects/:id/milestones
• API v1 beta release notes

See API v1 usage instructions. While the API v1 is still in beta this changelog is 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
• 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

• Added GET, POST /people-tags
• Added archive/unarchive projects through PATCH /projects/{id}
• Fix for POST /assignments when holidays exist
• Fix for showing error when placeholder is used on POST /actuals
• Fix to show correct number format on GET /projects
• Fix for GET /clients not returning correct response

• Added GET /reports/hours/projects/:id
• Added support for people skills
• Added DELETE /projects/:projectId/milestones/:milestoneId
• Added GET /skills/:id/people endpoint
• Added DELETE /time-offs/rostered-off/:id
• Added GET /reports/totals/projects/:id
• Added GET /project/:id/project-rates
• Added GET /timeoffs/rostered-off
• Added GET /people/:id/time-offs/rostered-off
• Added date filters to GET /projects/id/assignments
• Added date filters to GET /people/id/assignments
• Added GET /people/{personId}/time-offs
• Added DELETE /time-offs/:id
• Added GET /reports/hours/people
• Added DELETE /person/:id:/skills/:skill
• Added GET /reports/totals/projects
• Added GET /invitations
• Added DELETE /invitations/:id
• Added POST /time-offs
• Improved docs with consistent OpenAPI tags