Migrating from v1 to v2

Introduction

Productboard API v2 is the next generation of our public API — designed from the ground up to be more consistent, more flexible, and more efficient than v1. Whether you're maintaining an existing integration or planning a new one, this guide will walk you through what's changing, what's staying the same, and how to make the transition smoothly.

Why API v2

API v1 was built incrementally over time, which led to inconsistencies across endpoints and gaps in coverage. API v2 addresses this with a unified design: predictable endpoint patterns, configuration-driven schemas, and new capabilities — all built around standard RESTful conventions. The result is an API that's easier to learn, faster to integrate with, and requires fewer calls to get the data you need.

What stays the same

Not everything is changing. These foundational aspects of the API work the same way in v2:

• Authentication — same auth mechanism, no changes required
• Rate limits — same limits and behavior
• Richtext formatting — same format for richtext fields

If your integration already handles these, that code carries over as-is.

Key Changes in API v2

API v2 isn't just a version bump — it's a redesign of how the API works. Here are the most important changes you'll encounter when migrating from v1.

Configuration-based API

In v1, figuring out which fields an entity supported often required multiple API calls, or digging through documentation. API v2 introduces configuration endpoints that describe this for you. You can query the configuration for any entity or note type to get a full list of available fields, their types, and the filters you can use. No more brittle data models — your integration can discover what's available at runtime.

Unified entity endpoint

v1 grew organically, which meant different entity types had different endpoint structures and different levels of support. Some entities couldn't be deleted; others had inconsistent field behavior. v2 replaces this patchwork with a single, consistent endpoint pattern that covers all entity types — products, components, features, subfeatures, initiatives, objectives, key results, releases, release groups, users, and companies. Every entity type supports the same set of operations: Create, List, Retrieve, Update, and Delete. And all fields and values are returned by default, so you don't need extra calls to get the full picture.

Relationship endpoints

Connecting entities and notes in v1 required indirect approaches — often involving multiple calls or workarounds to piece together how objects related to each other. v2 introduces dedicated relationship endpoints for both entities and notes, giving you a direct way to traverse the graph of connections between objects. You can list, create, and remove relationships in a straightforward, predictable way.

No X-Version header required

A small quality-of-life improvement: v1 required an X-Version header on every request. In v2, you just call the endpoint directly — no version header needed. One less thing to configure, one less thing to debug.

New features

v2 also brings capabilities that didn't exist in v1:

• Analytics, Teams, and Members — new endpoints for accessing team structures and member activity data
• Response field control — use the fields query parameter to request only the fields you need, reducing payload size and improving performance
• Powerful search capabilities - search entities by the value of default and custom fields.
• Richer error responses — v2 returns structured error codes alongside error messages, making it easier to handle errors programmatically

Known Parity Gaps in API v2

API v2 covers the vast majority of what v1 offers, but there are a few gaps worth knowing about. Some are permanent design decisions, others are temporary. Here's a clear breakdown so you can plan accordingly.

Removed endpoints with no plans to return

Two v1 endpoint groups have been removed from v2 and won't be coming back:

• Note followers — the ability to add or remove followers from a note via the API is no longer available
• Feedback forms — listing configurations, retrieving configurations, and submitting a feedback form are no longer supported

If your integration relies on either of these, you'll need to remove that functionality or handle it outside the API.

Removed endpoints planned for a future release

A few v1 capabilities aren't available in v2 at launch, but they're on the roadmap. We're sharing these gaps upfront so you can plan your migration with full visibility — no surprises.

Custom field management

Creating, updating, and deleting company fields via the API is temporarily unavailable in v2. You can still read and write values to existing custom fields through the entity endpoints — it's only the field definition management that's missing.

Notes search limitations

v2 includes a list notes and notes search endpoint. Full-text search across note content (the term parameter in v1) is now supported via the data.search.query field on notes search. One gap remains:

• Filtering by tag (anyTag / allTags in v1)

What to do in the meantime

If your integration depends on any of these capabilities, you have two options:

• Continue using v1 for the affected operations while migrating everything else to v2. Both API versions can run side by side, so you don't need to wait for full parity before starting your migration.
• Watch for updates — we'll announce new v2 capabilities through our changelog as they become available.

Notes response changes

The v2 List notes and Get note endpoints return a leaner response than their v1 equivalents. The following fields are no longer included:

• followers[] — follower data is no longer part of the note response
• comments[] — comments are no longer embedded in note responses
• totalResults — no longer returned in list responses
• features[].importance — the importance value on note-to-entity relationships has been removed

If your integration reads any of these fields, you'll need to update your code to handle their absence. Call the v2 List configurations endpoint for the current response schema.

Important Considerations When Migrating to API v2

Beyond the parity gaps covered above, there are a few behavioral changes in v2 that could affect your integration in unexpected ways if you're not prepared. These aren't missing features — they're differences in how v2 handles operations you may already be using. Here's what to watch for.

Cascading deletes

In v1, deleting a parent entity that had children was blocked — you'd get an error and have to delete the children first. In v2, those deletes cascade automatically:

This applies to the Delete a feature, Delete a release group, and Delete a release v1 endpoints.

Why this matters: If your integration relied on v1's safeguard behavior — for example, treating a blocked delete as a signal that children exist — that safety net is gone in v2. An accidental delete of a parent entity will now remove all its children without warning.

Workaround: Add a pre-deletion check to your integration. Before issuing a DELETE, call the relevant list endpoint to verify whether the entity has children, and prompt for confirmation or block the operation in your own application logic.

User and company creation for notes

In v1, the Create a note endpoint accepted user and company identifiers like user.email or company.domain and would automatically create those records if they didn't already exist in Productboard. In v2, that auto-creation behavior is gone — users and companies must exist before you can assign a note to them.

How it works now

The v2 Create a note endpoint accepts a user's email address directly in the relationships array:

{
  "relationships": [
    {
      "type": "customer",
      "target": {
        "type": "user",
        "email": "[email protected]"
      }
    }
  ]
}

If the user exists, the note is created and assigned to them. If the user doesn't exist, the API returns a 404 error — regardless of whether the associated company exists.

What to change in your integration

If your v1 integration relied on auto-creation, you'll need to handle the 404 case explicitly:

1. Attempt to create the note with the user's email in data.relationships[].target.email
2. If you get a 404, create the user via the entity endpoint (set type to user). If the user's company doesn't exist yet, it will be created automatically as part of user creation
3. Retry the note creation

This adds a conditional extra step to the note creation flow, but the happy path — where the user already exists — remains a single call.

Create and update responses are minimal

In v1, create and update operations return the complete entity with all its fields — making it easy to update local state or display the result immediately. In v2, these operations return only a minimal reference:

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "feature",
    "links": {
      "self": "https://api.productboard.com/v2/entities/123e4567..."
    }
  }
}

Why this matters: If your integration reads fields from the response body after a create or update — for example, to populate a UI or trigger downstream logic — those fields won't be there anymore.

Workaround: Follow up with a GET request to the URL in links.self to retrieve the full entity. If you're doing batch operations, consider whether you can defer the full retrieval until it's actually needed, rather than fetching after every write.

Progress reporting in key result entities

The progress field on keyResult entities has changed in v2. In v1, the response included a server-computed progress percentage alongside the raw values:

"progress": {
  "startValue": 1,
  "targetValue": 4,
  "currentValue": 2,
  "progress": 33.33
}

In v2, the computed percentage is removed. You get only the raw values:

"progress": {
  "startValue": 1,
  "targetValue": 4,
  "currentValue": 2
}

See Progress Fields types for the full schema.

If your integration displays or uses that percentage, you'll need to compute it client-side:

progress = (currentValue - startValue) / (targetValue - startValue) * 100

Be sure to handle the edge case where targetValue equals startValue to avoid a division-by-zero error.

Pagination

v2 uses the same cursor-based approach as v1. There is no way to control the limit of the number of items returned in a page. This means that while you can still paginate through results, you won't be able to specify how many items you get back in each response. The best way to paginate is to keep fetching pages until you reach the end of the list, which is indicated by a null value of a links.next field in the response.

AI Coding Agent Considerations

If you're using AI-assisted tools like Claude Code, Cursor, or GitHub Copilot to build or maintain your Productboard integration, there's one simple step you can take to get significantly better results: point your agent at the raw markdown version of the documentation.

Fetch documentation as markdown

Productboard's API reference is available in markdown format by appending .md to any documentation URL. For example:

• Standard URL: https://developer.productboard.com/reference/createnote
• Markdown URL: https://developer.productboard.com/reference/createnote.md

Why this matters for AI agents

When an AI coding agent fetches a standard documentation page, it has to parse through rendered HTML — navigation elements, scripts, styling — to find the actual API content. The markdown version strips all of that away, giving the agent clean, structured text that's easier to process.

This means:

• More accurate code generation — the agent can extract endpoint details, field names, and request/response schemas without noise
• Up-to-date content — fetching directly from the documentation source ensures the agent isn't relying on stale training data
• Better migration guidance — when moving from v1 to v2, an agent with access to both sets of markdown docs can map changes more reliably

If your agent supports tool use or web fetching, configure it to retrieve the .md variant of any Productboard API reference page before generating or updating integration code.

This advice applies to this document too so this document can also help steer your agent's understanding of the migration process and key considerations.

Feedback and Help

We'd love to hear how your migration is going. If you have questions, run into issues, or want to share feedback on API v2, visit our Feedback and Help page for support options and ways to get in touch with the team.