D-Bus API

Ambrosia lives at org.amberlinux.Ambrosia, object /org/amberlinux/Ambrosia, on the session bus. Each domain is an interface: .Applications, .Assistant, .Bookmarks, .Clipboard, .Notes, .Recent and .Terminal. All seven answer the same methods, apart from the two marked below, so a client written against one reads the next by changing the interface name.

Method	Does
Get(id)	one row; a missing id is an error, not an empty answer
List(limit)	the newest rows, in the domain’s own order
Query(filter)	rows matching a dictionary of filters, such as search
Add(entry)	stores a row and answers with its id
Update(id, fields)	changes only the fields given (not on Applications)
Delete(id)	removes one row
Clear(since)	removes unpinned rows from a time onwards (on Applications, only the pins made in Ambrosia)
Pin(id, pinned)	keeps a row at the top and out of any clearing (not on Applications)
Read(id, field)	a file descriptor holding one field in full
Changed	a signal after every change

Two extras sit outside the shared set: Applications.Launch(desktop_id) starts an application, and Terminal also sends EntryAdded(entry) for each new command.

A reply carries at most 250 rows, and a long value arrives as a preview with its true size beside it; Read fetches the whole of it. A filter key the domain does not have is refused rather than ignored, so a misspelt filter never comes back as every row.

From a shell

# The five newest clipboard entries
gdbus call --session --dest org.amberlinux.Ambrosia \
  --object-path /org/amberlinux/Ambrosia \
  --method org.amberlinux.Ambrosia.Clipboard.List 5

# Terminal commands that mention make
gdbus call --session --dest org.amberlinux.Ambrosia \
  --object-path /org/amberlinux/Ambrosia \
  --method org.amberlinux.Ambrosia.Terminal.Query "{'search': <'make'>}"

# Watch every change as it happens
gdbus monitor --session --dest org.amberlinux.Ambrosia

The full contract, with every key and error, is docs/INTEGRATION.md in the Ambrosia repository.