Docklet Live Cards SDK

Build custom macOS desktop notifications with a single HTTP request. No SDK to install, no auth required.

Live Demo

Switch scenarios to see what your integration sends and what Docklet renders.

Example Sources

Each scenario updates both the rendered card and the payload body.

Mock feed is off. Start with node scripts/live_cards_mock_server.js

POST /live-activities/card/upsert Docklet: 9876 · Mock: 9877

GitHub active

PR #142 needs review

docklet-macos · feature/island-refactor

Requested 4m ago by @aramirez

Select an action to simulate callback behavior.

01. The Setup

Docklet runs a local server on your Mac. You don't need API keys or complicated auth. If Docklet is running, it's ready.

Base URL: http://127.0.0.1:43822/v1

02. Push a Card

Send a simple POST request to /cards/upsert to show something on the island.

curl -X POST http://127.0.0.1:43822/v1/cards/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "my-tool",
    "card": {
      "id": "hello-world",
      "kind": "status",
      "title": "Hello from Terminal!",
      "statusText": "It works!",
      "state": "active"
    }
  }'

03. Add Buttons

Want your card to do something? Add up to 3 actions. You can open URLs, copy text, or get a callback in your app.

"actions": [
  {
    "id": "open",
    "title": "Open Website",
    "style": "primary",
    "behavior": "openUrl",
    "url": "https://getdocklet.app"
  }
]

04. Profit.

That's it. You are now a Docklet Developer.

Full API Reference

Base URL

http://127.0.0.1:43822/v1

GET

/cards/health

Check if the Docklet server is running and see available capabilities.

POST

/cards/upsert

Create or update a card. ID is unique per source.

Parameter	Type	Description
sourceId	String	Unique identifier for your app/tool (e.g., "jira").
card	Object	The card data (title, status, etc.).

POST

/cards/delete

Remove a specific card from the island.

GET

/actions/events

Long-poll for user interaction events (button clicks).

The Card Model

Field	Type	Required
id	String	Yes
kind	"status" \| "delivery" \| "timer"	Yes
title	String	Yes
state	"active" \| "completed"	Yes
progress	Number (0.0 - 1.0)	No
actions	Array of Action	No

Action Behaviors

Buttons in your card can trigger different results. These are valid behavior values:

Behavior	Description
`callback`	Docklet creates an event your app can poll for via `/actions/events`.
`openUrl`	Instantly opens a `url` in the default browser.
`copyText`	Copies the specified `copyText` string to the system clipboard.
`dismiss`	Immediately closes/removes the card from the island.