API overview

Almost everything you can do in Nifty, you can do through its API, at /api/v1 on your server. It speaks 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,
    "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": { … } }; a list as { "data": [ … ], "meta": { … } } (Pagination).
• Times are ISO 8601 in UTC: 2026-10-10T08:36:06.920Z.
• IDs are 26-character strings, sorting by when the record was made: 01m4jf4tmpdav4str03j3vz4sq.
• Errors share one shape (Errors).

Find a server

GET /.well-known/nifty needs no token. It confirms an address is a Nifty server, with 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" }]
}

Versions

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

The reference

Every endpoint, one page per area, from Account to System, with Schemas for the shapes they share. Endpoints for your password, username and API tokens aren't listed: 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.