Tags
The #tags in notes. Rename or merge them here.
List tags
GET/tags
Tags are created from notes, so there's no POST.
curl "$NIFTY_URL/api/v1/tags" \
-H "Authorization: Bearer $NIFTY_TOKEN"Query parameters
| Name | Description |
|---|---|
ordername | id | updated_at · optional | name sorts case-insensitively, like the web, with id as the tie-breaker. |
directionasc | desc · optional | asc (ascending) or desc (descending), for order. |
updated_sincedate-time · optional | Only records updated at or after this time (ISO 8601 with Z or a UTC offset), ordered by updated_at, id. |
cursorstring · optional | meta.next_cursor from the previous page. |
limitinteger · optional | Items per page, up to 100; a larger number is taken as 100. |
counttrue | false · optional | true adds meta.total_count: the size of the filtered set (with updated_since too), ignoring cursor and limit. Anything but true or false is a 400. |
Response
200 OK Errors: 400 401 429
{
"data": [
{
"id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
"name": "string",
"created_at": "2026-10-10T09:30:00Z",
"updated_at": "2026-10-10T09:30:00Z"
}
],
"meta": {
"next_cursor": "eyJrIjpbIjIwMjYtMTAtMDlUMDg6MzA6MDBaIl19",
"limit": 1,
"total_count": 1
}
}Get a tag
GET/tags/{id}
curl "$NIFTY_URL/api/v1/tags/01j9zq3k8m5x2v7c4n6b0t1r9e" \
-H "Authorization: Bearer $NIFTY_TOKEN"Path parameters
| Name | Description |
|---|---|
idULID | A record's ID. |
Response
200 OK Errors: 401 404 429
{
"data": {
"id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
"name": "string",
"created_at": "2026-10-10T09:30:00Z",
"updated_at": "2026-10-10T09:30:00Z"
}
}Rename a tag
PATCH/tags/{id}
Also PUT /tags/{id}, the same.
A name another tag has, ignoring case, is a 422 (name: "already exists"). To combine the two, merge
instead (POST /tags/{tag_id}/merge). Changing only the casing is fine.
curl -X PATCH "$NIFTY_URL/api/v1/tags/01j9zq3k8m5x2v7c4n6b0t1r9e" \
-H "Authorization: Bearer $NIFTY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"tag":{"name":"garden"}}'Path parameters
| Name | Description |
|---|---|
idULID | A record's ID. |
Request body
| Name | Description |
|---|---|
tagobject | |
tag.namestring · optional | Normalised: a leading # is dropped, runs of spaces or hyphens become one hyphen (Work trip → Work-trip), and leading hyphens and trailing hyphens and . , ! ? ; : are dropped (rust. → rust). Punctuation inside a name is kept (1:1s). No commas. |
Response
200 OK Errors: 400 401 403 404 415 422 429
{
"data": {
"id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
"name": "string",
"created_at": "2026-10-10T09:30:00Z",
"updated_at": "2026-10-10T09:30:00Z"
}
}Delete a tag
DELETE/tags/{id}
Permanent. Writes a tag deletion record. From M7 it also comes off every note.
curl -X DELETE "$NIFTY_URL/api/v1/tags/01j9zq3k8m5x2v7c4n6b0t1r9e" \
-H "Authorization: Bearer $NIFTY_TOKEN"Path parameters
| Name | Description |
|---|---|
idULID | A record's ID. |
Response
204 Deleted Errors: 401 403 404 429
Merge a tag into another
POST/tags/{tag_id}/merge
Notes with this tag get the into_id tag instead (from M7), then this tag is deleted: it appears in
GET /deletions as a tag. The surviving tag is unchanged and returned. A missing or unknown
into_id, or this tag's own id, is a 422 on into_id.
curl -X POST "$NIFTY_URL/api/v1/tags/01j9zq3k8m5x2v7c4n6b0t1r9e/merge" \
-H "Authorization: Bearer $NIFTY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"into_id":"01j9zq3m2a7d5f8g1h3j6k9m0n"}'Path parameters
| Name | Description |
|---|---|
tag_idULID | The tag to merge away. |
Headers
| Name | Description |
|---|---|
Idempotency-Keystring · optional | Makes a POST safe to retry for 24 hours. Needs a bearer token (400 under session auth). |
Request body
| Name | Description |
|---|---|
into_idULID | The tag to keep. |
Response
200 Merged. The surviving tag. Errors: 400 401 403 404 409 415 422 429
{
"data": {
"id": "01j9zq3k8m5x2v7c4n6b0t1r9e",
"name": "string",
"created_at": "2026-10-10T09:30:00Z",
"updated_at": "2026-10-10T09:30:00Z"
}
}