API v1
v1
View as Markdown

Errors

PUT /api/v1/me

The API uses the ordinary HTTP status codes. 2xx means it worked, 4xx means the request was wrong, 5xx means this end was.

Every refusal answers JSON with a message saying what went wrong. A request that fails validation answers 422 and adds an errors object keyed by field name, naming every field at fault at once. The example on the right is one of those.

The API never answers 403. Something you can reach but may not change in its current state answers 422 with the reason, and something you cannot reach answers 404.

Status codes

Every code the API answers with, and what the body holds when it does.

Code When Body
200 OK The request worked. The record, or the page of records, that was asked for.
201 Created Something was created: a record, a token, a merge, or a checkout or portal session. What was created.
204 No Content The request worked and there is nothing to send back, after a deletion or a logout for example. None.
401 Unauthorized No token was sent, or the one sent has been revoked. Log in answers it too when the email and password do not match, or when the two-factor code is wrong. A message.
404 Not Found Nothing answers to that path. A record belonging to another account, one reached through a vault that does not hold it, and an id that is not well formed all answer the same way, so that nothing is disclosed about them. A message.
405 Method Not Allowed The path exists, but not with that method. A message.
409 Conflict Merging two contacts, when either of them changed after the preview was read: read the preview again and send its new fingerprint. Previewing or merging two contacts while an import writes into their vault: wait until the import has finished. Nothing is written either way. A message.
413 Content Too Large The request body is larger than this server accepts, which only an upload such as an avatar can reach. It is refused before validation runs. A message.
422 Unprocessable Content A field is missing or invalid, or the request cannot be carried out in the current state of the record, such as answering a reminder twice or cancelling a subscription that is already ending. A message, and an errors object listing every field at fault.
429 Too Many Requests The rate limit was reached. Retry-After says how many seconds to wait. A message.
500 Internal Server Error Something failed on this end rather than in the request. A message.
503 Service Unavailable The instance is down for maintenance. The status endpoint answers it when the database cannot be reached, and starting a checkout or a portal session answers it when Stripe did not answer. A message. The status endpoint answers a status of error instead.

Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in X-RateLimit-Remaining.

PUT
curl https://my.monicahq.com/api/v1/me \
-X PUT \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/me', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/me');
Response 422
{
"message": "The first name field is required.",
"errors": {
"first_name": [
"The first name field is required."
]
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.