API Overview - Puffle Docs

Base URL

https://app.puffle.ai

Endpoint paths in this reference include their /api prefix, for example GET /api/account. Combine the base URL and documented path directly:

curl -H "Authorization: Bearer pk_live_abc123" \
  "https://app.puffle.ai/api/account"

HTTPS is required on all requests.

The public product surface uses Lead Finder, Feed, Outbound, Posts, Unibox, and Senders. Lead Finder routes live under /api/lead-finder; Feed routes live under /api/feed. /api/campaigns powers Outbound execution, and /api/calendar powers Posts and connected social accounts. Use the documented endpoint paths exactly.

Public Endpoint Scope

The API Reference lists the supported public Bearer-token contract. Admin routes under /api/admin/*, dashboard-only session routes, inbound webhooks, OAuth callbacks, legacy Leads/Lists/Signals surfaces, and private integration plumbing are intentionally hidden from these docs. If an endpoint is not documented here, do not infer that it is public or stable. Use the closest documented public endpoint or ask Puffle support for the intended workflow.

Authentication

All public API requests require a Puffle API key as a Bearer token in the Authorization header. API keys are prefixed with pk_live_.

Authorization: Bearer pk_live_abc123...

Generating an API key

Log in to the Puffle dashboard
Navigate to Settings -> API
Click Generate API key
Copy and store the key. It is shown only once.

Each account has one active API key at a time. Rotation therefore requires a short interruption: pause callers, revoke the current key, generate the replacement, deploy it to every caller, and then resume traffic. You cannot create the replacement while the old key is active.

Revoking an API key

Keys can be revoked from the dashboard or through the session-authenticated /api/user/api-key endpoint. Revocation is immediate, and subsequent requests using the revoked key fail with 401.

Session authentication

A small set of API key endpoints, specifically those that create, view, and revoke API keys (/api/user/api-key), use session-based authentication through browser cookies rather than Bearer tokens. These are designed to be called from the Puffle dashboard UI, not from your backend integration.

Security best practices

Never expose keys in client-side code

API keys grant full access to your Puffle account. Always make API calls from your backend, never from browser JavaScript or mobile apps where the key could be extracted.

Use environment variables

Store your key in an environment variable (PUFFLE_API_KEY) and reference it in code. Never hard-code keys or commit them to version control.

Rotate keys periodically

Plan a maintenance window. Pause API traffic, revoke the active key, generate and securely store the replacement, update every service, verify a low-risk read such as GET /api/account, and only then resume normal traffic. Requests made between revocation and deployment return 401.

Respond to suspected exposure

If a key may have been exposed, revoke it immediately from the Puffle dashboard and replace it before making more API requests.

Rate Limits

Rate limits are endpoint-specific. Some routes enforce their own cooldowns or protective limits, and upstream providers may also return rate-limit errors. The endpoint page is the source of truth for request size and polling guidance. If you receive a 429 Too Many Requests response, respect the Retry-After header when it is present. If there is no Retry-After, back off exponentially and avoid tight polling loops.

Rate-limit response

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry after 60 seconds."
  }
}

Handling rate limits

Detect the 429 status

Check for HTTP status 429 in every response before processing the body.

Read the Retry-After header

Wait the number of seconds specified in Retry-After before retrying.

Use exponential backoff

If Retry-After is not present, implement exponential backoff starting at 1 second.

Avoid polling loops

Avoid tight polling loops and back off aggressively after 429 responses.

Errors

Public Bearer-authenticated routes generally return the structured error envelope below for framework-level authentication, method, validation, and typed route errors:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description of the error."
  }
}

Some route-specific errors still return the older flat shape:

{
  "error": "Human-readable description of the error."
}

Check the endpoint page examples for the exact response shape an operation can return. Treat error.code as stable when it is present; otherwise handle the HTTP status and human-readable error message.

HTTP Status Codes

Status	Meaning	When It Happens
`200`	OK	Successful GET, PATCH, PUT, or POST that returns data
`201`	Created	Successful resource creation (POST)
`204`	No Content	Successful deletion or action with no response body
`400`	Bad Request	Invalid body, missing required fields, or constraint violation
`401`	Unauthorized	Missing or invalid Bearer token / session
`403`	Forbidden	Valid auth but insufficient permissions
`404`	Not Found	Resource does not exist or does not belong to your account
`409`	Conflict	Resource already exists, is already running, or cannot transition now
`422`	Unprocessable Entity	Well-formed but semantically invalid request
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

Error Codes

Code	Description
`unauthorized`	Missing or invalid authentication credentials
`not_found`	The requested resource does not exist
`invalid_request`	Body or parameters are invalid, or a constraint was violated
`rate_limited`	Endpoint or provider rate limit hit
`conflict`	Resource already exists or cannot transition now
`internal_error`	Unexpected server error

Pagination

Pagination is endpoint-specific. Feed, Lead Finder, and sender endpoints generally return bounded lists. Unibox and some Outbound endpoints use page, limit, or route-specific pagination fields. Use the query parameters and response fields shown on each endpoint page.

Common parameters

Parameter	Type	Description
`limit`	integer	Items to return. Maximum and default vary by endpoint.
`page`	integer	Page number for page-based endpoints.
`cursor`	string	Cursor for endpoints that explicitly document cursors.

Iterating Pages

# First page
curl -s -H "Authorization: Bearer pk_live_abc123" \
  "https://app.puffle.ai/api/threads?limit=50"

# Subsequent pages: follow the pagination field documented by the endpoint
curl -s -H "Authorization: Bearer pk_live_abc123" \
  "https://app.puffle.ai/api/threads?limit=50&page=2"

​Base URL

​Public Endpoint Scope

​Authentication

​Generating an API key

​Revoking an API key

​Session authentication

​Security best practices

​Rate Limits

​Rate-limit response

​Handling rate limits

​Errors

​HTTP Status Codes

​Error Codes

​Pagination

​Common parameters

​Iterating Pages

Base URL

Public Endpoint Scope

Authentication

Generating an API key

Revoking an API key

Session authentication

Security best practices

Rate Limits

Rate-limit response

Handling rate limits

Errors

HTTP Status Codes

Error Codes

Pagination

Common parameters

Iterating Pages