LumaLedger
Sign inGet started
Developers
API reference

Tags

get/v1/tags

List tags

tags.listread tokenidempotent

The ledger's tags, with how many transactions carry each.

Parameters

limit
integer · query
Page size, 1–200.
cursor
string | null · query
The next_cursor of the previous page.
X-Organization-Id
string | null · header

Returns 200 · TagList

data
array of Tag · required
has_more
boolean · required
next_cursor
string | null · required
Example
curl -X GET "https://api.lumaledger.app/v1/tags" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"
post/v1/tags

Create a tag

tags.createwrite tokenidempotent

Create a tag. Names are unique ignoring case: asking for one that exists returns the existing tag (its color unchanged) instead of an error, so creating a tag by name is safe to repeat.

Parameters

Idempotency-Key
string | null · header
Any unique string (a UUID is ideal). A retry with the same key returns the first attempt's response instead of doing the work twice. Keys are kept for 24 hours.
X-Organization-Id
string | null · header

Body · TagCreate

color
string | null
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default.
name
string · required

Returns 201 · Tag

color
string | null · required
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default.
created_at
datetime · required
id
integer · required
The tag id. transactions.list filters by it as tag_id.
name
string · required
Unique in the ledger, ignoring case.
transaction_count
integer · required
Transactions carrying the tag.
Example
curl -X POST "https://api.lumaledger.app/v1/tags" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "…"
  }'
delete/v1/tags/{tag_id}

Delete a tag

tags.deletewrite tokendestructiveidempotent

Delete a tag and take it off every transaction. Rules that name it keep their row; the condition simply stops matching.

Parameters

tag_id
integer · path · required
X-Organization-Id
string | null · header

Returns 204 with no body.

Example
curl -X DELETE "https://api.lumaledger.app/v1/tags/{tag_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"
get/v1/tags/{tag_id}

Get a tag

tags.getread tokenidempotent

One tag by id.

Parameters

tag_id
integer · path · required
X-Organization-Id
string | null · header

Returns 200 · Tag

color
string | null · required
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default.
created_at
datetime · required
id
integer · required
The tag id. transactions.list filters by it as tag_id.
name
string · required
Unique in the ledger, ignoring case.
transaction_count
integer · required
Transactions carrying the tag.
Example
curl -X GET "https://api.lumaledger.app/v1/tags/{tag_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"
patch/v1/tags/{tag_id}

Rename or recolor a tag

tags.updatewrite tokenidempotent

Rename or recolor a tag. Only the fields sent change. Renaming to a name another tag has is a 409. Transactions and rules that use the tag keep it: they refer to its id, not its name.

Parameters

tag_id
integer · path · required
X-Organization-Id
string | null · header

Body · TagUpdate

color
string | null
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default. Null clears it.
name
string | null

Returns 200 · Tag

color
string | null · required
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default.
created_at
datetime · required
id
integer · required
The tag id. transactions.list filters by it as tag_id.
name
string · required
Unique in the ledger, ignoring case.
transaction_count
integer · required
Transactions carrying the tag.
Example
curl -X PATCH "https://api.lumaledger.app/v1/tags/{tag_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
put/v1/transactions/{transaction_id}/tags

Set a transaction's tags

transactions.set_tagswrite tokenidempotent

Replace the tags on a transaction with exactly tag_ids. Tags a rule applied are replaced too. Hand-written transactions cannot carry tags (a 422).

Parameters

transaction_id
integer · path · required
X-Organization-Id
string | null · header

Body · TransactionTagsInput

tag_ids
array of integer · required
Every tag the transaction should carry (see tags.list); an empty list removes them all.

Returns 200 · TransactionTags

tags
array of Tag · required
The tags the transaction carries now, in id order.
transaction_id
integer · required
Example
curl -X PUT "https://api.lumaledger.app/v1/transactions/{transaction_id}/tags" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": [
      1
    ]
  }'

Objects

Tag

Fields

color
string | null · required
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default.
created_at
datetime · required
id
integer · required
The tag id. transactions.list filters by it as tag_id.
name
string · required
Unique in the ledger, ignoring case.
transaction_count
integer · required
Transactions carrying the tag.

TagCreate

Fields

color
string | null
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default.
name
string · required

TagList

A page of tags, in id order.

Fields

data
array of Tag · required
has_more
boolean · required
next_cursor
string | null · required

TagUpdate

Only the fields sent change.

Fields

color
string | null
A palette key (amber, blue, gold, green, indigo, orange, purple, red, rose, sky, slate, teal), drawn in the app's theme. Null for the default. Null clears it.
name
string | null

TransactionTags

Fields

tags
array of Tag · required
The tags the transaction carries now, in id order.
transaction_id
integer · required

TransactionTagsInput

Fields

tag_ids
array of integer · required
Every tag the transaction should carry (see tags.list); an empty list removes them all.