API overview

Almost everything you can do in Nifty, you can do through its API, at /api/v1 on your server. The API uses JSON and needs a token.

Your first request

1. Make a token in Settings → API tokens (Authentication).

2. Keep your server's address and the token in two variables, as every example here does.

   export NIFTY_URL=https://notes.example.com
   export NIFTY_TOKEN=nw_…

3. Ask who you are.

   curl "$NIFTY_URL/api/v1/me" -H "Authorization: Bearer $NIFTY_TOKEN"

{
  "data": {
    "name": "Ada Lovelace",
    "username": "ada",
    "has_password": true,
    "two_factor": false,
    "password_sign_in": true,
    "csrf_token": null,
    "time_zone": "London",
    "time_zone_iana": "Europe/London",
    "today": "2026-10-10",
    "token": { "id": 1, "name": "My script", "created_at": "2026-10-10T08:36:06.920Z", "expires_at": null, "last_used_at": "2026-10-10T08:36:11.395Z" }
  }
}

Requests and responses

• Send bodies as JSON, with Content-Type: application/json. Anything else gets 415.
• One record comes back as { "data": { … } }, and a list comes back as { "data": [ … ], "meta": { … } } (Pagination).
• Times are ISO 8601 in UTC, such as 2026-10-10T08:36:06.920Z.
• IDs are 26-character strings that sort by when the record was made, such as 01m4jf4tmpdav4str03j3vz4sq.
• All errors have the same shape (Errors).
• Links in a response, such as a person's photo, use your server's address. On the desktop app, they use the name your request was sent to, such as localhost. Webhooks always use your server's address.

Find a server

GET /.well-known/nifty doesn't need a token. It confirms that an address is a Nifty server, and gives its version and API address (System).

{
  "app": "nifty",
  "version": "2026.10.1",
  "min_shell_version": "0.0.0",
  "api_versions": [{ "version": "v1", "base_url": "https://notes.example.com/api/v1" }]
}

How paths work

• Each kind of record has its own list, such as /tasks. You create a record by sending POST to its list, with the ID of anything it belongs to in the body. The record itself is at /tasks/{id}.
• You change a record with PATCH, which changes only the fields you send.
• Something you switch on or off, such as a pin, has its own path. PUT switches it on and DELETE switches it off, as in PUT /notes/{id}/pin.
• A one-off action is a POST to a verb, such as POST /notes/{id}/restore.

Versions

Every API response has an X-Nifty-Version header with the server's version, so your app can tell when the server has been updated. Within v1, Nifty only adds things, such as new endpoints, fields and values. A change that would break your code gets a new version, /api/v2, beside the old one.

To keep your code working as Nifty grows, ignore fields you don't know. Treat a value you don't recognise as an unknown kind rather than an error. This applies to fields with a fixed set of values, error codes, webhook events and the types in the deletions list (Keeping a copy in sync).

Anything added in a beta release can still change before that version's stable release. The AI endpoints, document analysis and the Unsplash search are in beta. The reference marks each one, and they can change in any release.

The reference

The reference describes every endpoint, with one page per area, from Account to System. Schemas describes the shapes they share. The endpoints for your password, username, authenticators and API tokens aren't listed, because only Nifty itself can use them.

Keep a copy

To mirror your data elsewhere, see Keeping a copy in sync. To retry a create safely, see Idempotency.