{ "openapi": "3.1.0", "info": { "title": "Story0 API", "version": "2026-11-01", "description": "Video decisions for media teams. Upload a video, ask for an outcome, and get typed results with timecoded evidence. Processing is asynchronous: create calls return a job; `job.succeeded` fires when the result exists.", "contact": { "name": "Story0", "url": "https://dev.story0.com" } }, "servers": [ { "url": "https://api.story0.com" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from the console: `s0_live_…` (billed) or `s0_test_…` (fixtures, never billed)." } }, "schemas": { "Upload": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "upload" ] }, "status": { "type": "string", "enum": [ "pending", "completed", "expired" ] }, "upload_url": { "type": "string", "description": "PUT the file bytes here with the listed headers." }, "method": { "type": "string", "enum": [ "PUT" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "chunk_size_multiple": { "type": "integer", "description": "Chunked uploads send `Content-Range` chunks in multiples of this size (except the last)." }, "expires_at": { "type": "string" }, "asset_id": { "type": [ "string", "null" ] } }, "required": [ "id", "object", "status", "upload_url", "method", "headers", "chunk_size_multiple", "expires_at", "asset_id" ], "description": "A resumable upload session. PUT the whole file to `upload_url`, or send chunks with `Content-Range: bytes a-b/total` (308 means continue). `Content-Range: bytes */total` reports what was stored, so an interrupted upload resumes." }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "code", "request_id" ], "additionalProperties": {}, "description": "RFC 9457 problem details. Branch on `code`." }, "Asset": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "asset" ] }, "status": { "type": "string", "enum": [ "processing", "ready", "failed", "deleted" ] }, "source": { "type": "string", "enum": [ "upload", "url" ] }, "filename": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "media": { "type": [ "object", "null" ], "properties": { "duration_seconds": { "type": [ "number", "null" ] }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "fps": { "type": [ "number", "null" ] }, "video_codec": { "type": [ "string", "null" ] }, "has_audio": { "type": [ "boolean", "null" ] }, "bytes": { "type": [ "number", "null" ] }, "sha256": { "type": [ "string", "null" ] } }, "required": [ "duration_seconds", "width", "height", "fps", "video_codec", "has_audio", "bytes", "sha256" ] }, "error": { "type": [ "object", "null" ], "additionalProperties": {} }, "created_at": { "type": "string" }, "ready_at": { "type": [ "string", "null" ] }, "retention": { "type": "object", "properties": { "media_expires_at": { "type": "string" } }, "required": [ "media_expires_at" ] } }, "required": [ "id", "object", "status", "source", "filename", "livemode", "media", "error", "created_at", "ready_at", "retention" ] }, "AssetList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "Job": { "type": "object", "properties": { "id": { "type": "string", "example": "job_01jbx7…" }, "object": { "type": "string", "enum": [ "job" ] }, "operation": { "type": "string", "enum": [ "screen", "segment" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "livemode": { "type": "boolean" }, "request_id": { "type": [ "string", "null" ], "description": "The request that created the job." }, "asset_id": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ] }, "progress": { "type": [ "number", "null" ] }, "result": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "object": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "id", "object", "url" ] }, "error": { "type": [ "object", "null" ], "additionalProperties": {} }, "charge": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "estimate": { "type": [ "string", "null" ] }, "max_charge": { "type": "string" }, "total": { "type": [ "string", "null" ] } }, "required": [ "currency", "estimate", "max_charge", "total" ] }, "created_at": { "type": "string" }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "object", "operation", "status", "livemode", "request_id", "asset_id", "stage", "progress", "result", "error", "charge", "created_at", "started_at", "finished_at", "metadata" ] }, "SegmentCreate": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input" }, "mode": { "type": "string", "enum": [ "partition", "extract" ], "description": "`partition` labels the whole range; `extract` returns only matching moments." }, "instruction": { "type": "string", "minLength": 3, "maxLength": 2000, "example": "Partition the whole video by whether a dog is visible." }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "minItems": 2, "maxItems": 12, "description": "Required for `partition`: the mutually exclusive states." }, "uncertainty": { "type": "object", "properties": { "label": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$", "example": "dog_visible" } }, "description": "Label used where evidence is insufficient. Default `uncertain`." }, "boundaries": { "type": "object", "properties": { "snap": { "type": "string", "enum": [ "none" ] } }, "description": "Boundary snapping. Only `none` is available today." }, "sampling": { "type": "object", "properties": { "fps": { "type": "number", "minimum": 0.1, "maximum": 4 } }, "description": "Frames per second inspected. Default: 2 up to 2 minutes, 1 up to 10, then fewer." }, "range": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "exclusiveMinimum": 0 } }, "description": "Analyse only this range, in seconds from the start." }, "constraints": { "type": "object", "properties": { "min_seconds": { "type": "number", "exclusiveMinimum": 0, "maximum": 600 }, "max_seconds": { "type": "number", "exclusiveMinimum": 0, "maximum": 3600 }, "max_segments": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "description": "`extract` only: moment length and count limits." }, "billing": { "$ref": "#/components/schemas/BillingOptions" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key-value pairs (keys up to 40 characters, values up to 500) echoed on the job." } }, "required": [ "input", "mode", "instruction" ] }, "Input": { "type": "object", "properties": { "asset_id": { "type": "string", "example": "asset_01jbx6…" }, "url": { "type": "string", "format": "uri", "example": "https://media.example.com/dog-demo.mp4" } }, "description": "Exactly one of `asset_id` (uploaded or fetched media) or `url` (a direct link to a video file)." }, "Label": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$", "example": "dog_visible" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "key", "description" ] }, "BillingOptions": { "type": "object", "properties": { "max_charge": { "$ref": "#/components/schemas/Money" } }, "description": "The total this request may cost, including any preparation. Work stops before exceeding it." }, "Money": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,6})?$" } }, "required": [ "currency", "amount" ], "example": { "currency": "USD", "amount": "0.50" } }, "ScreenCreate": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "minItems": 1, "maxItems": 20, "example": [ { "key": "animals", "description": "Animals doing something surprising or funny" }, { "key": "sports", "description": "Skilled action sports with a clear payoff" } ] }, "billing": { "$ref": "#/components/schemas/BillingOptions" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key-value pairs (keys up to 40 characters, values up to 500) echoed on the job." } }, "required": [ "input", "categories" ] }, "Segmentation": { "type": "object", "properties": { "id": { "type": "string", "example": "seg_01jbx8…" }, "object": { "type": "string", "enum": [ "segmentation" ] }, "job_id": { "type": "string" }, "asset_id": { "type": "string" }, "livemode": { "type": "boolean" }, "fixture": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "partition", "extract" ] }, "engine": { "type": "string" }, "time_unit": { "type": "string", "enum": [ "seconds" ] }, "duration_seconds": { "type": "number" }, "range": { "type": "object", "properties": { "start": { "type": "number" }, "end": { "type": "number" } }, "required": [ "start", "end" ] }, "coverage": { "type": "object", "properties": { "timeline": { "type": "string", "enum": [ "complete" ] }, "sampled_frames": { "type": "number" }, "frame_interval_seconds": { "type": "number" }, "uncertain_seconds": { "type": "number" }, "modalities": { "type": "array", "items": { "type": "string" } } }, "required": [ "timeline", "sampled_frames", "frame_interval_seconds", "uncertain_seconds", "modalities" ] }, "boundary_resolution_seconds": { "type": "number" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "start": { "type": "number" }, "end": { "type": "number" }, "label": { "type": "string" }, "title": { "type": "string" }, "review": { "$ref": "#/components/schemas/Review" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } } }, "required": [ "id", "start", "end", "label", "review", "evidence" ] } }, "config": { "type": "object", "additionalProperties": {} }, "provenance": { "type": "object", "properties": { "engine": { "type": "string" }, "analysis_reused": { "type": "boolean" }, "api_version": { "type": "string" } }, "required": [ "engine", "analysis_reused", "api_version" ] }, "receipt": { "$ref": "#/components/schemas/Receipt" }, "retention": { "type": "object", "properties": { "result_expires_at": { "type": "string" }, "media_expires_at": { "type": "string" } }, "required": [ "result_expires_at", "media_expires_at" ] }, "created_at": { "type": "string" } }, "required": [ "id", "object", "job_id", "asset_id", "livemode", "mode", "engine", "time_unit", "duration_seconds", "range", "coverage", "boundary_resolution_seconds", "segments", "config", "provenance", "receipt", "retention", "created_at" ] }, "Review": { "type": "object", "properties": { "required": { "type": "boolean", "description": "Whether a person should check this before relying on it. It says nothing about rights or permission to publish." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Why review is suggested: `insufficient_evidence`, `partly_uncertain`, `padded_to_min_seconds`, `split_at_max_seconds`, `no_frames_sampled` or `not_answered`." } }, "required": [ "required", "reasons" ] }, "Evidence": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "seen" ] }, "start": { "type": "number" }, "end": { "type": "number" }, "description": { "type": "string" } }, "required": [ "id", "kind", "start", "end", "description" ] }, "Receipt": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "total": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string" }, "amount": { "type": "string" }, "unit_price_per_minute": { "type": "string" } }, "required": [ "item", "amount", "unit_price_per_minute" ] } }, "billable_seconds": { "type": "number" }, "price_version": { "type": "string" } }, "required": [ "currency", "total", "items", "billable_seconds", "price_version" ] }, "Screening": { "type": "object", "properties": { "id": { "type": "string", "example": "scr_01jbx8…" }, "object": { "type": "string", "enum": [ "screening" ] }, "job_id": { "type": "string" }, "asset_id": { "type": "string" }, "livemode": { "type": "boolean" }, "fixture": { "type": "boolean" }, "engine": { "type": "string" }, "time_unit": { "type": "string", "enum": [ "seconds" ] }, "duration_seconds": { "type": "number" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "outcome": { "type": "string", "enum": [ "match", "no_match", "uncertain" ] }, "score": { "type": "object", "properties": { "value": { "type": "number" }, "kind": { "type": "string", "enum": [ "model_estimate" ] }, "calibrated": { "type": "boolean", "enum": [ false ] } }, "required": [ "value", "kind", "calibrated" ] }, "observation": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "seen" ] }, "start": { "type": "number" }, "end": { "type": "number" } }, "required": [ "kind", "start", "end" ] } }, "review": { "$ref": "#/components/schemas/Review" } }, "required": [ "key", "outcome", "score", "observation", "evidence", "review" ] } }, "matched": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "object", "properties": { "sampled_frames": { "type": "number" }, "modalities": { "type": "array", "items": { "type": "string" } } }, "required": [ "sampled_frames", "modalities" ] }, "config": { "type": "object", "additionalProperties": {} }, "provenance": { "type": "object", "properties": { "engine": { "type": "string" }, "analysis_reused": { "type": "boolean" }, "api_version": { "type": "string" } }, "required": [ "engine", "analysis_reused", "api_version" ] }, "receipt": { "$ref": "#/components/schemas/Receipt" }, "retention": { "type": "object", "properties": { "result_expires_at": { "type": "string" }, "media_expires_at": { "type": "string" } }, "required": [ "result_expires_at", "media_expires_at" ] }, "created_at": { "type": "string" } }, "required": [ "id", "object", "job_id", "asset_id", "livemode", "engine", "time_unit", "duration_seconds", "categories", "matched", "coverage", "config", "provenance", "receipt", "retention", "created_at" ] }, "JobList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "Estimate": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "estimate" ] }, "operation": { "type": "string", "enum": [ "screen", "segment" ] }, "billable_seconds": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "total": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string" }, "amount": { "type": "string" }, "unit_price_per_minute": { "type": "string" } }, "required": [ "item", "amount", "unit_price_per_minute" ] } }, "price_version": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "object", "operation", "billable_seconds", "currency", "total", "items", "price_version", "expires_at" ] }, "Balance": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "balance" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "available": { "type": "string" }, "held": { "type": "string" }, "credits": { "type": "integer" } }, "required": [ "object", "currency", "available", "held", "credits" ], "description": "`available` excludes holds for queued and running jobs. 100 credits = $1." }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ] }, "totals": { "type": "object", "properties": { "jobs": { "type": "integer" }, "billable_seconds": { "type": "number" }, "amount": { "type": "string" } }, "required": [ "jobs", "billable_seconds", "amount" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "operation": { "type": "string", "enum": [ "screen", "segment" ] }, "jobs": { "type": "integer" }, "billable_seconds": { "type": "number" }, "amount": { "type": "string" } }, "required": [ "date", "operation", "jobs", "billable_seconds", "amount" ] } } }, "required": [ "object", "currency", "period", "totals", "days" ] }, "PriceList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "price_list" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "price_version": { "type": "string" }, "minimum_billable_seconds": { "type": "integer" }, "operations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "per_minute": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string" }, "per_minute": { "type": "string" } }, "required": [ "item", "per_minute" ] } } }, "required": [ "per_minute", "items" ] } }, "free_credit": { "type": "string" }, "credit_packs": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "credits": { "type": "integer" } }, "required": [ "amount", "credits" ] } } }, "required": [ "object", "currency", "price_version", "minimum_billable_seconds", "operations", "free_credit", "credit_packs" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "secret": { "type": "string", "description": "Shown once, at creation. Starts with `whsec_`." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "created_at": { "type": "string" } }, "required": [ "id", "object", "url", "events", "description", "status", "created_at" ] }, "WebhookEndpointList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} }, "created_at": { "type": "string" } }, "required": [ "id", "object", "type", "data", "created_at" ] }, "WebhookDeliveryList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "delivered_at": { "type": [ "string", "null" ] } }, "required": [ "id", "object", "event_id", "event_type", "status", "attempts", "last_status", "last_error", "created_at", "delivered_at" ] }, "EventList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "Feedback": { "allOf": [ { "$ref": "#/components/schemas/FeedbackCreate" }, { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "feedback" ] }, "created_at": { "type": "string" } }, "required": [ "id", "object", "created_at" ] } ] }, "FeedbackCreate": { "type": "object", "properties": { "result_id": { "type": "string", "example": "seg_01jbx8…" }, "segment_id": { "type": "string", "description": "For segmentations: the interval the feedback is about." }, "category": { "type": "string", "description": "For screenings: the category the feedback is about." }, "kind": { "type": "string", "enum": [ "correct", "incorrect", "relabel", "note" ] }, "label": { "type": "string", "maxLength": 40, "description": "For `relabel`: the label the reviewer chose." }, "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "exclusiveMinimum": 0 }, "comment": { "type": "string", "maxLength": 2000 }, "actor": { "type": "string", "maxLength": 200, "description": "Who gave the feedback, in your own terms (an email or user id)." } }, "required": [ "result_id", "kind" ] } }, "parameters": {} }, "paths": { "/v1/uploads": { "post": { "operationId": "createUpload", "tags": [ "Assets" ], "summary": "Start an upload", "description": "Returns a short-lived URL. PUT the file bytes to it with the listed headers, then complete the upload to get an asset.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "maxLength": 255 }, "content_type": { "type": "string", "maxLength": 100, "example": "video/mp4" }, "bytes": { "type": "integer", "exclusiveMinimum": 0 } } } } } }, "responses": { "201": { "description": "Upload session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/uploads/{id}/complete": { "post": { "operationId": "completeUpload", "tags": [ "Assets" ], "summary": "Complete an upload", "description": "Creates an asset from the uploaded bytes. The asset is `processing` until its media facts are read, usually within seconds.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The new asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/assets": { "post": { "operationId": "createAsset", "tags": [ "Assets" ], "summary": "Create an asset from a URL", "description": "Fetches a direct link to a video file. Platform pages (YouTube, Instagram, TikTok) are not fetched; upload those files instead.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "maxLength": 255 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "The new asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "listAssets", "tags": [ "Assets" ], "summary": "List assets", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Assets, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetList" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/assets/{id}": { "get": { "operationId": "retrieveAsset", "tags": [ "Assets" ], "summary": "Retrieve an asset", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteAsset", "tags": [ "Assets" ], "summary": "Delete an asset's media", "description": "Deletes the stored media now. Results that already exist stay available until their own expiry.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The deleted asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/segments": { "post": { "operationId": "createSegmentation", "tags": [ "Segments" ], "summary": "Segment a video", "description": "`partition` labels every moment of the range with exactly one of your labels or `uncertain`. `extract` returns only the moments that match the instruction. Returns a job; the result is a Segmentation.", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentCreate" } } } }, "responses": { "200": { "description": "Replayed: the same idempotency key and request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "202": { "description": "Accepted: the job is queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Not enough credits, or the work would exceed `max_charge`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/screenings": { "post": { "operationId": "createScreening", "tags": [ "Screenings" ], "summary": "Screen a video against categories", "description": "Answers each category with `match`, `no_match` or `uncertain`, with the frames that support a match. Returns a job; the result is a Screening.", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenCreate" } } } }, "responses": { "200": { "description": "Replayed: the same idempotency key and request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "202": { "description": "Accepted: the job is queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Not enough credits, or the work would exceed `max_charge`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/segments/{id}": { "get": { "operationId": "retrieveSegmentation", "tags": [ "Segments" ], "summary": "Retrieve a segmentation", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The segmentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segmentation" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/screenings/{id}": { "get": { "operationId": "retrieveScreening", "tags": [ "Screenings" ], "summary": "Retrieve a screening", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The screening", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Screening" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs/{id}": { "get": { "operationId": "retrieveJob", "tags": [ "Jobs" ], "summary": "Retrieve a job", "description": "Returns the job's current state. With `wait`, the request is held for up to that many seconds and answers as soon as the job finishes, so completion is seen within a fraction of a second without rapid polling. Or listen for the `job.*` webhooks.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 30, "description": "Seconds to wait for the job to finish (0–30)." }, "required": false, "description": "Seconds to wait for the job to finish (0–30).", "name": "wait", "in": "query" } ], "responses": { "200": { "description": "The job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs": { "get": { "operationId": "listJobs", "tags": [ "Jobs" ], "summary": "List jobs", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Jobs, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs/{id}/cancel": { "post": { "operationId": "cancelJob", "tags": [ "Jobs" ], "summary": "Cancel a job", "description": "A queued job is cancelled at once and costs nothing. A running job stops at its next checkpoint; if it finishes first, it completes and is billed.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The job's current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/estimates": { "post": { "operationId": "createEstimate", "tags": [ "Billing" ], "summary": "Estimate a charge", "description": "Quotes an operation for a ready asset, or for a duration you supply.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "screen", "segment" ] }, "input": { "type": "object", "properties": { "asset_id": { "type": "string" }, "duration_seconds": { "type": "number", "exclusiveMinimum": 0 } } } }, "required": [ "operation", "input" ] } } } }, "responses": { "200": { "description": "The estimate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Estimate" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/balance": { "get": { "operationId": "retrieveBalance", "tags": [ "Billing" ], "summary": "Retrieve the balance", "responses": { "200": { "description": "The balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/usage": { "get": { "operationId": "retrieveUsage", "tags": [ "Billing" ], "summary": "Summarize usage", "description": "Live charges by day and operation. Test-mode work is never billed and is not included.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 90 }, "required": false, "name": "days", "in": "query" } ], "responses": { "200": { "description": "Usage for the period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/prices": { "get": { "operationId": "listPrices", "tags": [ "Billing" ], "summary": "List prices", "description": "The current price list. No authentication required.", "security": [], "responses": { "200": { "description": "Prices per minute of video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } } } } }, "/v1/webhook_endpoints": { "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "Story0 signs every delivery with the Standard Webhooks scheme. The signing secret is returned only here.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/story0/webhooks" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.succeeded", "job.failed", "job.cancelled", "asset.ready", "asset.failed", "ping", "*" ] }, "minItems": 1, "description": "Default: every `job.*` event." }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "The endpoint, with its secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "responses": { "200": { "description": "Endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook_endpoints/{id}": { "delete": { "operationId": "disableWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Disable a webhook endpoint", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The disabled endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook_endpoints/{id}/test": { "post": { "operationId": "testWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Queues a signed `ping` event to this endpoint only.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "The queued event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook_endpoints/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List recent deliveries", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The 50 most recent deliveries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/events": { "get": { "operationId": "listEvents", "tags": [ "Webhooks" ], "summary": "List events", "description": "Every event is recorded, whether or not an endpoint was subscribed. Use this to reconcile after downtime.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "type", "in": "query" } ], "responses": { "200": { "description": "Events, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/feedback": { "post": { "operationId": "createFeedback", "tags": [ "Feedback" ], "summary": "Record feedback on a result", "description": "Append-only. Feedback never changes the result it refers to.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackCreate" } } } }, "responses": { "201": { "description": "The recorded feedback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request is not valid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": {} }