Marvin has an API you can use to connect Marvin to your own scripts and tools. This section is the full API documentation. It used to live on GitHub and is now kept up to date here.
OpenAPI
You can use a tool like Swagger UI or Postman to view Marvin's OpenAPI spec.
Overview
Direct database access
The vast majority of your data lives in a cloudant database. You are free to consume and modify your data as you see fit, but keep in mind that you might break your Marvin or lose data. I recommend making a backup before you start as well as regular backups (perhaps using the Desktop app's auto backups).
See Direct database access in this section.
Marvin's API
Marvin also has its own API:
access/modify data that doesn't live in the cloudant database like time tracking, habits
potentially easier to use than the couchdb API
possible from javascript/bookmarklets due to CORS
See Marvin API endpoints in this section.
Webhooks
Webhooks are used to notify your service that something happened in Marvin. This might be useful for creating web integrations or for starting the disco light whenever you complete a project.
See Webhooks in this section.
Stability
Marvin's API and data formats are subject to change. Each API endpoint is marked with a rough estimate of how stable it is. I will try not to break things, but it's hard to predict future developments!
Credentials
Don't share your credentials as they will give others access to your data. The apiToken is safer to share since it allows limited read/write access to your data (whereas the fullAccessToken is able to do more, and the database credentials can read/write almost all your data). But still, only share it with those you trust not to abuse it as the creation of many tasks could cause your Marvin to run very slowly, or could cause your account to be restricted due to perceived abuse.
To access your couchdb database, use the syncServer, syncDatabase, syncUser, and syncPassword credentials found in the API settings (Features page → API). You can also find them here.
To access Marvin's growing API surface, use the apiToken or fullAccessToken found in the API settings (Features page → API). You can also find it here.
Rate limits
Please keep your API use within these limits:
No bursts faster than 1 request every 3 seconds.
No more than 1440 requests per day on average (about 1 per minute).
When creating items in bulk, no more than 1 item per second. Please don't keep creating items until your database is gigantic.
Every request counts, reads and writes alike, including /api/doc/update and /api/markDone. One request to the database's _changes feed counts as one request, however many documents it returns.
These limits are one shared budget across Marvin's public API and direct database access. There is no daily counter, so the daily limit is an average rather than something that resets at a fixed time.
If you send too many requests in a short time, the public API replies with HTTP 429 ("Too many AM API requests") and refuses further requests for about a minute. If you get a 429 from the API or from the database, wait and then continue more slowly. There is currently no way to see your usage.
The desktop app's local API server runs on your own computer, so these limits don't apply to it.
Your API access or account may be restricted if you abuse the API. Please contact support if you have further questions about rate limits or your API usage.