Synchronize Roadmap Status and Releases with the API

Discover roadmap statuses, synchronize feedback progress, set roadmap targets, and link shipped changelog posts through the ChangeCrab API.

All Articles

Synchronize Roadmap Status and Releases with the API

The Suggestions API includes ChangeCrab's mini roadmap. Integrations can discover the changelog's configured statuses, retrieve changed items, move feedback through the roadmap, set delivery targets, identify duplicates, and link feedback to the changelog post that shipped it.

Discover valid roadmap statuses

Statuses are configured per changelog, so integrations should discover them rather than hard-code database IDs. Call GET /api/changelogs/{id}/suggestion-statuses before synchronizing. 

{
  "success": true,
  "data": [
    {
      "id": 12,
      "name": "Under Review",
      "color": "#6366F1",
      "is_initial": true,
      "is_completed": false
    },
    {
      "id": 15,
      "name": "Completed",
      "color": "#10B981",
      "is_initial": false,
      "is_completed": true
    }
  ]
}

Move feedback through the roadmap

Update status_id using the suggestion endpoint. A real status transition updates status_changed_at, writes the lifecycle event, sets or clears completed_at, and uses the existing close-the-loop notification setting for followers. 

curl https://changecrab.com/api/changelogs/abc123def4/suggestions/482 \
  --request PATCH \
  --header "X-API-Key: your_api_key_here" \
  --header "Content-Type: application/json" \
  --data '{
    "status_id": 14,
    "eta": "Q4 2026",
    "target_quarter": "Q4 2026"
  }'

Synchronize incrementally

Store the latest successful synchronization time and pass it to updated_after. Follow the pagination metadata until current_page equals last_page. 

GET /api/changelogs/abc123def4/suggestions
  ?updated_after=2026-08-12T09:00:00Z
  &per_page=100
  &page=1

Use the server response's updated_at values to advance your checkpoint. Do not infer roadmap state from status names alone; retain the status ID mapping returned by the statuses endpoint.

Mark duplicate feedback

Set duplicate_of_id to another suggestion in the same changelog. Send null to detach it. ChangeCrab rejects self-references and cross-changelog suggestion IDs. 

{
  "duplicate_of_id": 417
}

Link feedback to a shipped changelog post

When work ships, set linked_post_id to a post belonging to the same changelog. ChangeCrab records a released lifecycle event and notifies followers when close-the-loop notifications are enabled. Send null to remove the link. 

curl https://changecrab.com/api/changelogs/abc123def4/suggestions/482 \
  --request PATCH \
  --header "X-API-Key: your_api_key_here" \
  --header "Content-Type: application/json" \
  --data '{
    "status_id": 15,
    "linked_post_id": 902
  }'

Roadmap fields

  • status is returned as an object containing the configured ID, name, and color.
  • eta is a short customer-facing estimate such as Q4 2026.
  • target_date accepts an exact YYYY-MM-DD date.
  • target_quarter is a short planning label such as Q4 2026.
  • duplicate_of_id points to the canonical feedback item.
  • linked_post_id points to the shipped changelog post.

Validation and access boundaries

Statuses, duplicate targets, and linked posts must belong to the same changelog. Private and internal visibility, bug reports, improvements, targets, duplicates, and release linking follow the changelog's enabled Premium feedback features. API keys can access only changelogs owned by teams available to their user.

Next steps