HTTP API

HTTP API

The daemon serves a JSON API over the Unix socket. It is local-only by construction: the socket has 0600 permissions, so only your user can talk to it and nothing is exposed to the network.

All examples use curl with --unix-socket:

			curl --unix-socket /tmp/clipd.sock http://unix/api/health

Endpoints

Health

GET /api/health

Liveness check for the daemon.

			curl --unix-socket /tmp/clipd.sock http://unix/api/health

List history

GET /api/v1/history

Returns recent entries, newest first. Accepts a limit query parameter.

			curl --unix-socket /tmp/clipd.sock "http://unix/api/v1/history?limit=10"

Get an entry

GET /api/v1/history/{id} 
			curl --unix-socket /tmp/clipd.sock http://unix/api/v1/history/1

Delete an entry

DELETE /api/v1/history/{id} 
			curl --unix-socket /tmp/clipd.sock -X DELETE http://unix/api/v1/history/1

Clear history

DELETE /api/v1/history

Deletes all entries.

			curl --unix-socket /tmp/clipd.sock -X DELETE http://unix/api/v1/history

Warning

This clears the entire history in one call. There is no confirmation step at the API level.

Create an entry

POST /api/v1/entries

Adds an entry directly, without going through the system clipboard.

			curl --unix-socket /tmp/clipd.sock -X POST 
  -H "Content-Type: application/json" 
  -d '{"content": "hello from the API"}' 
  http://unix/api/v1/entries
GET /api/v1/search

Full-text search with the q query parameter.

			curl --unix-socket /tmp/clipd.sock "http://unix/api/v1/search?q=example"

Statistics

GET /api/v1/stats 
			curl --unix-socket /tmp/clipd.sock http://unix/api/v1/stats