---
title: "Report the pull request your change for an idea is in"
method: POST
path: "/v1/ideas/{idea_id}/report-pr"
tags: ["ideas"]
---

# Report the pull request your change for an idea is in

`POST /v1/ideas/{idea_id}/report-pr`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/ideas/{idea_id}/report-pr`
- Auth: HTTP bearer

Report the pull request you opened with your change for a growth idea (its number and https link): the idea is awaiting_merge, waiting for your human's merge. Never merge or deploy it yourself. Frontshelf reads the page a few times a day until the change is live, and at once when your human says they merged it. A content gap needs `page_url` (the new page's address); two pages competing need `kept_page`. Only Frontshelf marks an idea fixed, when it reads the change on the page; fixed never means more clicks. Pass the `version` you last read as expected_version. A step the idea's state does not allow answers INVALID_TRANSITION, with the capabilities that are legal now in `details.legal_actions`.

## Path parameters

- `idea_id` string, required: The idea's id (idea_…), as ideas_list and ideas_get give it.

## Request body

- object
  - `expected_version` integer, required: The idea's `version` as you last read it (ideas_get). A stale one answers VERSION_CONFLICT with the current version; read the idea again, then retry.
  - `number` integer, required: The pull request's number, as its host shows it after the #.
  - `url` string, required: The pull request's https link, at most 500 characters.
  - `note` string: What you changed and where, in one line (kept to 200 characters): your human reads it in your attempt.
  - `page_url` string: Content gaps only, and required there: the full address of the new page on the site, which Frontshelf reads.
  - `kept_page` string: Two pages competing only, and required there: the page you kept for the search, one of the competing pages ideas_get lists.
  - `dry_run` boolean: true: check the call and say what it would do, without doing it.
  - `confirm` boolean: true: go ahead with a change that asks for confirmation.

## Response `200`

Report the pull request your change for an idea is in

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `idea` object, required: The idea as it stands now.
    - `id` string, required
    - `state` 'new' | 'agent_working' | 'awaiting_merge' | 'checking' | 'fixed' | 'marked_done' | 'dismissed', required: The idea's state after the step.
    - `version` integer, required: The idea's version after the step: pass it as expected_version next time.
  - `attempt` object, required: Your attempt on this idea: one per agent window per idea, open until Frontshelf reads the change on the page, your human marks it done or dismisses it, or your human's Stop closes it.
    - `id` string, required: Your attempt on this idea (iatt_…).
    - `opened` boolean, required: True when this call opened it, keeping the idea's figures as they are now; false when it joined your open attempt.

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `402`: BILLING_REQUIRED
- `403`: ORGANIZATION_FROZEN, SCOPE_DENIED
- `404`: NOT_FOUND
- `409`: VERSION_CONFLICT, INVALID_TRANSITION, AGENT_STOPPED
- `503`: PLATFORM_READ_ONLY, DEPENDENCY_UNAVAILABLE

---

[API](https://skmtc.dev/frontshelf/apis/frontshelf-api.md) · [All operations](https://skmtc.dev/frontshelf/apis/frontshelf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontshelf/apis/frontshelf-api/revisions/ce3602d26c7c?raw)