Use REST queries, uploads, and errors
Build clients around each endpoint’s supported fields and response contract.
The endpoint reference is the authority for each operation's method, path, parameters, schemas, and response examples. Existing endpoints use /api/... paths and retain their existing response shapes.
Query list endpoints
Many core resource lists support bracketed filters, comma-separated includes, and sorting. For example, the ideas list accepts a project filter, priority sorting, and related insights:
curl --get --fail-with-body \
"$CONVERSIONLAB_API_ORIGIN/api/ideas" \
--header "Authorization: Bearer $CONVERSIONLAB_TOKEN" \
--header 'Accept: application/json' \
--data-urlencode 'filter[project_id]=1' \
--data-urlencode 'sort=-priority_score' \
--data-urlencode 'include=insights' \
--data-urlencode 'page[number]=1' \
--data-urlencode 'page[size]=20'Use an ID returned by your team's project list instead of the illustrative 1. A leading minus requests descending order. Allowed filters, sorts, and includes differ by endpoint; unsupported names can be rejected.
Core lists using the JSON paginator accept page[number] and page[size], with a default and maximum page size of 30 in the current configuration. Other lists and reports can use different pagination or return a bounded collection; follow the operation's parameters and response links rather than assuming a single paginator everywhere.
Resource responses commonly wrap the record or collection in data. Related fields may appear only when included. /api/user, summaries, exports, and custom actions can have different shapes; parse their documented schemas.
Send writes and uploads
Send JSON with Content-Type: application/json for JSON operations. Use the operation's exact required IDs, enums, and field limits. Linked records must belong to the permitted project and team.
File uploads use multipart form data where specified. Ordinary attachments accept a file up to 10 MB and one of the documented JPEG, PNG, GIF, PDF, Word, or Excel formats. Link attachments use a URL instead of a file. An upload also identifies its project and attachable record; use the exact attachment type and fields in the reference.
Some updates have a documented POST alias for multipart compatibility. Use a method listed for that operation rather than inventing an alternative route. Bulk and lifecycle actions have their own request fields and effects; inspect the response before treating the whole selection as complete.
Handle failures
| HTTP status | Typical client response |
|---|---|
| 400 | Correct malformed or unsupported query parameters. |
| 401 | Replace missing, expired, or revoked authentication. |
| 402 | Resolve a read-only subscription state before retrying a write. |
| 403 | Check token ability, team membership, role, and feature availability. |
| 404 | Check the resource ID in the token's team context. |
| 422 | Read the validation message and field errors; correct the request. |
| 429 | Respect returned retry information and slow down. |
| 5xx | Preserve error context and retry cautiously after recovery. |
The configured default bearer-token rate limit is 120 requests per minute; deployments can override it. Read the returned rate-limit and retry headers when present. Do not retry validation or permission failures unchanged.
For a timed-out create, check whether the item was created before resending the same write. The public contract does not promise universal idempotency keys for mutations.