TimeTree API overview

This document describes an overview of TimeTree API.

Creating TimeTree account

First, you must register TimeTree account to use TimeTree API. If you have already use TimeTree iOS/Android, you can register via mobile app.

Developer Guidelines

You must follow TimeTree Developer Guidelines to build your applications.

Application types

TimeTree API has three different applications. Each application has following features and can be selected according to the purpose.

Calendar App

  • Calendar App is an application that is associated with user's calendar.
  • Calendar App can access to only the specific calendar specified by the user.
  • Calendar App can access as if you were a single user participating in the calendar.
  • The icon / name is displayed as an app for creators of events / comments.
  • The connection is maintained even if the linked user leaves the calendar.

To create a Calendar App, go to Calendar App page, click on "Create App" and enter the required information.

Calendar App API reference is here

OAuth App

  • OAuth App is an application on behalf of the user.
  • OAuth App can manipulate resources that users can access.
  • Since it is "on behalf of the user", the creator of the events / comments will be the linked user.
  • If a user leaves a calendar, the OAuth App will not be able to access that calendar.

To create an OAuth App, go to OAuth App page, click on "Create App" and enter the required information.

OAuth App API reference is here

Personal access token

  • Personal access token is intended for personal API trials.
  • Personal access token accesses TimeTree on behalf of the user, just like the OAuth App.

To create a Personal access token, go to Personal access token page, click on "Create Token" and enter the required information.

Personal access token API reference is here

Determining which app to build

  • Display as an application in events and comments → Calendar App
  • Application accesses multiple calendars → OAuth App or Personal access token
  • Try the API for the time being or simplify authentication → Personal access token

Client

API Clients must request to timetreeapis.com using HTTPS.

Schema

Requests and responses follows JSON:API formats. When you include JSON body in the request, specify Content-Type: application/json header. DateTime is represented as ISO8601 formatted string.

Time zone

To express a time zone, you can use a string from the IANA's Time Zone Database. For example, to specify Tokyo as a time zone, you can specify it with Asia/Tokyo.

API Versioning

All API requests are processed as v1 version. But we recommend specifying Accept header explicitly.

Accept: application/vnd.timetree.v1+json

Authentication

The access token obtained by each authentication method must be included in the Authorization header of the API request as a Bearer token.

Authorization: Bearer ACCESS_TOKEN

Scopes

TimeTree API requires the following scopes to access each endpoint.

  • Read: User, Calendar, Calendar Member, Event
  • Write: Event, Comment

HTTP Methods

Method Description
GET Retrieving resources.
POST Creating resources.
PUT Updating resources.
DELETE Deleting resources.

HTTP Status

Successful Status

Status Description
200 OK Request succeeded.
201 Created Resource created.
204 No Content Request succeeded, but no response.

Failure status

Client failure

Status Description
400 Bad Request Request invalid. Refer errors and fix your request.
401 Unauthorized Request not authenticated. Access token is missing or invalid.
403 Forbidden Request not authorized. Request is being performed on an unpermitted resource.
404 Not Found Request failed. Specified resource does not exist.
406 Not Acceptable Request failed. Specify json format.
429 Too Many Requests Request failed. Wait for rate limit until unix timestamp in X-RateLimit-Reset header.

Server failure

Status Description
500 Internal Server Error Unknown error occurred. Contact support.
503 Service Unavailable API server is unavailable.
504 Timeout Request timeouts. Wait for a while and try again.

Rate Limiting

TimeTree API has a limit of 600 requests per every 10 minutes. You can check the request limit in headers of all responses. Request limit is counted by request IP and access token.

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1556093863

Error Responses

Error responses follow RFC7807 Problem Details for HTTP APIs format. In some case, a response has errors property that includes error details.

HTTP/1.1 404 Not Found
{
  "type": "about#blank",
  "status": 404,
  "title": "Not Found",
  "errors": "error detail(optional)"
}