Developer Docs
Manage your plants, events, photos, and insights programmatically via the REST API, connect AI assistants via MCP, or use the CLI from your terminal.
REST API
CRUD endpoints for plants, events, photos, and insights. Bearer token auth, OpenAPI spec included.
MCP
Connect AI assistants like Claude Desktop, Cursor, or ChatGPT to your plant data via the Model Context Protocol.
CLI
Manage your plants from the terminal. Authentication, CRUD, AI tools, and data export in one command.
Authentication
All API and CLI requests require a Bearer token. Generate tokens from Settings → Developer tokens in the app. Tokens use the prefix tnd_mcp_ and are hashed server-side (SHA-256). They are shown once at creation — store them securely.
curl -H "Authorization: Bearer tnd_mcp_..." \
https://rootnotes.app/api/plantsScopes
Each token is issued with one or more scopes. By default, new tokens receive all scopes.
| Scope | Allows |
|---|---|
| plants:read | List and get plants, events, photos, locations |
| plants:write | Create, update, and delete plants and photos |
| events:write | Create, update, and delete events |
| insights:read | Access analytics and insights dashboard data |
Rate limits
Write operations (POST, PATCH, DELETE) are limited to 20 requests per minute per user. Read operations are not rate-limited. When you hit the limit, the API returns 429 Too Many Requests.
Error responses
All errors return JSON with an error field and an HTTP status code.
| Status | Meaning |
|---|---|
| 400 | Validation error |
| 401 | Missing or invalid token |
| 403 | Insufficient scopes or resource not owned |
| 404 | Resource not found |
| 429 | Rate limit exceeded |