> ## 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.

# Workflow Models

> Write controls, operation, source settings and analytics models.

## Overview

Exact request and response models for organiser write actions, sources, search settings and aggregate analytics. Endpoint payloads live inside `data` in the [standard envelope](/api-reference/conventions#response-envelopes).

## ReviewedWriteRequest

Shared controls for every OAuth write. See [Operations](/api-reference/operations). Only [Process Photos](/api-reference/pipeline/photos/process) needs `review_token` and `confirmed`; every other write executes with `mode` and `idempotency_key` alone.

```json theme={null}
{
  "mode": "execute",
  "review_token": "ddc661a7-8861-4793-9437-af42a82d12f8",
  "idempotency_key": "event-456-process-1",
  "confirmed": true
}
```

| Field | Type | Description |
| - | - | - |
| `mode` | string | preview (default; a dry run that changes nothing) or execute. |
| `review_token` | string \| null | Process Photos only: required at execution; token from preview. Ignored by other writes. |
| `idempotency_key` | string \| null | Required at execution; stable nonempty retry key, up to 200 characters. |
| `confirmed` | boolean | Process Photos only: must be true at execution. Default false; client assertion of user confirmation, not human-presence proof. |

## GuardedOperationData

Returned by OAuth writes and [operation status](/api-reference/operations).

```json theme={null}
{
  "mode": "preview",
  "operation": "create_event",
  "org_id": 903,
  "event_id": null,
  "review_token": "ddc661a7-8861-4793-9437-af42a82d12f8",
  "expires_at": "2026-10-05T10:15:00+00:00",
  "proposed": {
    "name": "Race Photography 2026",
    "client_enabled": false
  },
  "consequences": [
    "Creates an unpublished draft."
  ],
  "operation_id": null,
  "status": "preview",
  "result": null
}
```

| Field | Type | Description |
| - | - | - |
| `mode` | string | preview or execute. |
| `operation` | string | Product operation name. |
| `org_id` | integer | Organiser ID. |
| `event_id` | integer \| null | Event ID where applicable. |
| `review_token` | string \| null | Expiring preview token; null for operation status. |
| `expires_at` | string \| null | Review expiry timestamp; null for operation status. |
| `proposed` | object | Exact proposed action. |
| `consequences` | string\[] | Effects of the action, to show the user. |
| `operation_id` | string \| null | Durable operation UUID after execution. |
| `status` | string | preview, pending, queued, running, completed, failed or dispatch\_unknown. |
| `result` | object \| null | Operation result, when available. |

## PhotoSourceItem

One configured source from [Photo Sources](/api-reference/photo-sources).

```json theme={null}
{
  "source_id": 1,
  "name": "9Pic Storage",
  "provider": "9pic_storage",
  "url": null,
  "status": "new"
}
```

| Field | Type | Description |
| - | - | - |
| `source_id` | integer | Source identifier. |
| `name` | string | Display name. |
| `provider` | string | 9pic\_storage, googledrive, dropbox, onedrive or sharepoint. |
| `url` | string \| null | Shared-folder link; null for 9Pic Storage. |
| `status` | string | Current source import state. |

## PhotoSourcesData

List result from [Photo Sources](/api-reference/photo-sources).

```json theme={null}
{
  "event_id": 456,
  "sources": [
    {
      "source_id": 1,
      "name": "9Pic Storage",
      "provider": "9pic_storage",
      "url": null,
      "status": "new"
    }
  ],
  "total": 1
}
```

| Field | Type | Description |
| - | - | - |
| `event_id` | integer | Event ID. |
| `sources` | PhotoSourceItem\[] | Configured supported sources. |
| `total` | integer | Number of returned sources. |

## ParticipantSearchData

Read result from [Participant Search](/api-reference/participant-search).

```json theme={null}
{
  "event_id": 456,
  "bib_search": false,
  "selfie_search": false,
  "context_search": false,
  "readiness": "unknown",
  "processing_required": false
}
```

| Field | Type | Description |
| - | - | - |
| `event_id` | integer | Event ID. |
| `bib_search` | boolean | BIB search setting. |
| `selfie_search` | boolean | Selfie search setting. |
| `context_search` | boolean | Context search setting. |
| `readiness` | string | Always unknown; settings do not prove index readiness. |
| `processing_required` | boolean | Search settings may require indexing. |

## AnalyticsDateRange

Date boundaries in [Event Analytics](/api-reference/event-analytics).

```json theme={null}
{
  "start_date": "2026-10-01",
  "end_date": "2026-10-05",
  "event_start_date": "2026-10-01"
}
```

| Field | Type | Description |
| - | - | - |
| `start_date` | string | Inclusive start date. |
| `end_date` | string | Inclusive end date. |
| `event_start_date` | string | Local event date. |

## AnalyticsTrendItem

One available daily aggregate in [Event Analytics](/api-reference/event-analytics).

```json theme={null}
{
  "date": "2026-10-01",
  "metrics": {}
}
```

| Field | Type | Description |
| - | - | - |
| `date` | string | Local calendar date. |
| `metrics` | object | Available metric name to integer estimated count. |

## EventAnalyticsData

Aggregate result from [Event Analytics](/api-reference/event-analytics).

```json theme={null}
{
  "event_id": 456,
  "date_range": {
    "start_date": "2026-10-01",
    "end_date": "2026-10-05",
    "event_start_date": "2026-10-01"
  },
  "timezone": "Asia/Kolkata",
  "summary": {},
  "daily_trend": [],
  "estimated": true,
  "availability": "unavailable",
  "unavailable_dates": [
    "2026-10-01",
    "2026-10-02",
    "2026-10-03",
    "2026-10-04",
    "2026-10-05"
  ],
  "live_available": false,
  "unavailable_reason": "Engagement data is unavailable for the requested dates."
}
```

| Field | Type | Description |
| - | - | - |
| `event_id` | integer | Event ID. |
| `date_range` | AnalyticsDateRange | Effective dates. |
| `timezone` | string | Always Asia/Kolkata. |
| `summary` | object | Metric name to integer count; estimates, not unique participants. |
| `daily_trend` | AnalyticsTrendItem\[] | Available daily counts. |
| `estimated` | boolean | Always true; not billing data. |
| `availability` | string | available, partial or unavailable. |
| `unavailable_dates` | string\[] | Dates without authoritative data. |
| `live_available` | boolean \| null | Whether current-day data was obtained. |
| `unavailable_reason` | string \| null | Availability explanation. |

## EventLocationRequest

Optional location for [Create Event](/api-reference/create-event). Omission uses Remote.

```json theme={null}
{"city":"Pune","state":"Maharashtra","country":"India","lat":18.52,"lng":73.85}
```

| Field | Type | Description |
| - | - | - |
| `city` | string | Required nonblank city, up to 200 characters. |
| `state`, `country`, `place_id` | string | Optional; default empty, up to 200 characters. |
| `formatted_address` | string | Optional; default empty, up to 500 characters. |
| `lat`, `lng` | number | Optional; default zero; latitude -90 to 90, longitude -180 to 180. |

## CreateEventRequest

Write controls plus event inputs for [Create Event](/api-reference/create-event).

```json theme={null}
{"mode":"execute","idempotency_key":"create-race-photography-2026","name":"Race Photography 2026","event_date":"2026-11-05T08:00:00+05:30","event_type":"running"}
```

| Field | Type | Description |
| - | - | - |
| Write controls | ReviewedWriteRequest | `mode` and `idempotency_key`; see above. |
| `name` | string | Required nonblank, up to 1000 characters. |
| `event_date` | string | Required explicit-timezone ISO timestamp, up to 100 characters. |
| `event_type` | string | running, marriage, conference or general. |
| `bib_search`, `selfie_search` | boolean | Default false. BIB is forced off for non-running events. |
| `location_data` | EventLocationRequest \| null | Optional location. |

## AddPhotoSourceRequest

Write controls plus a shared source for [Photo Sources](/api-reference/photo-sources).

```json theme={null}
{"mode":"execute","idempotency_key":"event-456-source-race-photos","name":"Race photos","provider":"googledrive","url":"https://drive.google.com/drive/folders/example-folder"}
```

| Field | Type | Description |
| - | - | - |
| Write controls | ReviewedWriteRequest | `mode` and `idempotency_key`; see above. |
| `name` | string | Required nonblank, up to 100 characters. |
| `provider` | string | googledrive, dropbox, onedrive or sharepoint. |
| `url` | string | Supported HTTPS shared-folder URL, up to 1000 characters. |

## ParticipantSearchRequest

Write controls plus supplied changes for [Participant Search](/api-reference/participant-search).

```json theme={null}
{"mode":"execute","idempotency_key":"event-456-bib-on","bib_search":true}
```

| Field | Type | Description |
| - | - | - |
| Write controls | ReviewedWriteRequest | `mode` and `idempotency_key`; see above. |
| `bib_search`, `selfie_search` | boolean \| null | At least one change required; omitted values remain unchanged. |

## ReviewedProcessRequest

Review controls plus a bounded run request for [Process Photos](/api-reference/pipeline/photos/process).

```json theme={null}
{"mode":"preview","count":10}
```

| Field | Type | Description |
| - | - | - |
| Review controls | ReviewedWriteRequest | Preview first, then execute with `review_token`, `confirmed: true` and `idempotency_key`. |
| `count` | positive integer | Required maximum photos for this run. Effective count is capped by available unprocessed photos. |

## Used By

* [Create Event](/api-reference/create-event)
* [Photo Sources](/api-reference/photo-sources)
* [Participant Search](/api-reference/participant-search)
* [Event Analytics](/api-reference/event-analytics)
* [Operations](/api-reference/operations)
* Photo pipeline [Import](/api-reference/pipeline/photos/import), [Process](/api-reference/pipeline/photos/process), [Go Live](/api-reference/pipeline/photos/go-live), and [Unpublish](/api-reference/pipeline/photos/unpublish).


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