# 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

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

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

## 2. Preview

```sh
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:

```json example=preview-request
{ "email": "you@example.com" }
```

Response:

```json example=preview-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:

```sh
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:

```json example=execute-request
{ "preview_id": "<from preview>", "confirmation": true, "confirmation_text": "I confirm that Paintaire may use these details for the selected action." }
```

Response:

```json example=execute-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](https://paintaire.com/developers/agent-api) for every action, status code and error.

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