Ketchup API Spec

The Ketchup API

The Ketchup API allows you to interact with Ketchup ( ) via a set of REST URLs that return data in JSON format. The API allows you to list, show, update and delete meetings, projects, agenda items and notes.

Please feedback any queries to


Authentication is via a token. You can access your token in "My Account"

Get your API key with:

curl -u

'single_access_token' is what you're looking for.

All subsequent requests should be of the form:

In all cases, 'shortcode_url' is the ID of the parent, so MEETING_ID would be the 'shortcode_url' of the parent meeting, ITEM_ID the 'shortcode_url' of the parent item.


Projects allow group meetings and listing only meetings from a particular project.

Create Projects

Create a new project simply by passing the project name as part of a meeting create or update, eg:

{'title':'My New Meeting', 'project_name':'A new or existing project'}

List Projects

GET /api/v1/projects.json

List Meetings in a project

GET /api/v1/projects/PROJECT_ID/meetings.json

Edit a project

PUT /api/v1/projects/PROJECT_ID.json


List Meetings

Note: By default, these methods return meeting data, notes and items for all meetings. For performance, you can pass 'lean=true' to any of the meeting list methods, to get just a list of meetings, rather than including notes and items.

GET /api/v1/meetings.json(?lean=true)
            "title":"[Gem] Discussing the Gem Intranet",
            "attendees":"Paul, Julie, Catherine, Emma",

You can also get all meetings in icalendar format:

GET /api/v1/meetings.ics

List upcoming meetings

GET /api/v1/meetings/upcoming.json

List previous meetings

GET /api/v1/meetings/previous.json

List todays meetings

GET /api/v1/meetings/todays.json

Show a Meeting

GET /api/v1/meetings/i6L3So.json

Create a Meeting

POST /api/v1/meetings.json
{'title':'My Meeting', 'location':'Dublin',
  'attendees':'Paul,Brian', 'date':'tomorrow'}

Update a Meeting

PUT /api/v1/meetings/MEETING_ID.json
{'title':'Your Meeting'}

Delete a Meeting

DELETE /api/v1/meetings/MEETING_ID.json


List Items

GET /api/v1/meetings/MEETING_ID/items.json

Create an Item

POST /api/v1/meetings/MEETING_ID/items.json
{'content':'Take this seriously'}

Update an Item

PUT /api/v1/items/ITEM_ID.json
{'content':'Take this very seriously'}

Sort Items

PUT /api/v1/meetings/MEETING_ID/sort_items.json

Delete an Item

DELETE /api/v1/items/ITEM_ID.json


List Notes

GET /api/v1/items/ITEM_ID/notes.json

Create a Note

POST /api/v1/items/ITEM_ID/notes.json

Update a Note

PUT /api/v1/notes/NOTE_ID.json
{'content':'not so notable'}

Sort Notes

PUT /api/v1/items/ITEM_ID/sort_notes.json

Delete a Note

DELETE /api/v1/notes/NOTE_ID.json

Parse a date-string

The DATESTRING should be URI-encoded



Register a new user

POST /api/v1/users.json
{'email':'', 'password':'spiffy', 'timezone':'Dublin'}

View User Details

GET /api/v1/profile.json

Update User Account

PUT /api/v1/profile.json