Unamused Connector · machine brief · no login required

Unamused connector brief

This page is written for an AI agent, not a human. If you are an agent creating a Custom Connector for Unamused, everything you need is below. Humans: the connector page explains the same thing in friendlier terms.

1. What Unamused is

Unamused is a free, open-source (MIT) service that hosts machine-usable action APIs for small businesses — bookings, orders, quote requests, contact forms — behind one connector. An agent connects to Unamused once, then can find any hosted business and act on a customer's behalf: search the business, inspect its actions, call them. It is an independent project, not affiliated with Meta.

2. Add it to Muse

In Muse, ask: "create a Custom Connector for Unamused" and point it at this page (https://unamused.app/connector/brief) or at the machine-readable files below. Muse reads API docs itself, test-calls every tool, and saves the integration. No Meta review or approval is required for Custom Connectors.

3. Endpoints

Every business also keeps its own portable API that works with any agent on any platform: https://unamused.app/a/<business_id>/mcp, https://unamused.app/a/<business_id>/openapi.json, https://unamused.app/a/<business_id>/actions/<action>.

4. Auth

Read endpoints need no key. There is no API-key scheme: the business_id (12 unguessable hex characters) is the capability identifier, and every mutating operation is gated by single-use tokens described below. Never ask a user to paste a secret into chat; there is nothing to paste.

5. Tool catalog (connector MCP)

Typical flow: search_businesses → get_business → call_action. Per-business MCP servers expose that business's own actions as tools instead.

6. Approval flow (server-enforced)

Actions that commit the business (bookings, orders) are approval-gated server-side — the gate cannot be skipped by the agent:

1. Call the action with its parameters. The server validates them and returns approval_required: true plus a single-use approval_token (valid 10 minutes). Nothing has executed.
2. Show the human the action and the exact parameters. Get a yes.
3. Call again with approval_token to execute.

The token binds the business, the action, and the exact approved parameters: reuse, expiry, a different business, or changed parameters are all rejected. The same two-step flow works on the REST endpoints and the MCP tools.

7. Payments

Unamused never touches payment credentials. When an agent needs to pay (e.g. completing an order), the agent's own wallet handles checkout — in Muse, that is Stripe Link with one-time virtual cards. Unamused only needs to hand the agent a priced order; do not build payment handling into the connector.

8. Webhooks (business side)

When an action executes through the webhook channel, Unamused POSTs JSON {action, params, idempotency_key, …} to the business's URL with:

• X-Unamused-Signature: t=<unix-ts>,v1=<hex> — HMAC-SHA256 of <ts>.<raw-body> keyed by the business's webhook secret
• X-Unamused-Timestamp and X-Unamused-Idempotency-Key (also inside the JSON body)

Receivers should verify the signature and reject timestamps outside a ±5 minute window to stop replays.

9. Status polling

Every executed action is recorded with a stable log_id (returned by call_action). Poll these — never re-run an action to check on it:

• GET https://unamused.app/connector/businesses/<business_id>/status — current status, per-action last-execution info
• GET https://unamused.app/connector/action-log/<log_id> — one executed action's status (delivered / handoff / error)
• GET https://unamused.app/connector/changes?since=<ISO-8601>[&business_id=…] — delta poll: new businesses, executed actions, deletions

Check no more often than every 5 minutes (300 seconds) and prefer /changes?since= delta polls over full reads. Polling burns the user's usage meter; these endpoints are deliberately lightweight.

10. Deletion ("forget me")

When a user asks to delete a business's data — including "forget my business" or "forget me" inside Muse:

1. Call request_deletion (MCP) or POST https://unamused.app/connector/deletion/request with {"business_id": "…"}. It returns a single-use deletion_token (10 minutes) and exactly what will be deleted. Nothing is deleted by this call.
2. Show the owner what will be deleted. Get a clear yes.
3. Call confirm_deletion / POST https://unamused.app/connector/deletion/confirm with the token. This permanently deletes the business record, its action-log entries, and pending approval tokens, and returns a deletion receipt with a receipt_id — keep it as proof.

After deletion, the business's status endpoint reports status: "deleted" with the receipt. Deleted demo businesses re-seed on server restart (they are fictional placeholders).

11. Rate limits

• Reads (search, detail, status, changes, brief): 120/hour per IP — a 5-minute poll cadence never trips it.
• Action calls, MCP calls, deletion requests: 10/hour per IP.
• Free audits: 10/hour per IP.

12. Privacy summary

• Stored per business: name, URL, contact email (never shown publicly), action definitions, webhook secret, action-log entries (action, params, status, timestamps), deletion receipts.
• No user accounts, no passwords, no payment data. First-party server-side counters only (visits counted on Unamused's servers); no cookies, no JavaScript tracking, no third-party trackers.
• Meta does not review Custom Connectors — this page and the privacy posture it describes are the trust surface. Review them before connecting.
• Retention/deletion policy beyond the "forget me" flow above is not yet formalized; the deletion endpoints are the mechanism that exists today.

13. Machine-readable pointers

• OpenAPI: /connector/openapi.json
• Manifest: /connector/manifest.json
• MCP: https://unamused.app/connector/mcp
• Directory: /connector/businesses