Getting started

This document describes how to use 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.

Registering your OAuth application

Once your account have been registered, go to OAuth apps and click "Create App" link and fill required fields.

Issuing personal access token

You can issue personal access tokens and send requests to API instead of creating OAuth apps.

Developer Guidelines

You must follow TimeTree Developer Guidelines to build your applications.

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.

API Versioning

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

Accept: application/vnd.timetree.v1+json

HTTP Methods

Method Description
GET Retrieving resources.
POST Creating resources.
PUT Updateing 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 occured. 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 5000 requests per hour. You can check the request limit in headers of all responses. Request limit is counted by request IP and access token.

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
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)"
}

Authentication

Authorization workflow

TimeTree API uses OAuth2 to Authenticate and Authorize TimeTree account. TimeTree's OAuth2 URL is https://timetreeapp.com/oauth/.

  1. Access https://timetreeapp.com/oauth/authorize with query parameters below.
Param Description
client_id Your application's client id.
redirect_uri A URI to redirect that handles successful authorization.
response_type A response type you are requesting. TimeTree API only supports code.
state A string managing state of the request. We recommend to give it to CSRF vulnerability.
code_challenge (Option) Parameter for PKCE. A String generated from code_verifier.
code_challenge_method (Option) Parameter for PKCE. We reccomend S256.
GET https://timetreeapp.com/oauth/authorize?client_id={client_id}&response_type=code&state={csrf_token}
  1. TimeTree redirects to URI specified redirect_uri with code parameter. The code parameter expires in 10 minutes.
GET {redirect_uri}?code={code}&state={csrf_token}
  1. Request to https://timetreeapp.com/oauth/token with the following parameters to JSON body to get access token.
Param Description
client_id Your application's client id
client_secret Your application's secret
redirect_uri A URI to redirect that handles successful authorization.
code The authorization code given by TimeTree.
grant_type Only authorization_code is valid.
code_verifier (Option) If you pass the PKCE parameters previous step, this is required. A string used to generate code_challenge.
POST https://timetreeapp.com/oauth/token

If successful, the response body including access token will be returned.

{
  "acess_token": "ACCESS_TOKEN",
  "created_at": 1558583443,
  "token_type": "Bearer"
}
  1. You need to include access token as Bearer token in Authorization header to request TimeTree API.
Authorization: Bearer ACCESS_TOKEN

Authorization via personal access token

You can use a personal access token in Authorization header to request TimeTree API the same like OAuth apps.

Authorization: Bearer PERSONAL_ACCESS_TOKEN

Current User

GET /user

Get authorized user's(current user) information.

Parameters

None

Curl Example

$ curl https://timetreeapis.com/user \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "id":  "12345",
    "type": "user",
    "attributes": {
      "name": "Your Name",
      "description": "blah blah blah",
      "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
    }
  }
}

Calendars

GET /calendars

Get calendar list that current user can access.

Parameters

Parameter Description
include Includes association's object in the response. Separated by ,. Only supports labels and members. Optional

Curl Example

$ curl https://timetreeapis.com/calendars?include=labels,members \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id":  "1234",
      "type": "calendar",
      "attributes": {
        "name": "Some Calendar1",
        "description": "Calendar description",
        "color": "#2ecc87",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png",
        "created_at": "2019-04-01T12:34:56.000Z"
      },
      "relationships": {
        "labels": {
          "data": [
            { "id": "1234,1", "type": "label" },
            // ...
            { "id": "1234,10", "type": "label" }
          ]
        },
        "members": {
          "data": [
            { "id": "1234,12345", "type": "user" },
            { "id": "1234,23456", "type": "user" }
          ]
        }
      }
    },
    {
      "id":  "5678",
      "type": "calendar",
      "attributes": {
        "name": "Some Calendar2",
        "description": "Calendar description",
        "color": "#2ecc87",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png",
        "created_at": "2019-04-01T12:34:56.000Z"
      },
      "relationships": {
        // ...
      }
    }
  ],
  "included": [
    {
      "id": "1234,1",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#2ecc87"
      }
    },
    // ...
    {
      "id": "1234,12345",
      "type": "user",
      "attributes": {
        "name": "User1",
        "description": "blah blah blah",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
      }
    },
    // ...
  ]
}

GET /calendars/:calendar_id

Get a single calendar's information.

Parameters

Parameter Description
calendar_id Calendar's id. Required
include Includes association's object in the response. Separated by ,. Only supports labels and members. Optional

Curl Example

$ curl https://timetreeapis.com/calendars/1234?include=labels,members \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "id":  "1234",
    "type": "calendar",
    "attributes": {
      "name": "Some Calendar",
      "description": "Calendar description",
      "color": "#2ecc87",
      "image_url": "https://attachments.timetreeapp.com/path/to/image.png",
      "created_at": "2019-04-01T12:34:56.000Z"
    },
    "relationships": {
      "labels": {
        "data": [
          { "id": "1234,1", "type": "label" },
          { "id": "1234,2", "type": "label" },
          { "id": "1234,3", "type": "label" },
          { "id": "1234,4", "type": "label" },
          { "id": "1234,5", "type": "label" },
          { "id": "1234,6", "type": "label" },
          { "id": "1234,7", "type": "label" },
          { "id": "1234,8", "type": "label" },
          { "id": "1234,9", "type": "label" },
          { "id": "1234,10", "type": "label" }
        ]
      },
      "members": {
        "data": [
          { "id": "1234,12345", "type": "user" },
          { "id": "1234,23456", "type": "user" }
        ]
      }
    }
  },
  "included": [
    {
      "id": "1234,1",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#2ecc87"
      }
    },
    // ...
    {
      "id": "1234,12345",
      "type": "user",
      "attributes": {
        "name": "User1",
        "description": "blah blah blah",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
      }
    },
    // ...
  ]
}

GET /calendars/:calendar_id/labels

Get a calendar's label information used in event.

Parameters

Parameter Description
calendar_id Calendar's id. Required

Curl Example

$ curl https://timetreeapis.com/calendars/1234/labels \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "1234,1",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#2ecc87"
      }
    },
    {
      "id": "1234,2",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#3dc2c8"
      }
    },
    // ...
  ]
}

GET /calendars/:calendar_id/members

Get a calendar's member information.

Parameters

Parameter Description
calendar_id Calendar's id. Required

Curl Example

$ curl https://timetreeapis.com/calendars/1234/members \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "1234,12345",
      "type": "user",
      "attributes": {
        "name": "User1",
        "description": "blah blah blah",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
      }
    },
    {
      "id": "1234,56789",
      "type": "user",
      "attributes": {
        "name": "User2",
        "description": "Foo Bar",
        "image_url": "https://attachments.timetreeapp.com/path/to/anothor_image.png"
      }
    },
    // ...
  ]
}

Events, Keeps

GET /calendars/:calendarid/events/:eventid

Get event's information.

Parameters

Parameter Description
calendar_id Calendar's id. Required
event_id Event's id. Required
include Includes association's object in the response. Separated by ,. Only supports creator, label and attendees. Optional

Curl Example

$ curl https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a?include=creator,label,attendees \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "id": "c9c8e0fd66c34505a876d88cb4bb3b2a",
    "type": "event",
    "attributes": {
      "category": "schedule",
      "title": "Event title",
      "all_day": false,
      "start_at": "2019-03-18T09:00:00.000Z",
      "start_timezone": "UTC",
      "end_at": "2019-03-18T10:00:00.000Z",
      "end_timezone": "UTC",
      "recurrences": [],
      "description": "blah blah blah",
      "location": "Tokyo",
      "url": "https://example.com",
      "updated_at": "2019-03-18T09:53:33.123Z",
      "created_at": "2019-03-18T09:53:33.123Z"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1234,12345",
          "type": "user"
        }
      },
      "label": {
        "data": {
          "id": "1234,1",
          "type": "label"
        }
      },
      "attendees": {
        "data": [
          { "id": "1234,12345", "type": "user" },
          { "id": "1234,56789", "type": "user" }
        ]
      }
    }
  }
}

POST /calendars/:calendar_id/events

Creates an event to the calendar.

Parameters

Parameter Description
calendar_id Calendar's id. Required
data:attributes:title Event's title. Up to 50 characters. Required
data:attributes:category Specify schedule or keep. Required
data:attributes:all_day All day event flag. schedule: Required、keep: Optional
data:attributes:start_at Start datetime(ISO8601). If all day event, you must set time to 00:00:00. schedule: Required、keep: Optional
data:attributes:start_timezone Start timezone. Optional
data:attributes:end_at End datetime(ISO8601). If all day event, you must set time to 00:00:00. You must set after start_at. schedule: Required、keep: Optional
data:attributes:end_timezone End timezone. Optional
data:attributes:description Description(note). Up to 10000 characters. Optional
data:attributes:location Location. Up to 100 characters. Optional
data:attributes:url URL. Optional
data:relationships:label:data:id Event's label id. Required
data:relationships:label:data:type label only. Required
data:relationships:attendees:data[]:id Attendee's user id. Optional
data:relationships:attendees:data[]:type user only. If you have data:relationships:attendees:data[]:id, required

Curl Example

$ curl https://timetreeapis.com/calendars/1234/events \
  -d '{
    "data": {
      "attributes": {
        "category": "schedule",
        "title": "Event title",
        "all_day": false,
        "start_at": "2019-03-18T09:00:00.000Z",
        "start_timezone": "UTC",
        "end_at": "2019-03-18T10:00:00.000Z",
        "end_timezone": "UTC",
        "description": "blah blah blah",
        "location": "Tokyo",
        "url": "https://example.com"
      },
      "relationships": {
        "label": {
          "data": {
            "id": "1234,1",
            "type": "label"
          }
        },
        "attendees": {
          "data": [
            { "id": "1234,12345", "type": "user" },
            { "id": "1234,56789", "type": "user" }
          ]
        }
      }
  }' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 201 Created
{
  "data": {
    "id": "c9c8e0fd66c34505a876d88cb4bb3b2a",
    "type": "event",
    "attributes": {
      "category": "schedule",
      "title": "Event title",
      "all_day": false,
      "start_at": "2019-03-18T09:00:00.000Z",
      "start_timezone": "UTC",
      "end_at": "2019-03-18T10:00:00.000Z",
      "end_timezone": "UTC",
      "recurrences": [],
      "description": "blah blah blah",
      "location": "Tokyo",
      "url": "https://example.com",
      "updated_at": "2019-03-18T09:53:33.123Z",
      "created_at": "2019-03-18T09:53:33.123Z"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1234,12345",
          "type": "user"
        }
      },
      "label": {
        "data": {
          "id": "1234,1",
          "type": "label"
        }
      },
      "attendees": {
        "data": [
          { "id": "1234,12345", "type": "user" },
          { "id": "1234,56789", "type": "user" }
        ]
      }
    }
  }
}

PUT /calendars/:calendarid/events/:eventid

Updates an event.

Parameters

Parameter Description
calendar_id Calendar's id. Required
event_id Event's id. Required
data:attributes:title Event's title. Up to 50 characters. Required
data:attributes:category Specify schedule or keep. Required
data:attributes:all_day All day event flag. schedule: Required、keep: Optional
data:attributes:start_at Start datetime(ISO8601). If all day event, you must set time to 00:00:00. schedule: Required、keep: Optional
data:attributes:start_timezone Start timezone. Optional
data:attributes:end_at End datetime(ISO8601). If all day event, you must set time to 00:00:00. You must set after start_at. schedule: Required、keep: Optional
data:attributes:end_timezone End timezone. Optional
data:attributes:description Description(note). Up to 10000 characters. Optional
data:attributes:location Location. Up to 100 characters. Optional
data:attributes:url URL. Optional
data:relationships:label:data:id Event's label id. Required
data:relationships:label:data:type label only. Required
data:relationships:attendees:data[]:id Attendee's user id. Optional
data:relationships:attendees:data[]:type user only. If you have data:relationships:attendees:data[]:id, required

Curl Example

$ curl -X PUT https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a \
  -d '{
    "data": {
      "attributes": {
        "category": "schedule",
        "title": "Event title",
        "all_day": false,
        "start_at": "2019-03-18T09:00:00.000Z",
        "start_timezone": "UTC",
        "end_at": "2019-03-18T10:00:00.000Z",
        "end_timezone": "UTC",
        "description": "blah blah blah",
        "location": "Tokyo",
        "url": "https://example.com"
      },
      "relationships": {
        "label": {
          "data": {
            "id": "1234,1",
            "type": "label"
          }
        },
        "attendees": {
          "data": [
            { "id": "1234,12345", "type": "user" },
            { "id": "1234,56789", "type": "user" }
          ]
        }
      }
  }' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "type": "event",
    "id": "c9c8e0fd66c34505a876d88cb4bb3b2a",
    "attributes": {
      "category": "schedule",
      "title": "Event title",
      "all_day": false,
      "start_at": "2019-03-18T09:00:00.000Z",
      "start_timezone": "UTC",
      "end_at": "2019-03-18T10:00:00.000Z",
      "end_timezone": "UTC",
      "recurrences": [],
      "description": "blah blah blah",
      "location": "Tokyo",
      "url": "https://example.com",
      "updated_at": "2019-03-18T09:53:33.123Z",
      "created_at": "2019-03-18T09:53:33.123Z"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1234,12345",
          "type": "user"
        }
      },
      "label": {
        "data": {
          "id": "1234,1",
          "type": "label"
        }
      },
      "attendees": {
        "data": [
          { "id": "1234,12345", "type": "user" },
          { "id": "1234,56789", "type": "user" }
        ]
      }
    }
  }
}

DELETE /calendars/:calendarid/events/:eventid

Deletes an event.

Parameters

Parameter Description
calendar_id Calendar's id. Required
event_id Event's id. Required

Curl Example

$ curl -X DELETE https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 204 No Content

Activities

POST /calendars/:calendarid/events/:eventid/activities

Creates comment to an event.

Parameters

Parameter Description
calendar_id Calendar's id. Required
event_id Event's id. Required
data:attributes:content Comennt text. Up to 1000 characters. Required

Curl Example

$ curl -X POST https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a/activities \
  -d '{
    "data": {
      "attributes": {
        "content": "This is comment"
      }
    }
  }' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 201 Created
{
  "data": {
    "id": "5fde58f529bf4359b6cc15523ed86965",
    "type": "activity",
    "attributes": {
      "content": "This is comment",
      "updated_at": "2019-04-01T12:34:56.000Z",
      "created_at": "2019-04-01T12:34:56.000Z"
    }
  }
}