Conventions, as measured

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

These conventions describe what Paintaire does today, not a target. The shared marketplace layer is consistent; contractor deployments are separate systems that follow the patterns below only loosely, so check the contract of the service you are calling. For the marketplace routes, see the Agent API and the lead and newsletter contracts.

Authentication

Marketplace agent routes use Authorization: Bearer <token>. Each token carries scopes, and an action needs its scope. Credentials are issued by Paintaire on request.

Contractor deployments follow a different pattern: each service has its own API keys, issued by that deployment's owner. The header is usually X-API-Key, and some services use Authorization: Bearer instead. The header is specific to the service, and sending the wrong one gets a bare 401 with no hint about which header was expected. Do not reuse a credential across services.

Verified against ecosystem cecd4003

Errors

Marketplace routes return a flat { "error": "<message>" }, and some add fields that help you react: retry_after on a 429, retryable when an execution is already in progress, fields listing missing form fields, and confirmation_required with confirmation_statement when an action still needs explicit confirmation. Other Paintaire services use one of several envelope shapes. The direction of travel is a single envelope, { "error": { "code", "message", "details", "request_id" } }, but do not assume it yet. Parse by HTTP status first, then read whatever body is present defensively, and log request_id when a service supplies one.

Verified against ecosystem cecd4003

Rate limits

There is no platform-wide limiter. Limits, and the headers that report them, are set per service, so read the contract of each service you call. Honor Retry-After when present; some services send a 429 without it, so back off on your own. The marketplace routes send it in seconds. Do not build on X-RateLimit-Reset: its units are not consistent across services.

Verified against ecosystem cecd4003

Data

Money does not appear on the marketplace routes. Across Paintaire services the platform convention is that money crosses service boundaries as integer cents unless the owning service's contract says otherwise, and at least one service is an exception that stores dollars. Check the contract before doing arithmetic on an amount.

Timestamps on the marketplace routes, including action previews and receipts, are ISO-8601 in UTC. Contractor services vary, so read their contracts.

The Agent API's execute route requires an Idempotency-Key header, so a retry after a timeout replays the same receipt instead of creating a duplicate. The other marketplace routes do not take one.

Verified against this site's code and the platform conventions in ecosystem cecd4003

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