---
title: "Get edit recommendations"
method: POST
path: "/recommendations"
tags: ["Recommendations"]
---

# Get edit recommendations

`POST /recommendations`

## Request

- Base URL: `https://api.propertypixel.app/v1`
- URL: `https://api.propertypixel.app/v1/recommendations`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://llflgtovnkrsjqydycyu.supabase.co/auth/v1/oauth/authorize`, token URL `https://llflgtovnkrsjqydycyu.supabase.co/auth/v1/oauth/token`)

Free. Ask PropertyPixel's AI which corrective edits each photo needs (e.g. improve_lighting, clean_and_tidy, straighten_and_reframe). Select photos with photo_ids, or project_id + all_photos: true.

Returns the Recommendations that already exist and starts analysis for photos that have none. Analysis is asynchronous: photos in pending_photo_ids are still being analysed, so call again after poll_after_ms to see them. A daily analysis limit applies; photos over it are listed in skipped_photo_ids.

To run the suggestions, pass the ready Recommendation IDs to apply_recommendations (paid).

Requires a connection with edit access.

## Headers

- `Idempotency-Key` string: A unique key (for example a UUID) that makes retries safe. A retry with the same key and body returns the stored response; the same key with a different body returns 422. Keys last 24 hours.

## Request body

- object
  - `photo_ids` string[]: The photos to use. Get IDs from get_project. Alternatively pass project_id with all_photos: true.
  - `project_id` string, uuid: The project the photos belong to. Required with all_photos; with photo_ids it must match their project.
  - `all_photos` boolean: Use every photo in project_id instead of listing photo_ids.

## Response `200`

Get edit recommendations

- RecommendationList
  - `object` 'recommendation_list', required
  - `recommendations` Recommendation[], required
    - `object` 'recommendation', required
    - `id` string, uuid, required
    - `photo_id` string, uuid, required
    - `project_id` string, uuid, nullable, required
    - `status` 'pending' | 'ready' | 'no_changes' | 'applied' | 'dismissed' | 'failed', required: pending: still analysing. ready: can be applied. no_changes: the photo needs no corrective edits. applied: already turned into a job (see job_id). dismissed: the user dismissed it in the Studio. failed: analysis failed.
    - `enhancement_types` string[], required: The edits that applying this Recommendation runs.
    - `room_type` string, nullable, required: The photo's room type, if known.
    - `summary` string, required: One line describing the Recommendation.
    - `job_id` string, uuid, nullable, required: The enhancement job created when it was applied.
    - `created_at` string, date-time, required
  - `pending_photo_ids` string[], required: Photos still being analysed. Call again after poll_after_ms.
  - `skipped_photo_ids` string[], required: Photos with no Recommendation that could not be queued now (daily analysis limit reached, or the photo is not in a project).
  - `poll_after_ms` integer, required: Wait this long before calling again; 0 when nothing is pending.

## Other responses

- `400`: The request is invalid. Codes: `validation_failed`.
- `401`: Missing, invalid or revoked credential. Codes: `unauthorized`.
- `403`: The credential can't do this. View-only connections get forbidden_scope on writes. Codes: `forbidden_scope`, `forbidden`.
- `404`: The resource doesn't exist in this workspace. Codes: `not_found`.
- `409`: The request conflicts with the current state. Codes: `conflict`, `idempotency_in_progress`.
- `422`: An Idempotency-Key was reused with a different body, or an upload was rejected. Codes: `idempotency_conflict`, `upload_rejected`.
- `429`: Too many requests for this connection. Codes: `rate_limited`.
- `500`: Something failed on our side. Retry later. Codes: `internal`.

---

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