List suggestions

GET

/v1/suggestions

const url = 'https://api.gopromptless.ai/v1/suggestions?event=created&status=open&limit=50&offset=0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.gopromptless.ai/v1/suggestions?event=created&status=open&limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

Read the suggestion lifecycle feed for your organization. Filter with event or status (not both), narrow with query and since, and page with limit and offset. Results are ordered newest-first by the selected event’s timestamp.

Authorizations

bearerAuth

Parameters

Query Parameters

event

string

Allowed values: created merged closed

Select suggestions by lifecycle event and order by that event’s timestamp. Cannot be combined with status.

status

string

Allowed values: open draft merged closed

Select suggestions by current status. Cannot be combined with event.

query

string

Free-text match against suggestion title and description.

since

string format: date-time

ISO 8601 timestamp used as an inclusive lower limit on the event timestamp. A row whose timestamp equals this value is returned again, so deduplicate by id.

limit

integer

default: 50 >= 1 <= 100

Maximum number of suggestions to return.

offset

integer

Number of suggestions to skip before returning results.

Responses

200

A page of suggestions from the lifecycle feed.

application/json

SuggestionsResponse

A page of suggestions from the lifecycle feed.

object

suggestions

required

Suggestions

Array<object>

Suggestion

A documentation suggestion and its lifecycle state.

object

required

string format: uuid

title

required

Title

string | null

description

required

Description

string | null

status

required

Status

Current status, mirroring the docs pull request’s state (open, draft, merged, or closed). Null when the suggestion is drafted but no docs PR has been opened yet. Draft when a draft docs PR is open.

string | null

Allowed values: open draft merged closed

trigger_event_id

required

Trigger Event Id

Identifier of the task that created the suggestion, the same id POST /v1/triggers returned. Null for suggestions created before tasks were recorded.

string | null format: uuid

url

required

Url

string

docs_pr_url

required

Docs Pr Url

Link to the documentation pull request, or null before a docs PR exists.

string | null

doc_collection_id

required

Doc Collection Id

string | null format: uuid

doc_collection_name

required

Doc Collection Name

string | null

impacted_file_paths

required

Impacted File Paths

Array<string>

impacted_file_count

required

Impacted File Count

integer

created_at

required

Created At

string format: date-time

merged_at

required

Merged At

string | null format: date-time

closed_at

required

Closed At

string | null format: date-time

closed_without_merge

required

Closed Without Merge

True when the suggestion was closed without merging. Branch shipped versus rejected on this field.

boolean

close_reason

required

Close Reason

Supplementary machine-readable label for why the suggestion closed. This set may expand over time and includes a catch-all (unknown_legacy), so branch on closed_without_merge rather than hard-coding these values.

string | null

Allowed values: dashboard_review docs_pr_webhook stale_archive agent_supersede empty_after_edit unknown_legacy

Example

{
  "suggestions": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "open",
      "trigger_event_id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://app.gopromptless.ai/suggestions/7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "close_reason": "dashboard_review"
    }
  ]
}

400

A query parameter is invalid — since is not a valid ISO 8601 timestamp (invalid_since), or event and status were combined (invalid_filter).

application/json

ApiTriggerErrorResponse

Error body returned when an API trigger request is rejected.

object

error

required

Error

Stable machine-readable error code.

string

message

required

Message

Human-readable explanation of the error.

string

Example

{
  "error": "authentication_failed",
  "message": "Authentication failed."
}

401

The API key is missing, invalid, or revoked.

application/json

ApiTriggerErrorResponse

Error body returned when an API trigger request is rejected.

object

error

required

Error

Stable machine-readable error code.

string

message

required

Message

Human-readable explanation of the error.

string

Example

{
  "error": "authentication_failed",
  "message": "Authentication failed."
}

503

The read store is temporarily unavailable (runtime_store_unavailable).

application/json

ApiTriggerErrorResponse

Error body returned when an API trigger request is rejected.

object

error

required

Error

Stable machine-readable error code.

string

message

required

Message

Human-readable explanation of the error.

string

Example

{
  "error": "authentication_failed",
  "message": "Authentication failed."
}