Introduction

Note the API is currently in beta and is disabled by default. Breaking changes may occur as we finalise the functionality.
Contact us if you want to test the API and we'll turn it on for your account.

Schema

All API access is over HTTPS. All data is sent and received as JSON.

The endpoint is:

https://[account].minutebase.com/api/v1/...

Where [account] is your MinuteBase subdomain.

All timestamps are returned as epoch integers in seconds.

Authentication

All API requests require authentication using an API key which can be created by going to the API section of your MinuteBase profile.

You can pass your API key in either as a URL parameter, or using HTTP basic authentication with the key as the username (and anything as the password).

For example (using curl):

curl https://acme.minutebase.com/api/v1/people.json?token=123456abcdef

curl -u 123456abcdef:x https://acme.minutebase.com/api/v1/people.json

Status Codes

All responses return standard HTTP status codes

200 - OK

Everything went fine.

204 - No Content

Everything went fine and we don't need to send any content back.
Returned when deleting items where all you need to know is that it went ok.

301 - Moved Permanently

You'll get this back if you attempt to access the API over HTTP, we'll redirect you to the HTTPS version of the resource.

400 - Bad Request

Returned if you send invalid JSON

401 - Unauthorized

Returned if you don't provide an API key, or the one you used is invalid.

403 - Permission Denied

You tried to access something you're not permitted to see, such as a workspace that you're not a member of.

404 - Not Found

You tried to access something which doesn't exist.

409 - Conflict

Returned if you try and edit the minutes / agenda of a meeting at the same time as someone else.

420 - Over Rate Limit

This is not a standard HTTP response code, but is used by Twitter and a number of other APIs to indicate that you've gone over your rate limit.

We've not yet implemented rate limiting, but you should be aware of this for future versions of the API.

500 - Server Error

Something went wrong on our end. You should never receive this, but if you do we'll receive a notification and aim to get a fix out ASAP.

It may be a temporary issue, so feel free to wait a moment and try again.

HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

HEAD

Can be issued against any resource to get just the HTTP header info.

GET

Used for retrieving resources.

POST

Used for creating resources.

PUT

Used for updating resources or collections.

DELETE

Used for deleting resources.

Validation Errors

When trying to create/update records which are invalid, the returned JSON will include the validation errors so you can display them in your application and let the user fix them.

When invalid, the result will contain a hash of errors like the following:

{
    "id":"4dfb6209cf02a383cd0001b8",
    "user_id":null,
    "firstname":null,
    "surname":null,
    "email":null,
    "administrator":false,
    "company":null,
    "department":null,
    "job_title":null,
    "created_at":0,
    "errors":
    {
        "firstname":
        [
            "please enter a name"
        ],
        "surname":
        [
            "please enter a name"
        ]
    }
}

Pagination

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size from 10 to 100 with the ?per_page parameter.

Paginated results will be wrapped in an object containing information about the collection, the results themselves will always be found as an array named results.

{
    "current_page":1,
    "per_page":25,
    "total_entries":1563,
    "total_pages":63,
    "results": [ ... ]
}

Rate Limits

We're not currently rate limiting the API, but will be doing so shortly.

We'll send a number of headers back with each response outlining your current rate limit details.

X-RateLimit-Remaining

Number of requests remaining in the hour.

X-RateLimit-Limit

Number of requests the you've got access to per hour.

X-RateLimit-Reset

Timestamp for when the rate limit will be reset (usually at the top of the next hour)

JSON-P Callbacks

We don't currently support JSON-P as it would require the API key being used in client-side Javascript which would make it far too easy for someone to steal your key and access your data.

We may allow keyless access to the API in the future to access public information (such as meetings set as public).