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

# Create Event

> Create an unpublished organiser event in one call.

## Overview

Create an unpublished event with the same defaults as the dashboard's Create Event form. Creation does not import, process, publish, or consume credits.

| Setting | Default |
| - | - |
| Selfie search | On |
| BIB search | On for `running` events; always off for other event types |
| Show all photos, timeline, bulk download, total photo count | On |
| Name search, original-photo storage | Off |
| Visibility | Public; Trial organisers' events are always private |

With BIB or selfie search on, [Process](/api-reference/pipeline/photos/process) uses 1 credit per photo. Send `false` to turn either off, or change it later with [Event Settings](/api-reference/event-settings). The response's `consequences` state the credit balance and any Trial privacy rule; [Plan](/api-reference/plan) lists every plan limit.

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

## Endpoint

```
POST /api/v1/ext/{org_id}/events
```

## Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `org_id` | integer | Yes | Organiser where the caller has an accepted membership. |

## Request Body

| Field | Type | Description |
| - | - | - |
| `name` | string | Required nonblank event name, up to 1000 characters. |
| `event_date` | string | Required ISO 8601 timestamp with explicit timezone. |
| `event_type` | string | Required: `running`, `marriage`, `conference`, or `general`. |
| `bib_search`, `selfie_search` | boolean | Optional. Omit for the dashboard defaults above; `false` turns the search off. |
| `location_data` | object | Optional. Requires `city`; accepts `state`, `country`, `formatted_address`, `place_id`, `lat`, `lng`. Omission uses Remote. |
| `mode` | string | `execute` to create the event; `preview` (the default) is a dry run. |
| `idempotency_key` | string | Required with `execute`; stable retry key. See [ReviewedWriteRequest](/api-reference/models/workflow#reviewedwriterequest). |

This write runs in one call: send `mode: "execute"` with a stable `idempotency_key`. No review token or confirmation is needed. `mode: "preview"` remains available as an optional dry run that returns `proposed` and `consequences` without changing anything. See [Operations](/api-reference/operations) for retry rules and status tracking.

## Example Request

```bash cURL theme={null}
curl -i -X POST \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "Content-Type: application/json" \
  "https://api.9pic.ai/api/v1/ext/903/events" \
  -d '{"mode": "execute", "idempotency_key": "create-race-photography-2026", "name": "Race Photography 2026", "event_date": "2026-11-05T08:00:00+05:30", "event_type": "running"}'
```

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

response = requests.post(
    "https://api.9pic.ai/api/v1/ext/903/events",
    headers={"Authorization": "Bearer <oauth_access_token>"},
    json={'mode': 'execute', 'idempotency_key': 'create-race-photography-2026', 'name': 'Race Photography 2026', 'event_date': '2026-11-05T08:00:00+05:30', 'event_type': 'running'},
)
print(response.status_code, response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.9pic.ai/api/v1/ext/903/events", {
  method: "POST",
  headers: { "Authorization": "Bearer <oauth_access_token>", "Content-Type": "application/json" },
  body: JSON.stringify({"mode": "execute", "idempotency_key": "create-race-photography-2026", "name": "Race Photography 2026", "event_date": "2026-11-05T08:00:00+05:30", "event_type": "running"}),
});
console.log(await response.json());
```

## Example Response

```json theme={null}
{
  "responseType": "success",
  "message": "Event created",
  "data": {
    "mode": "execute",
    "operation": "create_event",
    "org_id": 903,
    "event_id": 789,
    "review_token": null,
    "expires_at": null,
    "proposed": {
      "name": "Race Photography 2026",
      "event_date": "2026-11-05T08:00:00+05:30",
      "event_type": "running",
      "bib_search": true,
      "selfie_search": true,
      "location_data": null,
      "show_all_images": true,
      "timeline_search": true,
      "bulk_download": true,
      "show_total_photos_count": true,
      "name_search": false,
      "visibility": "public",
      "client_enabled": false,
      "compress_and_upload": true,
      "store_original_memories": false
    },
    "consequences": [
      "Creates an unpublished draft and a default 9Pic Storage source.",
      "Does not import, process, publish, or consume credits.",
      "BIB search and Selfie search on: processing will use 1 credit per photo (240 credits available)."
    ],
    "operation_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "completed",
    "result": {
      "event_id": 789,
      "event_name": "Race Photography 2026",
      "event_slug": "race-photography-2026",
      "client_enabled": false
    }
  }
}
```

## Response Models

[GuardedOperationData](/api-reference/models/workflow#guardedoperationdata), inside the standard envelope.

## Error Responses

| Status | Meaning |
| - | - |
| `400` / `422` | Invalid input or missing `idempotency_key` at execution. |
| `401` | Invalid or expired access token. |
| `403` | Missing scopes, membership, admin role, or entitlement. |
| `404` | Event configuration or caller-owned operation not found. |
| `409` | Retry key reused for a different action, duplicate source, active work, or state conflict. |
| `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.