OAuth App / Personal access token

This document describes the OAuth App authentication and API reference.

Authorization flor(OAuth App only)

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 recommend 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.

{
  "access_token": "ACCESS_TOKEN",
  "created_at": 1558583443,
  "token_type": "Bearer"
}

API reference

Get an authorized user

Get authorized user's information.

Endpoint

GET /user

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json is recommended
authorization string header Obtained access token

Scope

Read:User

cURL Example

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

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"
    }
  }
}

List calendars

Get a list of calendars.

Endpoint

GET /calendars

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
include string query Includes association's object in the response. Separated by ,. Only supports labels and members.

Scope

Read:Calendar

cURL Example

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

Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id":  "1234",
      "type": "calendar",
      "attributes": {
        "name": "Some Calendar1",
        "description": "Calendar description",
        "color": "#2ecc87",
        "order": 0,
        "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",
        "order": 1,
        "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 a calendar

Get the information of the calendar.

Endpoint

GET /calendars/:calendar_id

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID
include string query Includes association's object in the response. Separated by ,. Only supports labels and members.

Scope

Read:Calendar

cURL Example

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

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "id":  "1234",
    "type": "calendar",
    "attributes": {
      "name": "Some Calendar",
      "description": "Calendar description",
      "color": "#2ecc87",
      "order": 0,
      "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"
      }
    },
    // ...
  ]
}

List labels

Get the label information of the calendar.

Endpoint

GET /calendars/:calendar_id/labels

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID

Scope

Read:Calendar

cURL Example

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

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"
      }
    },
    // ...
  ]
}

List members

Get the member information of the calendar.

Endpoint

GET /calendars/:calendar_id/members

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar id

Scope

Read:Calendar Member

cURL Example

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

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"
      }
    },
    // ...
  ]
}

List upcoming events

Get information on the events after the day of the request for the specified calendar.

Endpoint

GET /calendars/:calendar_id/upcoming_events

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID
timezone string query Timezone. Used for all day event. This does not change response's timezone. Default is UTC.
days string query The number of days to get. A range from 1 to 7 can be specified. Default is 1.
include string query Includes association's object in the response. Separated by ,. Only supports creator, label and attendees.

Scope

Read:Event

cURL Example

$ curl \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://timetreeapis.com/calendars/1234/upcoming_events?timezone=Asia/Tokyo&days=3&include=creator,label,attendees

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",
        "recurrence": [],
        "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" }
          ]
        }
      },
      // ...
    }
  ]
}

Get an event

Get an event information.

Endpoint

GET /calendars/:calendar_id/events/:event_id

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID
event_id string path Event ID
include string query Includes association's object in the response. Separated by ,. Only supports creator, label and attendees.

Scope

Read:Event

cURL Example

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

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

Create an event

Create an event to the calendar.

Endpoint

POST /calendars/:calendar_id/events

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID
data:attributes:title string body Required Event's title. Up to 50 characters.
data:attributes:category string body Required Specify schedule or keep.
data:attributes:all_day boolean body All day event flag. schedule: Required、keep: Optional
data:attributes:start_at string body Start datetime(ISO8601). If all day event, you must set time to 00:00:00. schedule: Required、keep: Optional
data:attributes:start_timezone string body Start timezone
data:attributes:end_at string body 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 string body End timezone
data:attributes:description string body Description(note). Up to 10000 characters.
data:attributes:location string body Location. Up to 100 characters.
data:attributes:url string body URL
data:relationships:label:data:id string body Required Event's label id
data:relationships:label:data:type string body Required label only
data:relationships:attendees:data[]:id string body Attendee's user id
data:relationships:attendees:data[]:type string body user only. If you have data:relationships:attendees:data[]:id, required

Scope

Write:Event

cURL Example

$ curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  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" }
          ]
        }
      }
    }
  }'

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

Update an event

Update an event.

Endpoint

PUT /calendars/:calendar_id/events/:event_id

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID
event_id string path Event ID
data:attributes:title string body Required Event's title. Up to 50 characters.
data:attributes:category string body Required Specify schedule or keep.
data:attributes:all_day boolean body All day event flag. schedule: Required、keep: Optional
data:attributes:start_at string body Start datetime(ISO8601). If all day event, you must set time to 00:00:00. schedule: Required、keep: Optional
data:attributes:start_timezone string body Start timezone
data:attributes:end_at string body 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 string body End timezone
data:attributes:description string body Description(note). Up to 10000 characters.
data:attributes:location string body Location. Up to 100 characters.
data:attributes:url string body URL
data:relationships:label:data:id string body Required Event's label id
data:relationships:label:data:type string body Required label only
data:relationships:attendees:data[]:id string body Attendee's user id
data:relationships:attendees:data[]:type string body user only. If you have data:relationships:attendees:data[]:id, required

Scope

Write:Event

cURL Example

$ curl \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  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" }
          ]
        }
      }
    }
  }'

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",
      "recurrence": [],
      "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": {
      "author": {
        "data": {
          "id": "1234,12345",
          "type": "user"
        }
      },
      "label": {
        "data": {
          "id": "1234,1",
          "type": "label"
        }
      },
      "attendees": {
        "data": [
          { "id": "12345", "type": "user" },
          { "id": "56789", "type": "user" }
        ]
      }
    }
  }
}

Delete an event

Delete an event.

Endpoint

DELETE /calendars/:calendar_id/events/:event_id

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID
event_id string path Event ID

Scope

Write:Event

cURL Example

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

Response Example

HTTP/1.1 204 No Content

Create a comment

Creates comment to an event.

Endpoint

POST /calendars/:calendar_id/events/:event_id/activities

Parameters

Name Type In Description
accept string header application/vnd.timetree.v1+json recommended
authorization string header Obtained access token
calendar_id string path Calendar ID
event_id string path Event ID
data:attributes:content string body Required Comment text. Up to 1000 characters.

Scope

Write:Comment

cURL Example

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

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"
    }
  }
}