Busy API (1.0.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. Only hour entries that the authenticated user has access to is returned.

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"

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>

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

Responses

Response samples

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

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",
  • "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": [
    • {
      }
    ]
}

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": [
    • {
      }
    ]
}