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

# Event Settings

> Read and change gallery and participant search settings

## Overview

Read or change the settings organisers manage in the dashboard: participant search, gallery display, downloads and visibility. Changes take effect in the gallery on the participant's next visit.

OAuth only. Reads require `events:read`. Changes require `events:read` and `events:write`, plus an accepted organiser **admin** membership. Send a bearer token without `X-API-Key`.

Changes run in one call: send `mode: "execute"` with a stable `idempotency_key`; `mode: "preview"` (the default) is an optional dry run. Active photo work blocks changes. See [Operations](/api-reference/operations) for retry rules.

> [!NOTE]
>
> Turning BIB or selfie search on makes [Process](/api-reference/pipeline/photos/process) use 1 credit per photo, and photos processed earlier must be reprocessed to become searchable. Photo watermarks are edited in the dashboard; `watermark_configured` reports whether one is set up.

## Endpoints

```
GET   /api/v1/ext/{org_id}/event/{event_id}/settings
PATCH /api/v1/ext/{org_id}/event/{event_id}/settings
```

## Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `org_id` | integer | Yes | Organiser where the caller has an accepted membership (admin for changes). |
| `event_id` | integer | Yes | Event to read or change. |

## Request Body (PATCH)

Send only the settings to change; at least one is required.

| Field | Type | Description |
| - | - | - |
| `bib_search` | boolean | BIB search. Running events only; turning it off also turns off context search. |
| `selfie_search` | boolean | Selfie search. |
| `show_all_images` | boolean | Show every photo, not only search results. Turning it off also turns off timeline search. |
| `timeline_search` | boolean | Browse photos by time. Needs `show_all_images`. |
| `bulk_download` | boolean | Let participants download their photos in bulk. |
| `show_total_photos_count` | boolean | Show the total photo count. |
| `visibility` | string | `public` lists the event on your storefront; `private` needs the gallery link. Trial events stay private. |
| `mode` | string | `execute` to apply; `preview` (the default) is a dry run. |
| `idempotency_key` | string | Required with `execute`; stable retry key. |

## Example Requests

### Read

```bash cURL theme={null}
curl -i -X GET \
  -H "Authorization: Bearer <oauth_access_token>" \
  "https://api.9pic.ai/api/v1/ext/903/event/456/settings"
```

```python Python theme={null}
import requests

response = requests.get(
    "https://api.9pic.ai/api/v1/ext/903/event/456/settings",
    headers={"Authorization": "Bearer <oauth_access_token>"},
)
print(response.status_code, response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.9pic.ai/api/v1/ext/903/event/456/settings", {
  method: "GET",
  headers: { "Authorization": "Bearer <oauth_access_token>" },
});
console.log(await response.json());
```

### Change

```bash cURL theme={null}
curl -i -X PATCH \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  "https://api.9pic.ai/api/v1/ext/903/event/456/settings" \
  -d '{"mode": "execute", "idempotency_key": "event-456-settings-1", "bulk_download": false, "visibility": "private"}'
```

```python Python theme={null}
import requests

response = requests.patch(
    "https://api.9pic.ai/api/v1/ext/903/event/456/settings",
    headers={"Authorization": "Bearer <oauth_access_token>"},
    json={'mode': 'execute', 'idempotency_key': 'event-456-settings-1', 'bulk_download': False, 'visibility': 'private'},
)
print(response.status_code, response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.9pic.ai/api/v1/ext/903/event/456/settings", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <oauth_access_token>", "Content-Type": "application/json" },
  body: JSON.stringify({"mode": "execute", "idempotency_key": "event-456-settings-1", "bulk_download": false, "visibility": "private"}),
});
console.log(await response.json());
```

## Example Responses

### Read

```json theme={null}
{
  "responseType": "success",
  "message": "Event settings",
  "data": {
    "event_id": 456,
    "bib_search": true,
    "selfie_search": true,
    "context_search": false,
    "show_all_images": true,
    "timeline_search": true,
    "bulk_download": true,
    "show_total_photos_count": true,
    "visibility": "public",
    "watermark_configured": false
  }
}
```

### Change

```json theme={null}
{
  "responseType": "success",
  "message": "Event settings updated",
  "data": {
    "mode": "execute",
    "operation": "update_event_settings",
    "org_id": 903,
    "event_id": 456,
    "review_token": null,
    "expires_at": null,
    "proposed": {
      "before": { "bulk_download": true, "visibility": "public" },
      "after": { "bulk_download": false, "visibility": "private" }
    },
    "consequences": [
      "Updates gallery settings; participants see the change on their next visit.",
      "Only people with the gallery link can open the event."
    ],
    "operation_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "completed",
    "result": {
      "event_id": 456,
      "bib_search": true,
      "selfie_search": true,
      "show_all_images": true,
      "timeline_search": true,
      "bulk_download": false,
      "show_total_photos_count": true,
      "visibility": "private"
    }
  }
}
```

## Response Models

[ReviewedWriteRequest](/api-reference/models/workflow#reviewedwriterequest) and [GuardedOperationData](/api-reference/models/workflow#guardedoperationdata).

## Error Responses

| Status | Meaning |
| - | - |
| `400` / `422` | Invalid input, nothing to change, BIB search on a non-running event, timeline search without all photos, or missing `idempotency_key`. |
| `401` | Invalid or expired access token. |
| `403` | Missing scopes, membership, or admin role; `public` visibility on a Trial plan; API keys are rejected. |
| `404` | Event configuration not found. |
| `409` | Retry key reused for a different action, or active photo work. |
| `503` | Organiser writes are temporarily unavailable. |

See [Errors](/api-reference/errors) and [Conventions](/api-reference/conventions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.