Agent API

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

API version 2026-09-01. Discovery is public and grants nothing. Execution needs a Paintaire-issued bearer credential with the scope for each step.

Discovery (public)

GET https://paintaire.com/.well-known/paintaire-agent.json — versioned manifest (also /api/agent/manifest)
GET https://paintaire.com/api/agent/content — resource index; ?resource=<id> returns one Markdown resource
GET https://paintaire.com/llms.txt and every page’s .md mirror

Actions

Action	Audience	Purpose	Required	Optional
`homeowner_quote`	homeowner	Request a quote from one vetted painting contractor.	`name`, `email`, `postal_code`	`phone`, `project_type`, `timeline`, `message`
`contractor_signup`	contractor	Request a Paintaire platform walkthrough.	`name`, `email`, `company`	`phone`, `company_size`, `message`
`contact`	either	Send a message to Paintaire.	`name`, `email`, `subject`, `message`	`phone`
`newsletter`	either	Subscribe to Paintaire updates.	`email`	—

Values are strings up to 2,000 characters; unknown fields are ignored; file uploads are not accepted. The contractor who receives a lead is chosen by Paintaire on the server — an agent cannot select one.

Flow

POST /api/agent/actions/{action}/preview with scope lead:preview. Returns a signed preview_id valid for 10 minutes, the normalized fields, the destination, and the exact confirmation_statement.
Show the user the fields, destination and statement. Proceed only on their explicit agreement.
POST /api/agent/actions/{action}/execute with scope lead:create, header Idempotency-Key (up to 200 characters, unique per user request), and body { "preview_id", "confirmation": true, "confirmation_text" }. The text must be exactly: “I confirm that Paintaire may use these details for the selected action.”
Store the returned receipt. Retrying with the same key and preview replays it (replay: true) without a second submission. A preview executes once: an executed preview is consumed even if the execution failed (a relayed 4xx or a 502). To try again after a failure, create a new preview and confirm with the user again; do not retry under a new key.

Responses

Status	When
200	Preview created; execution submitted or replayed
400	Invalid JSON, field, preview token (including a malformed token — anything other than exactly `<payload>.<signature>`), expired preview, missing `Idempotency-Key`, or action mismatch
401	Missing or invalid bearer credential
403	Credential lacks the scope
404	Unknown action
409	Confirmation missing or not exact; execution already in progress (`retryable: true`); `preview_already_used` — this preview was executed under another key; `idempotency_conflict` — this key was used with a different preview
429	Preview over 60 per minute or execute over 20 per minute per client address, or on execute an upstream rate limit relayed with its `Retry-After`; honor `Retry-After`
Other 4xx	Execution only: the upstream rejected the submission; its status passed through and the receipt is `failed`
502	Upstream failed or could not confirm the submission; also returned when replaying a failed execution
503	Execution not configured or receipt storage unavailable

Errors are { "error": "<message or code>" } with extra fields where listed.

Credentials

Issued by Paintaire on request for a named client, scoped to lead:preview and/or lead:create. Rotation overlaps old and new credentials; revocation is immediate on the next deployment. There is no self-service issuance.

Human page: https://paintaire.com/developers/agent-api