Create Event

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 uses 1 credit per photo. Send false to turn either off, or change it later with Event Settings. The response’s consequences state the credit balance and any Trial privacy rule; 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.

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 for retry rules and status tracking.

Example Request

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"}'

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())

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

{
  "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, 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 and Conventions.

Get Started

Events

Memories

Browse Photos

Search

Video

Downloads

Pipeline

Webhooks

Models

Overview

Endpoint

Path Parameters

Request Body

Example Request

Example Response

Response Models

Error Responses

​Overview

​Endpoint

​Path Parameters

​Request Body

​Example Request

​Example Response

​Response Models

​Error Responses

Overview

Endpoint

Path Parameters

Request Body

Example Request

Example Response

Response Models

Error Responses