Operations

Overview

OAuth writes run as durable operations. The API rechecks scopes, accepted admin membership, operation fields and current state on every call. Every execution needs a stable idempotency_key; completed retry records are kept for 30 days.

Write	Protocol
Create Event, Rename Event, Event Settings, Photo Sources, Participant Search, Import, Go Live, Unpublish	Direct: one call with `mode: "execute"` and `idempotency_key`.
Process Photos	Reviewed: spends credits, so it needs a preview and user confirmation.

Any write accepts mode: "preview" as a dry run that returns proposed and consequences without changing anything.

Direct Writes

Send the operation fields with mode: "execute" and a stable idempotency_key. No review_token or confirmed is needed. Save the returned operation_id. Go Live makes the event live for participants; tell the user before calling it. Unpublish moves it back to draft.

Reviewed Writes

confirmed: true is the client’s assertion that the user approved the exact preview, including the credits it uses. It is not backend proof of human presence.

Submit the operation fields with mode: "preview".
Show the user proposed.effective_count and proposed.credits_consumed.
After confirmation, repeat the same fields with mode: "execute", the returned review_token, confirmed: true and a stable idempotency_key.
Reviews expire after 15 minutes. A changed payload or event state requires a fresh preview.

Retries

After an ambiguous timeout, query the recorded operation or repeat the identical execution with the same retry key. Do not invent a new key. Reusing a key for a different action returns 409. Pending or queued means accepted, not completed. dispatch_unknown requires status checks and support review before another operation; do not infer failure from an uncertain dispatch.

Endpoint

GET /api/v1/ext/{org_id}/operations/{operation_id}

OAuth only, requiring events:read and accepted membership. Operations are scoped to the signed-in principal as well as the organiser: another user cannot read them even with the same organisation membership.

Path Parameters

Parameter	Type	Required	Description
`org_id`	integer	Yes	Authorised organiser.
`operation_id`	UUID	Yes	Durable ID returned by execution.

Example Request

curl -i -X GET \
  -H "Authorization: Bearer <oauth_access_token>" \
  "https://api.9pic.ai/api/v1/ext/903/operations/ddc661a7-8861-4793-9437-af42a82d12f8"

import requests

response = requests.get(
    "https://api.9pic.ai/api/v1/ext/903/operations/ddc661a7-8861-4793-9437-af42a82d12f8",
    headers={"Authorization": "Bearer <oauth_access_token>"},
)
print(response.status_code, response.json())

const response = await fetch("https://api.9pic.ai/api/v1/ext/903/operations/ddc661a7-8861-4793-9437-af42a82d12f8", {
  method: "GET",
  headers: { "Authorization": "Bearer <oauth_access_token>" },
});
console.log(await response.json());

Example Response

{
  "responseType": "success",
  "message": "Records",
  "data": {
    "mode": "execute",
    "operation": "process_photos",
    "org_id": 903,
    "event_id": 456,
    "review_token": null,
    "expires_at": null,
    "proposed": {
      "requested_count": 10,
      "effective_count": 10,
      "credits_consumed": 10
    },
    "consequences": [
      "Processes up to 10 photos and reserves 10 credits."
    ],
    "operation_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "pending",
    "result": {
      "event_id": 456
    }
  }
}

Operation States

State	Meaning
`preview`	Review available; no operation executed.
`pending`	Accepted and awaiting dispatch.
`queued`	Dispatched for background work.
`running`	Work has started.
`completed`	Operation completed.
`failed`	Recorded failure; inspect status before retrying.
`dispatch_unknown`	Delivery outcome is uncertain; requires reconciliation.

Response Models

ReviewedWriteRequest and GuardedOperationData.

Error Responses

Status	Meaning
`400` / `422`	Invalid input, missing `idempotency_key`, or missing review fields for Process Photos.
`401`	Invalid or expired access token.
`402`	Not enough credits for Process Photos; the message lists the plan’s options.
`403`	Missing scopes, membership, admin role, or a plan limit (see Plan).
`404`	Event configuration or caller-owned operation not found.
`409`	Expired or mismatched review, retry key reused for another action, changed state, duplicate source, or active work.
`503`	Organiser writes are temporarily unavailable.

See Errors and Conventions.

Get Started

Events

Memories

Browse Photos

Search

Video

Downloads

Pipeline

Webhooks

Models

Overview

Direct Writes

Reviewed Writes

Retries

Endpoint

Path Parameters

Example Request

Example Response

Operation States

Response Models

Error Responses

​Overview

​Direct Writes

​Reviewed Writes

​Retries

​Endpoint

​Path Parameters

​Example Request

​Example Response

​Operation States

​Response Models

​Error Responses

Overview

Direct Writes

Reviewed Writes

Retries

Endpoint

Path Parameters

Example Request

Example Response

Operation States

Response Models

Error Responses