Quickstart

Status: Live Updated: 2026-09-30 Verified against: ecosystem cecd4003

This walks the newsletter action end to end. You need a Paintaire-issued bearer credential with scopes lead:preview and lead:create; export it as $PAINTAIRE_TOKEN. Use a test address you control, because the final call really subscribes it.

1. Discover

curl https://paintaire.com/.well-known/paintaire-agent.json

The manifest lists each action with its required fields. Discovery is public.

2. Preview

curl -X POST https://paintaire.com/api/agent/actions/newsletter/preview \
  -H "Authorization: Bearer $PAINTAIRE_TOKEN" -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com" }'

Request body:

{ "email": "you@example.com" }

Response:

{ "ok": true, "preview_id": "<signed token>", "action": "newsletter", "fields": { "email": "you@example.com" }, "created_at": "2026-09-30T17:00:00.000Z", "expires_at": "2026-09-30T17:10:00.000Z", "confirmation_required": true, "confirmation_statement": "I confirm that Paintaire may use these details for the selected action.", "destination": "Paintaire" }

3. Confirm with the user

Show the user the fields, the destination and the confirmation_statement. Continue only if they agree.

4. Execute

Generate the key once and keep it, so a retry sends the same key:

KEY=$(uuidgen)
curl -X POST https://paintaire.com/api/agent/actions/newsletter/execute \
  -H "Authorization: Bearer $PAINTAIRE_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "preview_id": "<from step 2>", "confirmation": true, "confirmation_text": "I confirm that Paintaire may use these details for the selected action." }'

Request body:

{ "preview_id": "<from preview>", "confirmation": true, "confirmation_text": "I confirm that Paintaire may use these details for the selected action." }

Response:

{ "ok": true, "receipt": { "action_id": "0f8c2a6e-0000-4000-8000-000000000000", "action": "newsletter", "status": "submitted", "created_at": "2026-09-30T17:01:00.000Z", "consent_recorded_at": "2026-09-30T17:01:00.000Z", "confirmation_text": "I confirm that Paintaire may use these details for the selected action.", "result": { "ok": true } } }

Keep the receipt. Re-running the curl with the same $KEY (for example after a timeout) returns it again rather than submitting twice; a new key for the same preview gets 409 preview_already_used. See the Agent API for every action, status code and error.

Human page: https://paintaire.com/developers/quickstart