Make something awesome.
Make something awesome.
Last update: 02 November 2017
Note: the API is in alpha mode at the moment. It’s not considered to be production ready and we will stabilize it over the next weeks.
By default, all requests to
All API access is over HTTPS, and accessed from the
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
All timestamps return in ISO 8601 format:
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.
Monica tries to use the appropriate HTTP verbs wherever it can. Note that the
PATCH HTTP verb is not used right now.
|GET||Used for retrieving resources.|
|POST||Used for creating resources.|
|PUT||Used for replacing resources or collections.|
|DELETE||Used for deleting resources.|
Sending an invalid JSON during a POST or a PUT will result in a error.
|30||The limit parameter is too big.||The maximum number for the limit parameter in a request is 100.|
|31||The resource has not been found.||Comes along with a 404 HTTP error code.|
|32||Error while trying to save the data.||Happens when the validation (during a
|33||Too many parameters.||Happens when we try to save the data from the JSON, but the object expected different parameters.|
|34||Too many attempts, please slow down the request.||You are limited to 60 API calls per minute.|
|35||This email address is already taken.||An email address should be unique in the account.|
|36||You can’t set a partner or a child to a partial contact.|
|37||Problems parsing JSON.||When doing a
There are several ways to authenticate to the API. All requests to the API require authentication.
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.
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
?page parameter will return the first page.
The returned HTTP headers of any API request show your current rate limit status:
|X-RateLimit-Limit||The maximum number of requests you’re permitted to make per hour.|
|X-RateLimit-Remaining||The number of requests remaining in the current rate limit window.|
If you exceed the rate limit, an
429 error response returns with a JSON: