Overview

• Current version
• Schema
  • Summary Representations
• HTTP verbs
• Client errors
  • Invalid JSON
  • All custom errors
• Authentication
  • OAuth 2 Token (sent in a header)
  • OAuth2 Key/Secret
• Pagination
• Rate limiting

This document describes how to use Monica's API. This document is heavily inspired by GitHub's and Stripe's API. Please use the API in a nice way and don't be a jerk.

Current version

By default, all requests to https://app.monicahq.com/api receive the v1 version of the API.

Schema

All API access is over HTTPS, and accessed from the https://app.monicahq.com/api URL. All data is sent and received as JSON.

If you do have a custom instance of Monica, replace the URL above with the URL of your instance. The endpoint will always be YOUR_URL/api.

Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Thu, 14 Sep 2017 02:24:19 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

All timestamps return in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Summary Representations

When you fetch a list of resources, for instance the list of reminders, you will always get a subset of a contact attached to it, giving you just enough information so you don't need to fetch the full information of the contact to do something with it.

HTTP verbs

Monica tries to use the appropriate HTTP verbs wherever it can. Note that the PATCH HTTP verb is not used right now.

Client errors

Invalid JSON

Sending an invalid JSON during a POST or a PUT will result in a error.

{
  "error": {
    "message": "Problems parsing JSON",
    "error_code": 37
  }
}

All custom errors

Authentication

There are several ways to authenticate to the API. All requests to the API require authentication.

OAuth 2 Token (sent in a header)

curl -H "Authorization: Bearer OAUTH-TOKEN" https://app.monicahq.com/api

OAuth2 Key/Secret

This is meant to be used in server to server scenarios. Never reveal your OAuth application's client secret to your users. To use this authentication method, you need to first register an application in your Monica's instance.

Pagination

Requests that return multiple items will be paginated to 10 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?limit parameter. Omitting the ?page parameter will return the first page.

curl 'https://app.monicahq.com/api/contacts?page=2&limit=100'

Rate limiting

The returned HTTP headers of any API request show your current rate limit status:

Date: Thu, 14 Sep 2017 02:24:19 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

If you exceed the rate limit, an 429 error response returns with a JSON:

X-RateLimit-Limit   60
X-RateLimit-Remaining   0
Retry-After 55

{
    "error": {
        "message": "Too many attempts, please slow down the request.",
        "error_code": 34
    }
}