The Folevi REST API

The REST API lets your own scripts, and tools like Zapier, n8n and Make, work with Folevi: search and read notes, create notes from Markdown, add to a note, and add, list and complete tasks. It answers in JSON at https://app.folevi.com/api/v1. The full description, for API explorers and code generators, is at /api/v1/openapi.json (OpenAPI 3.1).

Make a token

Open Settings → Connected apps and choose New token under Personal access tokens. Give it a name, choose what it may do and where (your Personal, and any workspaces you pick), and when it expires: in 30 days, 90 days, a year, or never. Copy the token when it’s shown. It starts with fvpat_ and appears only once: Folevi keeps just a fingerprint of it.

A token works as you, so it never reaches more than you can open, and only in the places you gave it. Treat it like a password: keep it in your tool’s secret settings, never in code you share. Revoke it in Settings and it stops working at once. You can have up to 20 tokens.

Send a request

Send the token in the Authorization header. Replace YOUR_TOKEN with yours.

curl https://app.folevi.com/api/v1/places \
  -H "Authorization: Bearer YOUR_TOKEN"

Search notes, or leave out q to list the most recently edited, a page at a time (pass nextCursor back as cursor):

curl "https://app.folevi.com/api/v1/notes?q=roadmap&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Read one note as Markdown, with its folder path, tags and link:

curl https://app.folevi.com/api/v1/notes/NOTE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Create a note (in your Inbox here), then add to it:

curl https://app.folevi.com/api/v1/notes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-meeting-notes" \
  -d '{"title": "Meeting notes", "markdown": "## Decisions\n\n- Ship on Friday", "inInbox": true}'

curl https://app.folevi.com/api/v1/notes/NOTE_ID/append \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "- [ ] Send the summary"}'

Add a task (to your Inbox page when no noteId is given), list what’s due, and check it off:

curl https://app.folevi.com/api/v1/tasks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Call the venue", "dueDate": "2026-10-20", "priority": "high"}'

curl "https://app.folevi.com/api/v1/tasks?status=open&due_before=2026-10-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X PATCH https://app.folevi.com/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'

Retries and history

Send an Idempotency-Key header (any unique string, a UUID is ideal) with a write. If the same request arrives again within 24 hours, Folevi answers as it did the first time instead of creating a second note or task, and adds the header Idempotent-Replayed: true. The same key with a different request is refused.

Before the API changes a note that already exists, Folevi saves a version of it, so anything can be undone from the note’s history. Changes made through the API show in Changes as a connected app’s.

Errors and limits

Errors always look like {"error": {"code": "…", "message": "…"}}, with the status that fits: 400 for a malformed request, 401 for a missing, revoked or expired token, 403 when the token lacks the scope (insufficient_scope) or the place, 404 for a note or task it can’t reach, 409 when a note changed while saving, 422 for a field that isn’t valid, and 429 when you’ve sent too many.

• Reads: up to 300 a minute per token. Searches: up to 120 a minute.
• Writes: up to 30 a minute and 500 a day per token.
• A 429 comes with Retry-After, the seconds to wait.
• A new note can hold up to 100,000 characters of Markdown, and an addition up to 20,000.

Browsers can call the API from any site: it uses only the token, never your Folevi sign-in, so a page can’t use your session. To hear about changes as they happen instead of asking, use webhooks.