> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shootbin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add visual annotations to photos

> Pin comments onto exact locations on a photo using x/y coordinates, reply in annotation threads, and resolve notes once feedback is addressed.

Annotations are comments pinned to a precise location on a photo. Instead of writing "fix the hair on the left" in a general message, you click the exact spot on the image and type your note there. Both photographers and clients (approvers) can add annotations, reply to each other's notes in threaded comments, and mark notes as resolved once the feedback has been addressed.

## Adding an annotation

<Steps>
  <Step title="Enter annotation mode">
    Open a photo and click the **Add Note** button (or press `Ctrl+N` / `Cmd+N`). The cursor changes to a crosshair to indicate you are in annotation mode.
  </Step>

  <Step title="Place your marker">
    Click anywhere on the photo to drop a marker at that position. For rectangular area annotations, switch to rectangle mode and drag to draw a box over the area you want to highlight.
  </Step>

  <Step title="Type your comment">
    A text input appears next to your marker. Type your feedback and press **Save** (or hit Enter) to post the annotation.
  </Step>

  <Step title="Exit annotation mode">
    Click **Done** or press `Ctrl+N` / `Cmd+N` again to leave annotation mode. Your notes are saved and visible to everyone with access to the photo.
  </Step>
</Steps>

<Info>
  Annotations are pinned using percentage-based x/y coordinates relative to the photo, so they stay in the correct position regardless of screen size or zoom level.
</Info>

## Who can annotate

<CardGroup cols={2}>
  <Card title="Photographers (owners)" icon="camera">
    Owners can add annotations, edit their own notes, move markers by dragging them in annotation mode, and delete any annotation on the photo.
  </Card>

  <Card title="Clients (approvers)" icon="user-check">
    Approvers can add annotations and reply to existing annotation threads. They cannot delete notes left by other users.
  </Card>
</CardGroup>

<Note>
  Guest users can view photos and their annotations but cannot add or edit notes.
</Note>

## Annotation threads

Each annotation supports a reply thread, so conversations about a specific spot stay organized in one place.

* Click on any annotation marker to open the thread panel.
* Type in the reply box at the bottom of the thread and press **Send** to post a reply.
* You can delete your own comments from a thread; owners can delete any comment.

## Resolving annotations

Once you have addressed a piece of feedback, mark the annotation as resolved to keep the list tidy.

<Steps>
  <Step title="Resolve a single annotation">
    Open an annotation and click **Resolve**. The marker turns grey and moves to the "Resolved" filter view. Click **Unresolve** to reopen it if needed.
  </Step>

  <Step title="Resolve all open annotations at once">
    When you have addressed all outstanding feedback, click **Resolve All** at the top of the annotations panel. This marks every open annotation on the photo as resolved in one action.
  </Step>
</Steps>

You can filter the annotation list by **All**, **Open**, or **Resolved** to focus on what still needs attention.

<Tip>
  Resolve annotations as you upload revised photos. A clean resolved list makes it easy to confirm at a glance that all feedback was addressed before you request the next review round.
</Tip>

## API

You can manage annotations programmatically using the Shootbin API. All requests require a Bearer token and `Accept: application/json`.

### Add an annotation

```bash theme={null}
POST /api/projects/{project}/albums/{album}/photos/{photo}/annotations
```

**Request body:**

```json theme={null}
{
  "comment": "Please retouch the background near the top-left corner.",
  "x_position": 12.5,
  "y_position": 8.3
}
```

| Field        | Type   | Description                                                     |
| ------------ | ------ | --------------------------------------------------------------- |
| `comment`    | string | The annotation text. Required.                                  |
| `x_position` | float  | Horizontal position as a percentage (0–100) of the photo width. |
| `y_position` | float  | Vertical position as a percentage (0–100) of the photo height.  |

**Example:**

```bash theme={null}
curl -X POST https://your-domain.tld/api/projects/PROJECT_ID/albums/ALBUM_ID/photos/PHOTO_ID/annotations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"comment":"Soften the shadow on the left cheek.","x_position":42.5,"y_position":31.2}'
```

### Delete an annotation

```bash theme={null}
DELETE /api/projects/{project}/albums/{album}/photos/{photo}/annotations/{annotation}
```

```bash theme={null}
curl -X DELETE https://your-domain.tld/api/projects/PROJECT_ID/albums/ALBUM_ID/photos/PHOTO_ID/annotations/ANNOTATION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
```

<Warning>
  Deleting an annotation also removes its entire reply thread. This action cannot be undone.
</Warning>

## Related pages

* [Review workflow](/guides/review-workflow), how the broader proofing loop works between photographer and client
* [Approve, reject, and select photos for delivery](/guides/approvals), marking individual photos as approved or rejected