Migrate from API v1 to v2

API v2 replaces v1 as the documented, actively developed API. v1 keeps working for existing integrations, but it no longer receives new features.

This guide lists the changes required to move a v1 integration to v2.

The v1 reference remains available.

What stays the same

• Authentication. Send Authorization: Api-Key <your-api-key>, exactly as in v1. Existing API keys keep working; you don't need to re-issue them.
• Base URL. https://app.pushfeedback.com.
• Existing widget installations. The v1 widget endpoints remain available while you migrate configuration reads and feedback submissions to v2.

Endpoint mapping

v1 endpoint	v2 endpoint
GET /api/v1/projects/{slug}/	GET /api/v2/projects/{slug}/ (public configuration or authenticated full settings)
POST /api/v1/feedback/	POST /api/v2/projects/{slug}/feedback/
GET /api/v1/projects/{slug}/feedback/	GET /api/v2/projects/{slug}/feedback/
PATCH /api/v1/projects/{slug}/settings/	PATCH /api/v2/projects/{slug}/

Permission renames

v2 renames API key permissions to a consistent <resource>_<action> scheme.

v1 permission	v2 permission
feedback:read	feedback_read
feedback:submit	feedback_create
project:manage	projects_read + projects_update

Keys created before v2 may carry the legacy names. They remain valid as aliases of their v2 equivalents, so no key rotation is needed. feedback_submit also remains an alias for feedback_create.

Breaking changes

Get project: widget configuration and full settings

Use GET /api/v2/projects/{slug}/ to load the widget's configuration. Without a key, a project with require_submit_key disabled returns the public configuration: whitelabel, reCAPTCHA enabled state and site key, require_submit_key, plan, and features.

With a key covering the project and carrying projects_read, the endpoint returns the full project settings (url, name, additional_urls, require_submit_key, recaptcha, feedback_count, timestamps, and other project fields). The full response nests reCAPTCHA settings under recaptcha instead of the public configuration's recaptcha_enabled and recaptcha_site_key fields.

When require_submit_key is enabled, a client using v2 needs a project-restricted key with both projects_read and feedback_create to read configuration and submit feedback. Anyone who can view the page can read the key and access the full project settings. See API key security.

Submit feedback: project moved to the path, object response

Submitting now happens under the project, at POST /api/v2/projects/{slug}/feedback/. Remove project from the request body and put the slug in the URL instead.

Two field names change to snake case: ratingMode is now rating_mode, and recaptchaToken is now recaptcha_token.

Replace YOUR_PROJECT_ID with your project's slug in the examples below. The page URL must use the project's configured hostname or one of its additional URLs; otherwise the request returns 403.

The 201 response is the created feedback entry as a JSON object (the same shape you get from the list and get endpoints), instead of a bare string. Unknown fields in the body are rejected with 400 rather than ignored.

v1

curl -X POST https://app.pushfeedback.com/api/v1/feedback/ \
  -H "Content-Type: application/json" \
  -d '{"project": "YOUR_PROJECT_ID", "url": "https://docs.example.com/install", "rating": 5, "ratingMode": "stars", "message": "Clear and helpful."}'

v2

curl -X POST https://app.pushfeedback.com/api/v2/projects/YOUR_PROJECT_ID/feedback/ \
  -H "Content-Type: application/json" \
  -d '{"url": "https://docs.example.com/install", "rating": 5, "rating_mode": "stars", "message": "Clear and helpful."}'

Like v1, the endpoint is public unless the project has require_submit_key enabled, in which case a key with feedback_create is required.

Rating values

v2 uses the same numeric rating values in requests and responses: 5 for a thumbs up, 0 for a thumbs down, 1 to 5 for stars, and -1 for no rating. Change a v1 thumbs-up submission from 1 to 5 when moving to v2.

Case	v1 request	v2 request	v2 response
Stars	1 to 5	1 to 5	1 to 5
Thumbs up	1	5	5
Thumbs down	0 (or legacy widget value 5)	0	0
No rating	-1; omitted defaults to 0	-1 (or omitted)	-1

The create, list, and single-entry responses all use the same Feedback schema, including numeric rating and rating_mode. The list endpoint's rating=positive|neutral|negative query parameter filters by sentiment; it does not replace the numeric response value. Here, neutral means no rating (-1).

v1 omission defaults to 0, which is stored as a zero-star rating or thumbs down. In v2, omit rating or send -1 when no rating was given. Migration does not rewrite existing entries.

List feedback: limit/offset pagination and filters

• v1 paginated with a page query parameter, 25 entries per page. v2 uses limit (default 20, max 100) and offset, and the response keeps the count, next, previous, and results envelope. Follow next until it is null, or compute offsets yourself.
• Entries gain session, metadata, and updated_at. screenshot_url is still pre-signed and short-lived; fetch screenshots right after listing.
• The v1 compatibility field locked (always false) is omitted in v2. Remove any dependency on it; it does not indicate access to an entry.
• v2 adds filters (status, rating, has_message, has_screenshot, has_email, url, from, to) and an order parameter. See List feedback.

Update project settings: full project resource

PATCH /api/v1/projects/{slug}/settings/ accepted url and whitelabel and returned a three-field summary. In v2, PATCH /api/v2/projects/{slug}/ accepts any subset of the editable settings (url, name, additional_urls, whitelabel, require_submit_key, mcp_enabled, recaptcha) and returns the full project object.

mcp_enabled controls MCP access for one project and is accepted by project updates. New projects start with MCP disabled. Enable it under Projects > your project > Settings > MCP, or through an authorized REST update. See MCP setup.

whitelabel keeps its v1 semantics: it is team-wide and enabling it requires a paid plan.

Integration configuration: separate project resource

Email notifications are not part of the v2 project response or update request. Configure them through /api/v2/projects/{slug}/integrations/, alongside Slack, Jira Automation, webhooks, and the other supported integrations. Sending notifications to the project update endpoint returns 400.

Use Create an integration with integration_type: "email" and configuration.emails to configure recipients. To change an existing email integration, send the same configuration fields to PATCH /api/v2/projects/{slug}/integrations/email/. The enabled switch is a top-level integration field.

Integration access requires the corresponding integrations_read, integrations_create, integrations_update, or integrations_delete permission. Neither project permissions nor the legacy project:manage alias grant these permissions. Update an API key's permissions before moving an integration-management client to these endpoints; widget keys do not need integration access.

curl -X POST https://app.pushfeedback.com/api/v2/projects/YOUR_PROJECT_ID/integrations/ \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integration_type": "email", "enabled": true, "configuration": {"emails": ["[email protected]"]}}'

Tokens and webhook URLs are write-only. Read responses contain has_* flags instead of those values. Omit credentials in a partial update to retain them; an API response cannot be used as an update payload without removing read-only fields.

Integration ratings and delivery rules

Integration templates, field mappings, and conditions use the same rating values as the v2 feedback API. feedback.rating is 5 for a thumbs up, 0 for a thumbs down, 1 to 5 for stars, and -1 for no rating. feedback.rating_normalized remains available as an alias with the same value.

If an existing custom rule compared feedback.rating to the stored thumbs-up value 1, change that comparison to 5. Rules for a one-star rating still use 1. Review rules that mixed both rating modes before changing a numeric comparison.

feedback.sentiment follows the same categories as the feedback list filter: positive for 3 stars or more or a thumbs up, negative for ratings from 0 to 2, and neutral for no rating (-1). Existing delivery rules now use these categories too: three-star feedback matches positive, and unrated feedback matches neutral.

Custom mappings depend on the provider. Asana and Trello accept only an empty field_mappings object. For destination options such as label IDs or assignees, use the provider's configuration fields. See Update an integration for the provider table and examples of column mappings and grouped delivery rules.

New in v2

These capabilities have no v1 equivalent:

• Projects: create, list, and delete projects.
• Feedback triage: get a single entry, archive and restore entries (PATCH with status), and delete entries.
• Integrations: list, create, read, update, and delete email, chat, webhook, and issue-tracker configurations independently of project settings.
• Analytics: read aggregate feedback metrics for a project: KPIs, daily volume, top and emerging pages.

See the API v2 reference for details.