for iPhone, Android, and web Sign in options

Avocado API

a part of Guacamole, our development tool set.

Documentation showing how to build apps and services for couples using Avocado.

Getting started

In order to issue requests against the Avocado API, you will first need to email us at developers@avocado.io to obtain a developer token. (Read more)

Once we issue you a token, you can do just about anything our native apps can do using the same API that powers our Web client, our Android client, and our iOS client.

Please read our terms and conditions of use carefully before using this API.

Thanks for your interest in Avocado!

Who's using the API?

Lots of people have requested keys and are busy making things. If you make something that's published publicly, we'll highlight it here.

  • Cilantro Released mid-Sept 2012. A Chrome extension for Avocado that allows you to quickly post (and share links) with your boo without having to open a new tab or leave the site you're visiting. For more info, see Mihai's blog post about it.

Table of contents

  1. Throttle Limits — The limits on API calls per Developer per day.
  2. Signing your requestsRequired. Requests without a developer signature will be rejected.
  3. Authentication — Logging in and developer identification.
    1. Login
    2. Logout
  4. Couples and Users — User and couple format, relationship management.
    1. User model — JSON representation of a user
    2. Couple model — JSON representation of a couple
    3. Listing users
    4. Fetching a single user
    5. Fetching the current couple
  5. Activity models — Enumeration of the types of JSON activities you’ll find in the mixed list of activities.
    1. Base activity model — Common attributes of all activities
    2. Message activity
    3. Kiss activity
    4. Hug activity
    5. List activity
    6. Photo activity
    7. Media activity
    8. Activity activity
    9. Couple activity
    10. User activity
  6. Accessing activities — Mixed activity list containing messages and updates about user activity in the system.
    1. Listing activities
    2. Deleting activities
  7. Messages, hugs and kisses — Easy peasy activities.
    1. Sending text-only messages
    2. Sending kisses
    3. Sending hugs
  8. Lists — Ordered, textual lists.
    1. List model — JSON representation of a list
    2. List item model — JSON representation of a list item
    3. UI note — List item ordering
    4. Creating a list
    5. Listing of lists — “LoLs!”
    6. Get a single list
    7. Deleting a list
    8. Renaming a list
    9. Creating a list item
    10. Editing a list item
    11. Deleting a list item
  9. Calendar models — Simple events in time.
    1. Event — JSON representation of a single event
    2. Reminder — JSON representation of an event reminder
    3. Constants — Available recurrence types and influence
  10. Accessing the calendar — Creating, editing and listing events.
    1. Listing events
    2. Creating events
    3. Editing events
    4. Deleting events
    5. Creating reminders
    6. Editing reminders
    7. Deleting reminders
    8. Changing recurring events
  11. Media — Photos in the system.
    1. Media model — JSON representation of a media item
    2. Uploading photos
    3. Listing photos
    4. Deleting photos
  12. Recipe — The world's best guacamole recipe.
    1. Two near-ripe avocados, lightly smooshed
    2. Juice from one lime
    3. A dash of kosher salt
    4. Ground cumin & cayenne pepper to taste (optional)
    5. Freshly ground pepper to taste
    6. Nothing else
    We will guac your world.

Throttle Limits

Avocado API keys are throttled by default to ensure the Avocado servers remain healthy and to help you find bugs around accidentally making too many requests to Avocado.

The current API call limit per day is 10,000 per API key and the counter resets at midnight PST.

If 10,000 API calls per day is not enough for what you're building, feel free to reach out to us at developers@avocado.io.

Signing your requests

Requests to the Avocado API must include a developer signature or they will be rejected.

To create a developer signature, you must obtain a developer ID and secret key provided by Avocado’s Guacamole Engineers. In order to obtain these, please email developers@avocado.io and let us know what you’d like to build.

Have a developer key and ID? Here's the quickest way to get started: Download this Avocado API test shell script and execute it against your Avocado account by running...

./avocado_sign_test.sh

We also have some starter scripts in several languages with examples that can help you get started by showing how to sign your requests once you have a developer ID and key:

This scripts walk through signing a single request. To sign all of your requests, you'll have to do what the scripts do, which is...

  1. Store the cookie value returned by /api/authentication/login. The cookie will be named "user_email".
  2. Concatenate the cookie value with your developer key and create a sha256 hash of the result.
    Example concatenation: iamalongcookievalueIAmTheDeveloperKey
    becomes: crazylongweirdlookinghashedstring
  3. Combine the hex digest of the hashed result with your developer ID, separated by a colon, to create a token:
    14:3bf680400aec3bfd01beb0c74f946f5536c355662d8c83239b2934a92778391f
  4. Provide this token to each API call either by setting it as the X-AvoSig request header, or by including it as a GET parameter ?avosig= along with each request.

Authentication

Login

POST /api/authentication/login

Form-encoded POST parameters:

  • email — The user’s email address.
  • password — The user’s password.

Responses:

  • 200 — Success, expect Set-Cookie header.
  • 400 — Bad username or password.

Logout

GET /api/authentication/logout

Response:

  • 200 — Success, expect Set-Cookie header.

Couples and Users

User model

This is the JSON representation of a user returned by a variety of endpoints, namely /api/user, and also present inside Couple objects.

The user model contains a variety of useful information:

{
  "id": "1u1u1u1u1u1",
  "firstName": "David",
  "lastName": "",
  "birthday": 476323200000,
  "email": "getting-to-know@avocado.io",
  "lastReadTime": 1370557372000,
  "currentCoupleId": "1c1c1c1c1c1",
  "avatarUrl": "https://avocado.s3.amazonaws.com/path-to-avatar.png",
  "avatarImageUrls": {
    "small": "https://avocado.s3.amazonaws.com/path-to-avatar.png",
    "medium": "https://avocado.s3.amazonaws.com/path-to-avatar.png"
  },
  "verified": true
}

Properties not listed here might not yet be well-supported by our API, so please tread lightly.

Attributes:

  • verified — Whether the user has verified his or her e-mail address yet.
  • avatarUrl — Path to an image to use as the user’s avatar.
  • avatarImageUrls — An object containing available sizes for a user's current avatar image.
  • currentCoupleId — The user’s current couple ID, which might be different from the couple id if we’re examining the other user in the current couple (and the other user has left the couple).
  • birthday — The user’s birthday, expressed as a unix timestamp in milliseconds. (Example: 476323200000 is 02-04-1985 00:00:00 UTC.) Or null if not set.
  • lastReadTime — The time of the last activity the user has read, expressed as a unix timestamp in milliseconds.

Couple model

This is the JSON representation of a couple returned by a variety of endpoints, namely /api/couple.

The couple object is just two User objects, along with an ID:

{
  "id": "1c1c1c1c1c1",
  "currentUser": {
    "id": "1u1u1u1u1u1",
    "firstName": "David",
    ...
  },
  "otherUser": {
    "id": "2u2u2u2u2u2",
    "firstName": "Diane",
    ...
  }
}

Listing current users

GET /api/user authenticated

Responses:

  • 200JSON The list of User objects in the current authenticated couple, starting with the current authenticated user. The second item in the list is null if the user is not in a couple.
    [{
      "id": "1u1u1u1u1u1",
      "firstName": "David",
        ...
    }, {
      "id": "2u2u2u2u2u2",
      "firstName": "Diane",
      ...
    }]

Fetching a single user

GET /api/user/1u1u1u1u1u1 authenticated

Responses:

  • 200JSON The User with the ID given in the path. If this user does not exist or is not in your couple, the API will return a 404.
  • 404 — User not found or inaccessible to you.

Fetching the current couple

GET /api/couple authenticated

Responses:

  • 200JSON The current Couple object, containing both users.

Activity models

Base activity model

This is the JSON representation of an activity in the couple’s shared timeline. These objects are returned by activity-related endpoints, namely /api/activities, but also e.g. when sending a message.

There are many different activities, each with a different type, which contain various data depending on the variety of activity.

Base activity

{
  "id": "1a1a1a1a1a1",
  "userId": "1u1u1u1u1u1",
  "timeCreated": 1342827430000,
  "type": ...,
  "action": ...,
  "data": {}
}

Properties not listed here might not yet be well-supported by our API, so please tread lightly.

Attributes available on all activities:

  • id — A unique activity ID.
  • userId — The user ID who performed the action described by the activity.
  • timeCreated — The unix timestamp in milliseconds.
  • type — One of: message, list, photo, media, user, couple, activity.
  • action — One of: null, add, edit, delete.
  • data — An Object containing action-specific data, described below.

Message activity

{
  ...
  "type": "message",
  "action": null,
  "data": {
    "text": "Hello, world!"
  }
}

Attributes available in `data`

  • text — The text of the message.

Kiss activity

{
  ...
  "type": "kiss",
  "action": null,
  "data": {
    "kisses": [{
      "x": 0.2,
      "y": 0.4,
      "rotation": -0.2
    }, {
      "x": 0.6,
      "y": 0.5,
      "rotation": 0.4
    }],
    "imageUrls": {
      "small": "https://avocado.s3.amazonaws.com/path/to/image.jpeg"
      "medium": "https://avocado.s3.amazonaws.com/path/to/image.jpeg"
    }
  }
}

Attributes available in `data`

  • kisses — A list of kisses to be placed on the image for this "kiss". Each Object in this array will specify an x, y and rotation (in radians) to represent where a kiss should be placed and how it should be rotated. (For more discussion about these coordinates, see Sending kisses.)
  • imageUrls — An Object containing available image sizes for the target image of this kiss. (If no image was provided when the kiss was created, these URLs will be the same as the target user's user.avatarImageUrls, because they are the user's current avatar.)

Hug activity

{
  ...
  "type": "hug",
  "action": null,
  "data": { }
}

Attributes available in `data`

  • None (This one's easy.)

List activity

{
  ...
  "type": "list",
  "action": "add",
  "data": {
    "id": "1l1l1l1l1l1"
    "name": "Groceries"
  }
}

Attributes available in `data`

  • id — The ID of the list that was added, edited, or deleted.
  • name — The name of the list.

Photo activity

Photo activities appear when photos are uploaded to the media gallery. There is no delete action, see media activities for that.

{
  ...
  "type": "photo",
  "action": "add",
  "data": {
    "id": "1m1m1m1m1m1",
    "caption": "A walk in the park",
    "url": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
    "imageUrls": {
      "tiny": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
      "small": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
      "medium": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
      "large": "https://avocado.s3.amazonaws.com/path/to/image.jpeg"
    },
    "info": {
      "width": 640,
      "height": 480,
      "aspectRatio": 1.3333333333333333,
      "format": "JPEG",
      "size": 83043
    }
  }
}

Attributes available in `data`

  • id — The ID of the media that was added.
  • caption — The caption string.
  • url — The URL to the full-size photo.
  • imageUrls — The list of available image sizes and their URLs.
  • info — Information about the image, including height and width in pixels along with the aspectRatio (which is width / height). size is in bytes.

Media activity

Media activities differ from photo activities in that they only appear when photos are deleted.

(Two activity types exist because we may eventually split media into multiple types, e.g. video, which would still create a media deleted activity upon deletion.)

{
  ...
  "type": "media",
  "action": "delete",
  "data": {
    "id": "1m1m1m1m1m1",
  }
}

Attributes available in `data`

  • id — The ID of the media that was deleted.

Activity activity

Yo dawg, I herd you like activities. Activity activities are activities generated by actions taken on other activities, namely when an activity is deleted.

This can be used by a client to update the main activities list as the other user deletes activities in the stream of activities. Activity acti— you get the point.

{
  ...
  "type": "activity",
  "action": "delete",
  "data": {
    "id": "1a1a1a1a1a1",
  }
}

Attributes available in `data`

  • id — The ID of the activity that was deleted.

Couple activity

Activity for couple-related events, namely when the couple is created. Only type add exists currently, and it should be the first activity in the timeline.

{
  ...
  "type": "couple",
  "action": "add",
  "data": {}
}

User activity

Activity for user-related events, namely when a user accepts an invitation (type add), edits his or her profile (type edit), or leaves the couple (type delete).

{
  ...
  "type": "user",
  "action": "edit",
  "data": {
    "attribute": "avatar"
  }
}

Attributes available in `data`

  • attribute — For edit activities, the attribute that was edited.

Accessing activities

Listing recent activities

GET /api/activities authenticated

Returns the most-recent 100 activities, unless ?before= or ?after= is supplied, in which case the 100 activities before or after the timestamp are returned.

NOTE: You cannot supply both before and after in the same request, this will result in a 400.

Optional GET parameters:

  • after — Unix timestamp in milliseconds.
  • before — Unix timestamp in milliseconds.

Responses:

  • 200JSON An Array containing up to 100 Activity objects from the activity stream.

Deleting activities

POST /api/activities/1a1a1a1a1a1/delete authenticated

Responses:

  • 200 — The activity was deleted.
  • 404 — The activity with the given ID was not found.

Messages

Send a message

POST /api/conversation authenticated

Form-encoded POST parameters:

  • message — The text of the message.

Responses:

  • 200JSON The Message Activity object that will result from the message that was just created.
  • 400 — Empty or otherwise bad-news message.

Sending kisses

POST /api/conversation/kiss authenticated

Form-encoded POST parameters:

  • x — The x position of a kiss, expressed as a percent between [0.0, 1.0].
  • y — The y position of a kiss, expressed as a percent between [0.0, 1.0].
  • rotation — The rotation of a kiss, in radians, between [-π, π].
  • media — Optional multipart image body to use (instead of the other user's current avatar).

NOTE: x and y coordinates are percentages based on a crop-to-fill square (aspect-ratio maintained) version of either the other user's current avatar, or the POSTed media.

You can include multiple kisses by including multiple x, y and rotation values in the form-encoded POST body, as long as the number of all supplied options is the same and they are in the same order.

For example:
  x=0.6&y=0.2&rotation=0.5&x=0.2&y=0.3&rotation=0.7
This represents two kisses, the first at (0.6, 0.2) and the second at (0.2, 0.3).

Responses:

  • 200JSON The Kiss Activity object that will result from the kiss that was posted.
  • 400 — Invalid kiss coordinates (out of range), non-matching number of x, y, rotation, etc.

Sending hugs

POST /api/conversation/hug authenticated

Form-encoded POST parameters:

  • None (This one's easy.)

Responses:

  • 200JSON The Hug Activity object that will result from the hug that was just posted.

Lists

List model

Lists are entities with a set of ordered items.

{
  "id": "1l1l1l1l1l1",
  "name": "Groceries",
  "timeCreated": 1339624935000,
  "timeUpdated": 1340741159000,
  "items": [
    ...
  ]
}

Attributes

  • name — The name of the list.
  • timeCreated, timeUpdated — Unix timestamps in milliseconds.
  • items — An ordered Array of List Item objects.

List item model

List items started out pretty simple, but we added some properties over time, namely "important", "userId", "updateTime" and image-related properties.

{
  "id": "3b26580f66",
  "text": "List item text",
  "complete": false,
  "important": false,
  "userId": "1u1u1u1u1u1",
  "updateTime": 1347582410818,
  "imageUrls": {
    "tiny": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
    "small": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
    "medium": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
    "large": "https://avocado.s3.amazonaws.com/path/to/image.jpeg"
  },
  "imageInfo": {
    "width": 1224,
    "height": 1632,
    "aspectRatio": 0.75,
    "format": "JPEG",
    "size": 791279
  }
}

Attributes

  • id — A unique-per-list ID.
  • text — The body of the list item.
  • complete — A boolean. Whether the item has been completed.
  • important — Optional - A boolean. Whether the item is starred / marked as important. (This is not present if the item is not important.)
  • userId — Optional - The ID of the user who last updated this list item. (This is not present for list items created before we started storing this information.)
  • updateTime — Optional - The timestamp when the list item was last updated. (This is not present for list items created befor we started storing this information.)
  • imageUrls — Optional - An Object containing the available image sizes along with their URLs, iff the list item has an image attachment.
  • imageInfo — Optional - An Object containing information (width, height, aspectRatio, format) about the image if the list item has one.

UI note — List item ordering

In all of Avocado's standard clients, we attempt to maintain list items in a certain order, grouped by their current state:

  1. Starred
  2. Un-starred, un-completed
  3. Completed

So, if a user completes an item in a list, you should also attempt to maintain this order by calculating and providing the appropriate index, placing the item at the top of the group of completed items.

Similarly, if a user stars an item, it should be moved to position 0 in the list. (Finally, if a user un-completes a starred item, it should be moved to the end of the group of starred items — a fun edge case.)

(This is not performed automatically because we didn't think it would be cool for the backend API to be moving items around willy-nilly — this might be changed in the future.)

Create a list

POST /api/lists authenticated

Form-encoded POST parameters:

  • name — The name of the list.

Responses:

  • 200JSON The newly formed List object.
  • 400 — List name not provided.

Lists of lists (LoLs)

GET /api/lists authenticated

Responses:

  • 200JSON An Array of your couple’s List objects.
    [{
      "id": "1l1l1l1l1l1",
      "name": "Groceries",
      ...
    }]

Get a single list

GET /api/lists/1l1l1l1l1l1 authenticated

Responses:

  • 200JSON The specified List.
  • 404 — The list was not found.

Delete a list

POST /api/lists/1l1l1l1l1l1/delete authenticated

Responses:

  • 200 — The list was deleted.
  • 404 — The list was not found.

Rename a list

POST /api/lists/1l1l1l1l1l1 authenticated

Form-encoded POST parameters:

  • name — The new name for the list.

Responses:

  • 200JSON — The new List object, having been renamed, in its entirety.
  • 400 — The new list name was not supplied.
  • 404 — The list was not found.

Create a list item

POST /api/lists/1l1l1l1l1l1 authenticated

Form-encoded POST parameters:

  • text — The new list item.
  • index — Optional - The position at which to insert new list item. (See also: List item ordering)
  • media — Optional - The multipart image body to upload for this list item.

Responses:

  • 200JSON The new List Item object.
  • 400 — The new list item was not supplied, the index was out of range, the media was malformed, etc.
  • 404 — The list was not found.

Edit a list item

POST /api/lists/1l1l1l1l1l1/1li1li1li authenticated

Form-encoded POST parameters:

  • text — The new list item text.
  • complete1 or 0.
  • important1 or 0.
  • index — The index to where the item should be moved. (See also: List item ordering)
  • media — The multipart image body to upload for this list item.
  • delete_media — If present (and non-zero), the existing media for a list item will be removed.

Responses:

  • 200JSON The new List object, in its entirety, after the changes were applied. (This returns the full list since order might have changed, etc.)
  • 400 — The index was out of bounds, the provided image was malformed, or no edits were specified.
  • 404 — The list or list item was not found.

Delete a list item

POST /api/lists/1l1l1l1l1l1/1li1li1li/delete authenticated

Responses:

  • 200JSON The new List object, in its entirety, with the item deleted.
  • 404 — The list or list item was not found.

Calendar model

Event

Calendar events in Avocado are basically just a start and end time along with some metadata.

{
  "id": "1e1e1e1e1e1",
  "userId": "1u1u1u1u1u1",
  "startTime": 1354640400000,
  "endTime": 1354644000000,
  "title": "A daily repeating event",
  "description": "A string (or null)",
  "location": "A string (or null)",
  "attending": [
    "1u1u1u1u1u1",
    "2u2u2u2u2u2",
  ],
  "reminders": [ ... ],
  "recurrenceType": "daily",
  "timeCreated": 1342826033083,
  "timeUpdated": 1342826033083
}

Attributes

  • id — The ID of the event. NOTE: Instances of a recurring event have special IDs, namely they share a common “series” ID. This is the first 11 characters of the ID, which for recurring events will be something like 1e1e1e1e1e1-n where n is an encoded offset from the starting event.
  • userId — The ID of the user who created the event.
  • startTime — When the event starts, unix timestamp in milliseconds.
  • endTime — When the event ends, unix timestamp in milliseconds.
  • title — The title of the event. (required non-null)
  • location, description — Optional strings of metadata. description is referred to as “notes” throughout the Avocado UI.
  • attending — An array of user IDs of users attending this event.
  • reminders — An array of Reminder objects for this event.
  • recurrenceType — The RecurrenceType for this event, or null if it does not repeat.
  • timeCreated, timeCreated — Unix timestamps in milliseconds.

Reminder

Calendar reminders represent notifications sent before an event starts.

{
  "id": "1r1r1r1r",
  "userId": "1u1u1u1u1u1",
  "type": "push",
  "interval": 600000
}

Attributes

  • id — The ID of the reminder.
  • userId — The ID of the user to remind.
  • type — The ReminderType for this reminder.
  • interval — The time (in milliseconds) before the event when the reminder should be sent.

Constants

RecurrenceType

  • daily — Repeats every day at the same time.
  • weekdays — Repeats every weekday.
  • weekly — Repeats every week.
  • monthly — Repeats every month. NOTE: Events set on days like the 30th or 31st will only recur in months that have those dates. (A monthly recurring event on the 30th will not appear at all in February, for example.)
  • yearly — Repeats every year.

RecurrenceInfluence

  • none — Only change the given event. (default)
  • all_future — Change all events in this series that haven’t happened yet (startTime >= now).
  • forward — Change this event and all events that follow forever.

ReminderType

  • push — Send a push notification to the user’s phone. (default)

Accessing the calendar

Listing events

Load a window of time (eg. a day, a week), listing all the events either starting, ending, or ongoing during it.

GET /api/calendar authenticated

Optional GET parameters:

  • start — An optional start time (in milliseconds). If not provided, now is used. NOTE: At launch time, we don’t support looking more than 2 years into the future. (This limit might go away in the future.)
  • days — The number of days starting from start to load. Defaults to 7 days. Maximum is 120 days.
  • series — An event ID from any event in a recurring series. This will limit the results to just the events from that series; handy for partial refreshes when you’ve changed a recurring event (with influence on future events).

Responses:

  • 200JSON An array of Event objects.
  • 400 — Start time too far in the future, invalid number of days, etc.

Creating events

POST /api/calendar authenticated

POST parameters:

  • start — Start time of the event; unix timestamp in milliseconds.
  • end — End time of the event; unix timestamp in milliseconds.
  • title — Title of the event (eg. "Dinner with John & Sally").
  • location — Optional location string.
  • description — Optional description string.
  • attending — Optional user ID (or IDs) of users attending this event. Multiple IDs may be included in the POST body by including the parameter multiple times, eg. ...&attending=1u1u1u1u1u1&attending=2u2u2u2u2u2&....
  • repeat — An optional RecurrenceType, which creates a repeating event right off the bat. Additional restrictions apply: timezone is required when providing repeat. Also, recurring events may not be longer than their recurrence period (eg. 1 day for daily repeating events).
  • timezone — Named timezone, eg. America/Los_Angeles. Only required when specifying repeat. (This is required because recurrence may cross daylight savings boundaries, etc.)

Responses:

  • 200JSON The Event object that was created.
  • 400 — Invalid start or end times (end before start), missing title, invalid duration or timezone if repeat is specified, invalid attending, etc.

Editing events

POST /api/calendar/1e1e1e1e1e1 authenticated

POST parameters:

  • start — Start time of the event; unix timestamp in milliseconds.
  • end — End time of the event; unix timestamp in milliseconds.
  • title — Title of the event (eg. "Dinner with John & Sally").
  • location — Optional location string.
  • description — Optional description string.
  • attending — Optional user ID (or IDs) of users attending this event. Multiple IDs may be included in the POST body by including the parameter multiple times, eg. ...&attending=1u1u1u1u1u1&attending=2u2u2u2u2u2&....
  • apply_to_series — Optional RecurrenceInfluence iff this is a recurring event. See also: Changing recurring events.
  • repeat — An optional RecurrenceType, which upgrades a one-time event to a repeating event. Additional validation, including event duration and timezone, applies. repeat can only be specified when editing an event iff the event does not already repeat. See also: Changing recurring events.
  • timezone — Named timezone, eg. America/Los_Angeles. Only required when specifying repeat.

Responses:

  • 200JSON The Event object that was edited. (Note: This does not return the whole series of events if apply_to_series was specified; just the target event.)
  • 404 — Event not found.
  • 400 — Invalid start or end times (end before start), missing title, invalid duration or timezone if repeat is specified, invalid attending, etc.

Deleting events

POST /api/calendar/1e1e1e1e1e1/delete authenticated

POST parameters:

Responses:

  • 200 — OK if the event was deleted successfully.
  • 404 — Event not found.
  • 400 — Invalid apply_to_series.

Creating event reminders

POST /api/calendar/1e1e1e1e1e1/reminders authenticated

POST parameters:

  • interval — Milliseconds before the event starts when the notification should be sent. (Must be >= 0.)
  • type — The ReminderType for this reminder.
  • user_id — The ID of the user to notify.
  • apply_to_series — Optional RecurrenceInfluence iff this is a recurring event. See also: Changing recurring events.

Responses:

  • 200JSON The Event object that got a new reminder.
  • 404 — Event or reminder not found.
  • 400 — Invalid interval, user_id or type.

Editing event reminders

POST /api/calendar/1e1e1e1e1e1/reminders/1r1r1r1r authenticated

POST parameters:

Responses:

  • 200JSON The Event object whose reminder was edited.
  • 404 — Event or reminder not found.
  • 400 — Invalid interval or type.

Deleting event reminders

POST /api/calendar/1e1e1e1e1e1/reminders/1r1r1r1r/delete authenticated

POST parameters:

Responses:

  • 200 — OK if the reminder was deleted successfully.
  • 404 — Event or reminder not found.
  • 400 — Invalid apply_to_series.

Changing recurring events

Overview — IDs and offsets

Editing or deleting recurring events presents a special challenge. Every change can be applied to a one-off event, or many events in the series of events.

Repeating events from the same series share the same base ID (the first 11 characters are the same). For example:

First event in a series: 1e1e1e1e1e1
Second event in a series: 1e1e1e1e1e1-1
Third event in a series: 1e1e1e1e1e1-2
100th event in a series: 1e1e1e1e1e1-1A
500th event in a series: 1e1e1e1e1e1-7Q

These future repeating events are individually addressable in the API by calling the API with the appropriate ID in the path, eg.

GET /api/calendar/1e1e1e1e1e1-1A — Returns the 100th individual event in this series.

Recurrence influence

When editing or deleting individual events in these series, if no RecurrenceInfluence is specified, only the given event will be changed or removed. (The API defaults to none.)

However, if influence is specified, given as the apply_to_series parameter in the various endpoints, the change is applied to the series in the following ways:

RecurrenceInfluence: none

Only 1e1e1e1e1e1-4 is affected.

  • “Event foo” 1e1e1e1e1e1-2 yesterday
  • “Event foo” 1e1e1e1e1e1-3 today
  • “Event bar 1e1e1e1e1e1-4 tomorrow ↑ edit target ↑
  • “Event foo” 1e1e1e1e1e1-5 two days
    from now
  • “Event foo” 1e1e1e1e1e1-6 three days
    from now

RecurrenceInfluence: forward

Only 1e1e1e1e1e1-4 and the events following it are affected.

  • “Event foo” 1e1e1e1e1e1-2 yesterday
  • “Event foo” 1e1e1e1e1e1-3 today
  • “Event bar 1e1e1e1e1e1-4 tomorrow ↑ edit target ↑
  • “Event bar 1e1e1e1e1e1-5 two days
    from now
  • “Event bar 1e1e1e1e1e1-6 three days
    from now

RecurrenceInfluence: all_future

1e1e1e1e1e1-2 and events before it are not affected because they are in the past.

  • “Event foo” 1e1e1e1e1e1-2 yesterday
  • “Event bar 1e1e1e1e1e1-3 today
  • “Event bar 1e1e1e1e1e1-4 tomorrow ↑ edit target ↑
  • “Event bar 1e1e1e1e1e1-5 two days
    from now
  • “Event bar 1e1e1e1e1e1-6 three days
    from now

Media

Media model

Media objects currently represent photos, but will likely be expanded to other media types (like video) in the future.

Note that this is almost entirely the same as the Photo Activity model.

{
  "id": "1m1m1m1m1m1",
  "caption": "A walk in the park",
  "url": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
  "timeCreated": 1342826033083,
  "timeUpdated": 1342826033083,
  "filename": "image1.jpg",
  "imageUrls": {
    "tiny": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
    "small": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
    "medium": "https://avocado.s3.amazonaws.com/path/to/image.jpeg",
    "large": "https://avocado.s3.amazonaws.com/path/to/image.jpeg"
  },
  "info": {
    "width": 640,
    "height": 480,
    "aspectRatio": 1.3333333333333333,
    "format": "JPEG",
    "size": 83043
  }
}

Attributes

  • id — The ID of the media item.
  • caption — The caption string.
  • filename — The original filename, if it was provided.
  • timeCreated, timeCreated — Unix timestamps in milliseconds.
  • url — The URL to the full-size media (photo).
  • imageUrls — The list of available thumbnail sizes and their URLs.
  • info — Information about the image, including height and width in pixels along with the aspectRatio (which is width / height). size is in bytes.

Uploading photos

POST /api/media [multipart] authenticated

Multipart POST parameters:

  • caption — The caption text.
  • media — The file body itself.

Responses:

  • 200JSON The new Media object.

Listing photos

GET /api/media authenticated

Optional GET parameters:

  • after — Unix timestamp in milliseconds.
  • before — Unix timestamp in milliseconds.

Responses:

  • 200JSON Array of Media objects.

Deleting photos

POST /api/media/1m1m1m1m1m1/delete authenticated

Responses:

  • 200 — The item was deleted.
  • 404 — Could not find the item with the given ID.