Skip to content
Dashboard
API Reference

Changelog ​

Notable changes to the Mosaic API.

2026-10-22 ​

Added: Custom x-api-key webhook header ​

Organization owners and admins can now configure an x-api-key value in webhook settings. The key is sent alongside X-Mosaic-Signature only to the HTTPS origin approved by an owner or admin. This supports gateways that require that header, including AWS API Gateway usage plans. Other callback origins receive no gateway key. See Webhook Events for details.

2026-10-15 ​

Added: Pipeline observability and restricted API keys ​

Pipeline Observability exposes storage triggers, watched folder health, ingestion events, batch-to-run links, paginated tile/task progress, notification configurations, and delivery receipts. Run lists also accept folder, batch, storage trigger, and production filters.

Restricted API keys let owners and admins select None, Read, or Write for each entity. /whoami reports explicit scopes, and permission errors identify the missing scope with an actionable, non-retryable response. Existing unrestricted keys retain access.

2026-08-14 ​

Added: Agent list filtering ​

GET /agents now accepts two optional filters:

ParameterDescription
workspace_idReturn agents from one workspace in the API key's organization.
nameCase-insensitive substring search on agent names.

The filters can be combined and work with the existing limit and cursor pagination parameters. See List Agents for examples and validation behavior.

2026-08-03 ​

Added: Shared Stores API ​

The Shared Stores API now supports organization-scoped store and entry CRUD, idempotent single-entry updates, and bulk upserts with JSON metadata.

Organizations can have up to 10 shared stores, with up to 10,000 entries in each store. See Shared Stores for the endpoint reference.

2026-06-28 ​

Added: output source citations ​

Agent run outputs now include a sources[] array when a render uses licensed or external media. Getty b-roll citations include the usage window, query, provider asset ID when resolved, internal render asset ID, placement/layout, and rights metadata.

Affected surfaces:

SurfaceField
GET /agent_run/{run_id}outputs[].sources
GET /agent/{agent_id}/runsruns[].outputs[].sources
GET /agent_runsruns[].outputs[].sources
GET /trigger/{trigger_id}/runsruns[].outputs[].sources
RUN_PROGRESS webhookupdated_nodes[].outputs[].sources
RUN_FINISHED webhookoutputs[].sources

2026-05-21 ​

Added: avatar profile API and generation tile docs ​

The Avatar Profiles API now exposes the public avatar workflow:

EndpointDescription
POST /avatar-profiles/createCreate an avatar from a source video, or an image plus voice reference. Processing starts automatically.
GET /avatar-profiles/{id}Get one avatar, including signed video_preview_url, status, and status_message.
GET /avatar-profilesList avatars available to your organization.

Avatar profile responses use a flat object shape:

json
{
  "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "video_preview_url": "https://...",
  "name": "Founder Avatar",
  "status": "processing",
  "status_message": null
}

Avatars can be used in AI Avatar tiles immediately after creation. If processing is still running, the agent run waits for the avatar to become ready; failed avatars return an error through status_message.

New generation tile documentation is also available for:

The Run Agent docs now include node IDs and setup guidance for AI Avatar, Video Generation, Audio Generation, and Image Generation workflows.

2026-04-04 ​

Added: errors field on agent runs and webhooks ​

Agent run responses and webhook payloads now include an errors field that surfaces error messages from failed tasks, grouped by the template node that produced them.

Run-level (GET /agent_run/{run_id} and RUN_FINISHED webhook):

json
"errors": [
  {
    "original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "messages": ["FFmpeg render failed: output format not supported"]
  },
  {
    "original_node_id": "3ca7b810-9dad-11d1-80b4-00c04fd430c8",
    "messages": [
      "Audio transcription timed out after 300s",
      "Retry failed: service unavailable"
    ]
  }
]

Each entry links errors to the original_node_id (template node) so you can map failures back to specific nodes in your agent.

Node-level (GET /agent_run/{run_id}/nodes and RUN_PROGRESS webhook updated_nodes[]):

json
"errors": ["Audio transcription timed out after 300s"]

Per-node errors is a flat string array since the node context is already provided by the parent object.

Affected endpoints:

SurfaceFieldType
GET /agent_run/{run_id}errorsarray of { original_node_id, messages[] }
GET /agent_run/{run_id}/nodesnodes[].errorsstring[]
RUN_FINISHED webhookerrorsarray of { original_node_id, messages[] }
RUN_PROGRESS webhookupdated_nodes[].errorsstring[]

Previously, error details from processing tasks were only available internally. The status_message field on runs and nodes continues to work as before and is unaffected by this change.