Media Moana API Reference

List media files

Retrieves paginated list of media files with filtering by type. USE THIS WHEN: - Listing media for a specific view (all, folder, trash, favorites, published) - Searching media by text DO NOT USE WHEN: - Retrieving a single media by ID → use GET /api/v1/medias/{id}

Get media by ID

Retrieves a single media file by its ID. USE THIS WHEN: - Loading media details for a detail view or editor - Resolving a known media ID DO NOT USE WHEN: - Listing media → use GET /api/v1/medias

Update media

Updates media properties (currently supports renaming). USE THIS WHEN: - Renaming a single media file DO NOT USE WHEN: - Updating multiple media properties (favorite, trash, publish) → use POST /api/v1/medias/update - Moving media to a folder → use POST /api/v1/medias/update

Delete a media file permanently

Permanently deletes a single media file and moves its storage objects to trash. USE THIS WHEN: - Permanently removing one media file by ID DO NOT USE WHEN: - Deleting multiple media files at once → use POST /api/v1/medias/delete - Moving media to trash (soft delete) → use POST /api/v1/medias/update with trashed=true

Batch clone media files

Creates duplicates of multiple media files with new IDs, duplicating storage objects and metadata. USE THIS WHEN: - Duplicating one or more media files DO NOT USE WHEN: - Processing media with presets → use POST /api/v1/jobs with type "process"

Batch delete media files permanently

Permanently deletes multiple media files and moves their storage objects to trash. USE THIS WHEN: - Permanently deleting specific media files by IDs - Emptying the trash (set deleteAll=true) DO NOT USE WHEN: - Moving media to trash (soft delete) → use POST /api/v1/medias/update with trashed=true

Finalize file uploads

Completes the upload process for one or more files by creating new media records or replacing existing ones. USE THIS WHEN: - Finalizing file uploads after uploading to staged URLs (supports both single and batch) - Replacing an existing media file (set mediaId on the request item) DO NOT USE WHEN: - Staging the upload → use POST /api/v1/medias/stage-upload

Stage file upload

Generates pre-signed upload URLs for file uploads. Checks storage limits and detects duplicate files by SHA1 hash. USE THIS WHEN: - Initiating a new file upload (call this first, then upload to the returned URL, then call finish-upload) DO NOT USE WHEN: - Finalizing an upload → use POST /api/v1/medias/finish-upload

Batch update media properties

Updates favorite, published, trashed status, and folder location for multiple media files. USE THIS WHEN: - Toggling favorite, published, or trashed status for one or more media - Moving media files to a different folder - Restoring media from trash DO NOT USE WHEN: - Renaming a single media → use PUT /api/v1/medias/{id} - Permanently deleting media → use POST /api/v1/medias/delete

Get folder tree

Retrieves the complete folder hierarchy tree for the user, including nested structure. USE THIS ENDPOINT WHEN: - Displaying the folder navigation tree - Getting the full folder structure for a user DO NOT USE WHEN: - Listing media in a specific folder → use GET /api/v1/medias?queryType=FOLDER&value={folderId}

Create new folder

Creates a new folder under a parent folder. Validates folder name and checks for conflicts. USE THIS ENDPOINT WHEN: - Creating a new folder in the user's folder hierarchy - Organizing media into a new subfolder DO NOT USE WHEN: - Moving media to an existing folder → use POST /api/v1/medias/update - Renaming or moving a folder → use PUT /api/v1/folders/{id}

Update folder

Updates folder name or moves folder to a different parent. Validates naming conflicts and prevents circular references. USE THIS ENDPOINT WHEN: - Renaming a folder - Moving a folder to a different parent folder - Renaming and moving a folder in one operation DO NOT USE WHEN: - Creating a new folder → use POST /api/v1/folders - Deleting a folder → use DELETE /api/v1/folders/{id}

Delete folder

Deletes folder and all descendant folders, trashing all media files contained within. USE THIS ENDPOINT WHEN: - Removing a folder and its entire subtree - Cleaning up unused folder hierarchy DO NOT USE WHEN: - Moving media out of a folder → use POST /api/v1/medias/update - Renaming a folder → use PUT /api/v1/folders/{id}

Get all presets

Returns all presets for the authenticated user merged with built-in presets. USE THIS WHEN: - Listing presets for selection or display in the UI DO NOT USE WHEN: - Retrieving a single preset by slug → use GET /api/v1/presets/{slug} FILTER: - Omit the filter parameter (default) to return both built-in and user presets. - filter=builtin returns only built-in presets. - filter=user returns only the authenticated user's own presets.

Create new preset

Creates a new processing preset with specified pipeline configuration. USE THIS WHEN: - Saving a new user-defined processing preset DO NOT USE WHEN: - Duplicating an existing preset → use POST /api/v1/presets/clone - Importing presets from a file → use POST /api/v1/presets/import LIMITS: - Each user may own at most 1000 presets. Built-in presets do not count toward this limit. - Returns 422 RESOURCE_LIMIT_EXCEEDED if creating would exceed the cap.

Get preset by slug

Retrieves a specific preset's configuration by its slug. USE THIS WHEN: - Loading a single preset for editing or display - Resolving a known preset slug (including builtin- prefixed slugs) DO NOT USE WHEN: - Listing all presets → use GET /api/v1/presets

Update preset

Updates an existing user-owned preset. Built-in presets cannot be modified. USE THIS WHEN: - Saving changes to a user-created preset DO NOT USE WHEN: - Modifying a built-in preset → clone it first with POST /api/v1/presets/clone

Delete preset

Deletes a single user-owned preset. Built-in presets cannot be deleted. USE THIS WHEN: - Deleting one preset by slug DO NOT USE WHEN: - Deleting multiple presets → use POST /api/v1/presets/delete

Clone presets

Creates copies of existing presets (built-in or user-owned) with a ' (copy)' suffix. USE THIS WHEN: - Making an editable copy of a built-in preset - Duplicating user-owned presets DO NOT USE WHEN: - Creating a brand-new preset from scratch → use POST /api/v1/presets LIMITS: - Each user may own at most 1000 presets. Cloning is rejected (422 RESOURCE_LIMIT_EXCEEDED) if the result would exceed the cap.

Batch delete presets

Deletes multiple user-owned presets in one call. USE THIS WHEN: - Deleting several presets at once (e.g. after a table selection) DO NOT USE WHEN: - Deleting a single preset → use DELETE /api/v1/presets/{slug} - Trying to delete built-in presets (returns 403)

Import presets

Imports a list of presets, assigning them to the current user. USE THIS WHEN: - Restoring presets from a JSON export file DO NOT USE WHEN: - Creating a single preset → use POST /api/v1/presets - Duplicating existing presets → use POST /api/v1/presets/clone LIMITS: - Each user may own at most 1000 presets. Import is rejected (422 RESOURCE_LIMIT_EXCEEDED) if it would exceed the cap.

List AI presets

Returns all AI presets for the authenticated user merged with built-in presets. USE THIS WHEN: - Listing presets for selection or display in the UI - Separating image-generation presets from everything else DO NOT USE WHEN: - Retrieving a single preset by slug → use GET /api/v1/ai-presets/{slug} MODE: - mode=ai_image returns only image-generation presets. - mode=chat or omitting the parameter returns all chat presets. FILTER: - Omit the filter parameter (default) to return both built-in and user presets. - filter=builtin returns only built-in presets. - filter=user returns only the authenticated user's own presets.

Create AI preset

Creates a new AI preset with model, prompt, and optional schema. USE THIS WHEN: - Saving a new user-defined AI preset configuration DO NOT USE WHEN: - Duplicating an existing preset → use POST /api/v1/ai-presets/clone - Importing presets from a file → use POST /api/v1/ai-presets/import LIMITS: - Each user may own at most 1000 AI presets. Built-in presets do not count toward this limit. - Returns 422 RESOURCE_LIMIT_EXCEEDED if creating would exceed the cap.

Get AI preset by slug

Retrieves a specific AI preset including enriched model metadata. USE THIS WHEN: - Loading a single preset for editing or display - Resolving a known preset slug (including builtin- prefixed slugs) DO NOT USE WHEN: - Listing all presets → use GET /api/v1/ai-presets

Update AI preset

Updates an existing user-owned AI preset. Built-in presets cannot be modified. USE THIS WHEN: - Saving changes to a user-created preset DO NOT USE WHEN: - Modifying a built-in preset → clone it first with POST /api/v1/ai-presets/clone

Delete AI preset

Deletes a single user-owned AI preset. Built-in presets cannot be deleted. USE THIS WHEN: - Deleting one preset by slug DO NOT USE WHEN: - Deleting multiple presets → use POST /api/v1/ai-presets/delete

Clone AI presets

Creates copies of existing presets (built-in or user-owned) with a ' (copy)' suffix. USE THIS WHEN: - Making an editable copy of a built-in preset - Duplicating user-owned presets DO NOT USE WHEN: - Creating a brand-new preset from scratch → use POST /api/v1/ai-presets LIMITS: - Each user may own at most 1000 AI presets. Cloning is rejected (422 RESOURCE_LIMIT_EXCEEDED) if the result would exceed the cap.

Batch delete AI presets

Deletes multiple user-owned AI presets in one call. USE THIS WHEN: - Deleting several presets at once (e.g. after a table selection) DO NOT USE WHEN: - Deleting a single preset → use DELETE /api/v1/ai-presets/{slug} - Trying to delete built-in presets (returns 403)

Import AI presets

Imports a list of AI presets, assigning them to the current user. USE THIS WHEN: - Restoring presets from a JSON export file DO NOT USE WHEN: - Creating a single preset → use POST /api/v1/ai-presets - Duplicating existing presets → use POST /api/v1/ai-presets/clone LIMITS: - Each user may own at most 1000 AI presets. Import is rejected (422 RESOURCE_LIMIT_EXCEEDED) if it would exceed the cap.

Get available AI models

Returns the merged list of available AI models from all providers and OpenRouter. Provider-configured models take priority over OpenRouter duplicates. USE THIS WHEN: - Populating a model selection dropdown - Checking which models are available for a given mode DO NOT USE WHEN: - You already have a model ID and need its details → look it up in the list

List automations

Returns all automations for the authenticated user, including built-in automations. Built-in automations appear first with builtIn=true. Their enabled state is per-user. USE THIS ENDPOINT WHEN: - Displaying the user's automation dashboard - Checking which automations are active - Finding an automation slug for clone/update operations FILTER: - Omit the filter parameter (default) to return both built-in and user automations. - filter=builtin returns only built-in automations (including user overrides of them). - filter=user returns only the authenticated user's own automations.

Create automation

Creates a new automation with trigger, action (including output mode), and configuration. USE THIS ENDPOINT WHEN: - Setting up a new automation rule (cron-scheduled or event-driven) - Automating AI analysis, image processing, or media publishing pipelines DO NOT USE WHEN: - Duplicating an existing or built-in automation → use POST /api/v1/automations/{slug}/clone Trigger types: "cron" (scheduled) or "event" (fires when media processing completes). Media target filter (in trigger): optional folderId narrows target media for cron runs and event-triggered media matching. Origin filter (event triggers only, in trigger): includeOrigins list controls which media origins trigger the automation. Valid values: upload, edit, job, automation, session. Default (null): ["upload", "edit", "job", "session"]. Rejected for cron triggers. Action types: "image_ai_preset", "chat_ai_preset", or "processing_preset" (reference a preset by ID). Action outputMode: "new_media" or "replace_media". Optional for chat_ai_preset (structured output is written as media metadata automatically). Action targetFolderId: optional destination folder for output media. LIMITS: - Each user may own at most 100 automations. Built-in automations do not count toward this limit. - Returns 422 RESOURCE_LIMIT_EXCEEDED if creating would exceed the cap.

Get automation by slug

Returns full automation configuration including trigger and action (with output mode). Supports both user-created and built-in automation slugs. USE THIS ENDPOINT WHEN: - Viewing automation details before editing or cloning - Checking a specific automation's configuration and scheduling state DO NOT USE WHEN: - Listing all automations → use GET /api/v1/automations

Update automation

Updates all fields of an existing user-created automation. Built-in automations cannot be modified — clone first. USE THIS ENDPOINT WHEN: - Modifying trigger schedule, folder targeting, action preset, or output mode - Re-configuring a automation after testing DO NOT USE WHEN: - Only toggling enabled/disabled → use POST /api/v1/automations/{slug}/enable - Modifying a built-in automation → clone it first with POST /api/v1/automations/{slug}/clone

Delete automation

Permanently deletes a user-created automation. Built-in automations cannot be deleted — disable instead. USE THIS ENDPOINT WHEN: - Removing a single automation that is no longer needed DO NOT USE WHEN: - Deleting multiple automations at once → use POST /api/v1/automations/delete - Temporarily pausing an automation → use POST /api/v1/automations/{slug}/enable with enabled=false

Clone automation

Creates an editable copy of an existing automation (user-created or built-in). The clone is created in disabled state with " (Copy)" appended to the name. USE THIS ENDPOINT WHEN: - Customizing a built-in automation (built-ins are read-only, so clone first) - Duplicating an automation to create a variation with different settings DO NOT USE WHEN: - Creating an automation from scratch → use POST /api/v1/automations LIMITS: - Each user may own at most 100 automations. Cloning is rejected (422 RESOURCE_LIMIT_EXCEEDED) if the result would exceed the cap.

Enable or disable automation

Toggles an automation's enabled state. Works for both user-created and built-in automations. For cron automations, enabling computes the next run time; disabling clears it. For built-in automations, enabling creates an overwrite record in the database. USE THIS ENDPOINT WHEN: - Activating or pausing an automation without modifying its configuration - Opting into a built-in automation (built-in automations are disabled by default) DO NOT USE WHEN: - Changing automation configuration → use PUT /api/v1/automations/{slug}

Manually trigger automation

Manually triggers an automation, creating a job. Event-triggered automations cannot be triggered manually. USE THIS ENDPOINT WHEN: - Testing an automation before enabling its schedule - Running a cron automation on-demand outside its schedule DO NOT USE WHEN: - The automation is event-triggered (returns 400)

Batch delete automations

Deletes multiple user-created automations by slug. Built-in automation slugs are rejected. USE THIS ENDPOINT WHEN: - Cleaning up multiple obsolete automations at once DO NOT USE WHEN: - Deleting a single automation → use DELETE /api/v1/automations/{slug}

List jobs

Returns paginated jobs for the authenticated user, sorted by creation date descending. Optionally filter by status, type, triggerType, and automationId. Any missing parameter means no filter on that field. USE THIS WHEN: - Displaying the jobs list page - Polling for active job status updates - Filtering jobs by status, type, trigger type, or automation DO NOT USE WHEN: - Retrieving a single job by ID → use GET /api/v1/jobs/{id}

Submit a new job

Submits an async job for processing. Supports four job types: ai-generate (default): Text-to-image or image-to-image generation with AI. - Input: mediaIds for image-to-image, or count for text-to-image ai-edit: AI image editing, writing output as new media or replacing the source. - Input: mediaIds (required) and mode (NEW_MEDIA or REPLACE_MEDIA) parse: AI-powered media analysis using the user's Smart Analysis config. - Input: mediaIds (required) — analyzes each media and updates its parseInfo process: Preset-based media processing pipeline (non-AI transformations). - Input: mediaIds (required), presetId (required), and mode (NEW_MEDIA or REPLACE_MEDIA) USE THIS WHEN: - Generating, editing, or processing media in bulk - Bulk parsing/analyzing media metadata with AI DO NOT USE WHEN: - Generating a single image interactively → use POST /api/v1/sessions/generate

Get job detail

Returns job with per-item results. USE THIS WHEN: - Viewing detailed job status and individual item results - Checking progress of a specific job DO NOT USE WHEN: - Listing all jobs → use GET /api/v1/jobs

Delete a job

Permanently deletes a single terminal job (COMPLETED, FAILED, CANCELLED). DO NOT USE WHEN: - Deleting multiple jobs at once → use POST /api/v1/jobs/delete - Cancelling a running job → use POST /api/v1/jobs/{id}/cancel

Cancel a job

Cancels a pending/submitted/processing job and refunds unused credits. USE THIS WHEN: - User wants to stop a running or queued job - Reclaiming credits from an unwanted job DO NOT USE WHEN: - Job is already completed, failed, or cancelled → returns 409

Resume incomplete items in a job

Creates a new job from the incomplete (FAILED or CANCELLED) items of a failed/cancelled job, reusing the original configuration (model, prompt, parameters, preset). The new job is linked to the original via parentJobId and shares a stable rootJobId with every attempt in the chain, and attemptNumber advances by 1. Clients that want to show a single logical job can group by rootJobId. USE THIS WHEN: - Retrying only the failed items of a partially-successful job without resubmitting the whole batch DO NOT USE WHEN: - Submitting a fresh job → use POST /api/v1/jobs - The source job has no FAILED or CANCELLED items (returns 400) - This isn't the latest attempt in the chain (returns 422 with code NOT_LATEST_ATTEMPT) - The job has already been resumed the maximum allowed times (returns 422 with code RESUME_LIMIT_EXCEEDED)

Batch delete jobs

Permanently deletes multiple terminal jobs (COMPLETED, FAILED, CANCELLED). DO NOT USE WHEN: - Deleting a single job → use DELETE /api/v1/jobs/{id} - Cancelling running jobs → use POST /api/v1/jobs/{id}/cancel