Busy API (1.1.0)

Download OpenAPI specification:Download

Introduction

This is the official API documentation for Busy's REST API. The goal of the API is to allow for creating integrations with other software

If you have any requests or need support, contact us via our chat at https://busy.no/ or send us a mail at apisupport@busy.no.

Getting started

To get started with the API, go to our 1-click API demo workspace. This will generate a demo workspace for you – complete with dummy data and an API key.

With your API key you can then start making requests to the API endpoints defined in this reference (using https://api.demo.busy.no/ as the base URL). Note: Remember to include the X-Api-Key header with your key as value.

See the Authentication section for more information about auth and production access.

Client libraries

We don't have any official client libraries at the moment, but there are plenty of code generators which can generate code from our OpenAPI 3.0 spec. Here's a one-liner (using oazapfts!) to generate a library in a TypeScript project:

npm install oazapfts && oazapfts https://api.busy.no/openapi.json busyApi.ts

Usage policy

Be nice to our API – avoid sending unnecessary large requests or unnecessary many requests. If the API gets abused, we reserve the right to revoke access for that user or workspace.

The API is currently in early stages, and while we strive to keep 100% backwards compatibility, the API might still get smaller breaking changes.

Usage in the production environment

We recommend that you use the demo environment to develop and test your integrations. All use of the API in the production environment is at your own risk – wrongly composed API calls may have severe consequences, and you don't want to unintentionally delete or corrupt your workspace's data.

Response types

Normally, the API endpoints return a 200 OK response. For specific response codes and data, see each endpoint.

Global error types

In addition to the responses defined for each endpoint, there are a set of error responses that might be returned for any requests. The response will follow the RFC 7807 Problem Details format, which has the content type application/problem+json.

HTTP code Description
400 Invalid input data. The response object contains details on the expected values.
401 The request was not authenticated correctly. This is most likely because of a missing or invalid API key.
403 The request was authenticated, but the user does not have access to the requested resource. Note that the API key only have access to the resources that its user has.
404 The requested endpoint or resource was not found.
429 The rate limiter was triggered – see the Retry-After, X-RateLimit-Reset, X-RateLimit-Limit, and X-RateLimit-Remaining headers.
500 An error has occurred on our end. This should normally not happen, and we log and fix these issues; contact us if this error persists.

Data types

The data types are specified for each endpoint – here is a list of commonly used formats:

  • Date and time: ISO-8601
  • Query string arrays/lists: repeat the variable for each element, e.g. /query?array=1&array=2&array=3 for an array array = [1, 2, 3].

Pagination

To avoid fetching of unneeded amounts of data, all the endpoints returning lists of data implements pagination. The API uses limit and offset to control how much and which data to return, similar to most database systems.

Authentication

API Key

The API currently supports personal API keys for authentication. The API key is connected to one user, which means that you will get the exact same privileges as the user whose API key it is. If you generate an API key as an admin, you will have full access to the workspace. If you generate one as a regular user, it will only have access to what that user has access to.

1-click API demo workspace

The fastest method for testing out the APi is by navigating to the 1-click API demo workspace. This will generate a demo workspace for you – complete with dummy data and an API key – without any registration needed.

Production API key

To use the API in production, simply log in to your user on https://app.busy.no and generate an API key for your user in "Settings" → "Integrations" → "API access".

Remember to use https://api.busy.no as the base URL for API calls.

Authenticating HTTP requests

Use the X-Api-Key header to authenticate your requests. The value of the header should be the API key you have already generated.

Security Scheme Type API Key
Header parameter name: X-API-Key

Account

Operations related to accounts (which can have multiple users).

Get signed in account

Gets the account of the authenticated user.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "string",
  • "lastActiveUserId": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

HourEntry

Operations related to hour entries.

Get hour entries

Gets hour entries based on set of filters. The following hour entries are accessible:

  • The user's own hour entries
  • The hour entries logged on projects where the authenticated user is a project manager
  • The hour entries of the users that the authenticated user is a group leader for
Authorizations:
query Parameters
offset
integer <int32> [ 0 .. 2147483647 ]
Default: 0

The offset of the result set to start at.

limit
integer <int32> [ 1 .. 100 ]
Default: 10

The maximum amount of results to return.

orderBy
string
Default: "startTime"
Enum: "startTime" "createdAt" "updatedAt"

The field to order by.

orderByDirection
string
Default: "asc"
Enum: "asc" "desc"

The direction to order by.

createdAtMin
string <date-time>

Filters entries that were created at the given point in time or later (inclusive min).

startTimeMin
string <date-time>

Filters entries that starts at the given point in time or later (inclusive min).

startTimeMax
string <date-time>

Filters entries that starts at the given point in time or earlier (inclusive max).

userIdIn
Array of numbers <double> [ items <double > ]

Filters entries that belongs to one of the specified user IDs.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Create hour entry

Creates an hour entry.

Authorizations:
Request Body schema: application/json
startTime
required
string <date-time>

The start time of the entry.

stopTime
required
string <date-time>

The stop time of the entry. Must be same or later than startTime.

billableMinutes
integer <int32> >= 0

Specifies how many minutes of the entry which is billable – used for calculating prices in reports and invoice orders.

projectId
required
string

The ID of the project to use.

tagId
required
string

The ID of the tag to use.

description
string

A description of the entry.

userId
string

The ID of the user to log time for. If not specified, the authenticated user is used.

flagged
boolean

Specifies if the entry has been marked with a flag. The flag is only used by Busy to visually show a flag on the entry.

approved
boolean

Specifies if the entry has been approved by a group leader, project manager, or admin.

locked
boolean

Specifies if the entry is locked for edits and has to be unlocked to be edited again.

Responses

Request samples

Content type
application/json
{
  • "startTime": "2019-08-24T14:15:22Z",
  • "stopTime": "2019-08-24T14:15:22Z",
  • "billableMinutes": 0,
  • "projectId": "string",
  • "tagId": "string",
  • "description": "string",
  • "userId": "string",
  • "flagged": true,
  • "approved": true,
  • "locked": true
}

Response samples

Content type
application/json
{
  • "id": "1552",
  • "userId": "6532",
  • "projectId": "335",
  • "tagId": "12",
  • "startTime": "2021-11-12T13:00:00.000Z",
  • "stopTime": "2021-11-12T15:00:00.000Z",
  • "billableMinutes": 60,
  • "createdAt": "2021-11-05T09:15:30.369Z",
  • "updatedAt": "2021-11-05T09:15:30.369Z",
  • "description": "Very productive work session",
  • "flagged": false,
  • "approved": false,
  • "locked": false
}

Update hour entry

Updates an hour entry.

Authorizations:
path Parameters
hourEntryId
required
integer <int32>

The ID of the hour entry to edit.

Request Body schema: application/json
startTime
string <date-time>

The start time of the entry.

stopTime
string <date-time>

The stop time of the entry. Must be same or later than startTime.

billableMinutes
integer <int32> >= 0

Specifies how many minutes of the entry which is billable – used for calculating prices in reports and invoice orders.

projectId
string

The ID of the project to use.

tagId
string

The ID of the tag to use.

description
string

A description of the entry.

flagged
boolean

Specifies if the entry has been marked with a flag. The flag is only used by Busy to visually show a flag on the entry.

approved
boolean

Specifies if the entry has been approved by a group leader, project manager, or admin.

locked
boolean

Specifies if the entry is locked for edits and has to be unlocked to be edited again.

Responses

Request samples

Content type
application/json
{
  • "startTime": "2019-08-24T14:15:22Z",
  • "stopTime": "2019-08-24T14:15:22Z",
  • "billableMinutes": 0,
  • "projectId": "string",
  • "tagId": "string",
  • "description": "string",
  • "flagged": true,
  • "approved": true,
  • "locked": true
}

Response samples

Content type
application/json
{
  • "id": "1552",
  • "userId": "6532",
  • "projectId": "335",
  • "tagId": "12",
  • "startTime": "2021-11-12T13:00:00.000Z",
  • "stopTime": "2021-11-12T15:00:00.000Z",
  • "billableMinutes": 60,
  • "createdAt": "2021-11-05T09:15:30.369Z",
  • "updatedAt": "2021-11-05T09:15:30.369Z",
  • "description": "Very productive work session",
  • "flagged": false,
  • "approved": false,
  • "locked": false
}

User

Operations related to users (which belong to one workspace).

Get signed in user

Gets the authenticated user.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "email": "string",
  • "displayName": "string",
  • "accountId": "string",
  • "workspaceId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get users

Get users based on a set of filters.

Authorizations:
query Parameters
offset
integer <int32> [ 0 .. 2147483647 ]
Default: 0

The offset of the result set to start at.

limit
integer <int32> [ 1 .. 100 ]
Default: 10

The maximum amount of results to return.

orderBy
string
Default: "createdAt"
Enum: "createdAt" "updatedAt"

The field to order by.

orderByDirection
string
Default: "asc"
Enum: "asc" "desc"

The direction to order by.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Project

Operations related to projects.

Get projects

Gets projects based on a set of filters.

Authorizations:
query Parameters
offset
integer <int32> [ 0 .. 2147483647 ]
Default: 0

The offset of the result set to start at.

limit
integer <int32> [ 1 .. 100 ]
Default: 10

The maximum amount of results to return.

orderBy
string
Default: "name"
Enum: "name" "createdAt" "updatedAt"

The field to order by.

orderByDirection
string
Default: "asc"
Enum: "asc" "desc"

The direction to order by.

include
Array of strings
Items Enum: "users" "tags"

Values that can be included on a project.

  • users - The participants of the project.
  • tags - The tags enabled on the project.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Project Task

Operations related to project tasks.

Get project tasks

Gets project tasks based on set of filters.

Authorizations:
query Parameters
offset
integer <int32> [ 0 .. 2147483647 ]
Default: 0

The offset of the result set to start at.

limit
integer <int32> [ 1 .. 100 ]
Default: 10

The maximum amount of results to return.

orderBy
string
Default: "createdAt"
Enum: "name" "createdAt" "updatedAt"

The field to order by.

orderByDirection
string
Default: "asc"
Enum: "asc" "desc"

The direction to order by.

createdAtMin
string <date-time>

Filters entries that were created at the given point in time or later (inclusive min).

updatedAtMin
string <date-time>

Filters entries that were updated at the given point in time or later (inclusive min).

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}

Create project task

Creates a project task.

Authorizations:
Request Body schema: application/json
projectId
required
string

The ID of the project that the project task belongs to.

name
required
string

A short description of the task.

description
string

A longer description of the task.

participantUserIds
Array of strings <= 20 items

A list of the IDs of the users that participate in this task.

startDate
string or null <date>

An estimate on when the task should be started worked at.

stopDate
string or null <date>

An estimate on when the task should be finished.

durationEstimate
integer or null <int32> >= 0

An estimate of how many minutes completing the task will take.

defaultTagId
string or null

The default tag to use when logging time on the task.

externalId
string or null

An ID for the task in another system. This value can be set by integrations to easier keep a link between a task in Busy and in an external system.

Responses

Request samples

Content type
application/json
{
  • "projectId": "string",
  • "name": "string",
  • "description": "string",
  • "participantUserIds": [
    • "string"
    ],
  • "startDate": "2019-08-24",
  • "stopDate": "2019-08-24",
  • "durationEstimate": 0,
  • "defaultTagId": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "projectId": "string",
  • "name": "string",
  • "description": "string",
  • "participantUserIds": [
    • "string"
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "stopDate": "2019-08-24T14:15:22Z",
  • "durationEstimate": 0,
  • "defaultTagId": "string",
  • "externalId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Tag

Operations related to tags.

Get tags

Get tags based on a set of filters.

Authorizations:
query Parameters
offset
integer <int32> [ 0 .. 2147483647 ]
Default: 0

The offset of the result set to start at.

limit
integer <int32> [ 1 .. 100 ]
Default: 10

The maximum amount of results to return.

orderBy
string
Default: "name"
Enum: "name" "createdAt" "updatedAt"

The field to order by.

orderByDirection
string
Default: "asc"
Enum: "asc" "desc"

The direction to order by.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}