---
title: "Create a new flow."
method: POST
path: "/api/flows"
tags: ["flows"]
---

# Create a new flow.

`POST /api/flows`

Creates a flow under the `id` supplied in the body, so a caller can pre-generate an id and then start the flow by it. `id` is a required field: to have the server assign one instead, send the nil uuid (`00000000-0000-0000-0000-000000000000`) and read the assigned id from the `flow.id` of the response. Reusing the id of an existing flow is a 409; use `POST /api/flows/{id}` to update that flow instead.

## Request body

- Flow — A complete GStreamer pipeline definition. A flow represents a named, configured GStreamer pipeline that can be started, stopped, and persisted.
  - `blocks` BlockInstance[] — Block instances in this flow
    - `block_definition_id` string, required — Reference to the block definition
    - `computed_external_pads` ExternalPads — External pads that the block exposes
      - `inputs` ExternalPad[], required — Input pads (mapped to internal element pads)
        - `internal_element_id` string, required — Which internal element and pad this maps to
        - `internal_pad_name` string, required
        - `label` string, nullable — Optional display label (shown in graph editor)
        - `media_type` 'Generic' | 'Audio' | 'Video', required — Media type classification for pads.
        - `name` string, required — External name for this pad
      - `outputs` ExternalPad[], required — Output pads (mapped to internal element pads)
        - `internal_element_id` string, required — Which internal element and pad this maps to
        - `internal_pad_name` string, required
        - `label` string, nullable — Optional display label (shown in graph editor)
        - `media_type` 'Generic' | 'Audio' | 'Video', required — Media type classification for pads.
        - `name` string, required — External name for this pad
    - `id` string, required — Unique ID for this instance
    - `name` string, nullable — User-assigned name for this instance
    - `position` Position, required — Position in the visual editor
      - `x` number, float, required
      - `y` number, float, required
    - `properties` object, required — Property values for this instance
    - `runtime_data` object, nullable — Runtime data (not persisted to storage, only available when flow is running) Used for things like generated SDP for AES67 blocks
  - `elements` Element[] — Elements in this flow
    - `element_type` string, required — GStreamer element type (e.g., "videotestsrc", "x264enc", "filesink")
    - `id` string, required
    - `pad_properties` object — Pad properties (pad_name -> property_name -> value)
    - `position` number[], required — Display position in the visual editor (x, y)
    - `properties` object — Element properties as key-value pairs
  - `gst_state` 'Null' | 'Ready' | 'Paused' | 'Playing' — GStreamer pipeline state. These states correspond to the GStreamer GST_STATE enum.
  - `id` string, uuid, required — Unique identifier for this flow
  - `links` Link[] — Links between element pads and/or block external pads
    - `from` string, required — Source element and pad (format: "element_id" or "element_id:pad_name")
    - `to` string, required — Destination element and pad (format: "element_id" or "element_id:pad_name")
  - `name` string, required — Human-readable name
  - `properties` FlowProperties — Flow configuration properties.
    - `auto_restart` boolean — Whether this flow should be automatically restarted when the backend starts (set to true when starting a flow, false when manually stopping it)
    - `clock_sync_status` 'synced' | 'not_synced' | 'unknown' — Clock synchronization status.
    - `clock_type` 'monotonic' | 'realtime' | 'tai' | 'ptp' | 'ntp' — GStreamer clock type selection. Maps to GStreamer's clock implementations: - `Monotonic`: SystemClock with GST_CLOCK_TYPE_MONOTONIC (default) - `Realtime`: SystemClock with GST_CLOCK_TYPE_REALTIME (UTC wall clock) - `Tai`: SystemClock with GST_CLOCK_TYPE_TAI (linear atomic time, no leap seconds) - `Ptp`: PtpClock for IEEE 1588 PTP synchronization - `Ntp`: NtpClock for NTP synchronization
    - `cpu_affinity` 'off' | 'single_core' — CPU affinity strategy for GStreamer streaming threads. Controls whether pipeline threads are pinned to a single CPU core for better cache locality and reduced context switches.
    - `created_at` string, nullable — Timestamp when the flow was created ISO 8601 format with timezone
    - `description` string, nullable — Human-readable description (multiline text)
    - `direct_media_timing` boolean, nullable — Force direct media timing (`base_time=0`, `start_time=NONE`) so buffer PTS corresponds to absolute pipeline-clock time. - `Some(true)`: explicitly on. - `Some(false)`: explicitly off. - `None` (default): follow the clock-type default — `true` for `Ptp` (AES67 contract, RFC 7273 `mediaclk:direct=0`), `false` otherwise. Use this for narrow pipelines where every element cooperates with wall-clock timing (PTP+AES67, or TAI disciplined by `ptp4l`/`phc2sys` feeding AES67 with TAI timestamps). Avoid for general pipelines (MPEG-TS demuxers, RTP jitter buffers, WHEP session sinks) that assume `running_time` starts near 0.
    - `ephemeral` boolean — When true, the flow is not persisted to storage. Useful for temporary or API-created flows that should not survive a server restart.
    - `last_modified` string, nullable — Timestamp when the flow was last modified (any change to flow config) ISO 8601 format with timezone
    - `ntp_info` NtpInfo — NTP clock information (GStreamer GstNtpClock / NetClientClock). Populated at read-time from the running NtpClock instance. Values are snapshots from the clock's internal state at the moment the flow was queried.
      - `last_update` integer, nullable — Timestamp of last read (Unix seconds)
      - `minimum_update_interval_ns` integer, required — Minimum update interval between polls, in nanoseconds (from clock property)
      - `offset_ns` integer, nullable — Current offset between external (server) and internal (local) clocks at the calibration reference point, in nanoseconds. Positive = server ahead.
      - `port` integer, required — Server port
      - `rate` number, double, nullable — Current calibration rate (external clock speed / local speed). 1.0 = same speed, <1.0 = server slower than local, >1.0 = server faster.
      - `round_trip_limit_ns` integer, required — Maximum RTT for accepted samples, in nanoseconds (from clock property)
      - `server` string, required — Server hostname/IP the NtpClock is polling
      - `synced` boolean, required — Whether the clock has collected enough observations to be considered stable
    - `ntp_port` integer, nullable — NTP server port (only used when clock_type is NTP). Defaults to 123.
    - `ntp_server` string, nullable — NTP server address (hostname or IP, only used when clock_type is NTP) If not set but clock_type is NTP, will signal as "ntp=/traceable/"
    - `ptp_domain` integer, nullable — PTP domain (0-255, only used when clock_type is PTP)
    - `ptp_info` PtpInfo — PTP clock information (IEEE 1588). Contains detailed information about the PTP clock state including grandmaster and master clock identities, and synchronization statistics.
      - `domain` integer, required — PTP domain currently in use by the running pipeline (0-255)
      - `grandmaster_clock_id` string, nullable — Grandmaster clock ID (EUI-64 format as hex string, e.g., "00:11:22:FF:FE:33:44:55")
      - `master_clock_id` string, nullable — Master clock ID (EUI-64 format as hex string)
      - `restart_needed` boolean — True if configured domain differs from running domain (restart needed)
      - `stats` PtpStats — PTP clock synchronization statistics. Contains measurements from PTP clock synchronization including path delay, clock offset, and estimation quality.
        - `clock_offset_ns` integer, nullable — Clock offset/discontinuity in nanoseconds (positive = local clock ahead) This is the correction being applied to keep clocks synchronized
        - `clock_rate` number, double, nullable — Clock rate ratio (local clock speed relative to PTP master) 1.0 means clocks run at same speed, <1.0 means local is slower
        - `last_update` integer, nullable — Timestamp of last statistics update (Unix timestamp in seconds)
        - `mean_path_delay_ns` integer, nullable — Mean path delay to master clock in nanoseconds
        - `r_squared` number, double, nullable — R-squared value of clock estimation regression (0.0-1.0, higher is better) Values close to 1.0 indicate stable, accurate synchronization
      - `synced` boolean, required — Whether the clock is synchronized with a PTP master
    - `started_at` string, nullable — Timestamp when the flow was started (entered Playing state) ISO 8601 format with timezone (e.g., "2024-01-15T14:30:00+01:00") None if the flow has never been started or is currently stopped
    - `thread_priority` 'normal' | 'high' | 'realtime' — Thread priority level for GStreamer streaming threads. Controls the scheduling priority of GStreamer's internal streaming threads. Higher priorities help ensure smooth media processing under system load.
    - `thread_priority_status` ThreadPriorityStatus — Status of thread priority configuration for a running pipeline.
      - `achieved` boolean, required — Whether the requested priority was successfully applied
      - `error` string, nullable — Error message if priority could not be set (empty if achieved)
      - `requested` 'normal' | 'high' | 'realtime', required — Thread priority level for GStreamer streaming threads. Controls the scheduling priority of GStreamer's internal streaming threads. Higher priorities help ensure smooth media processing under system load.
      - `threads_configured` integer, required — Number of threads that had priority set
  - `running` boolean — Whether the pipeline is actively running (data flowing). This is the field most callers should use. It is `true` when the GStreamer pipeline is in `Playing` *or* in `Paused` due to an async element that has not yet completed its transition.

## Response `201`

Flow created

- FlowResponse — Response containing a single flow.
  - `flow` Flow, required — A complete GStreamer pipeline definition. A flow represents a named, configured GStreamer pipeline that can be started, stopped, and persisted.
    - `blocks` BlockInstance[] — Block instances in this flow
      - `block_definition_id` string, required — Reference to the block definition
      - `computed_external_pads` ExternalPads — External pads that the block exposes
        - `inputs` ExternalPad[], required — Input pads (mapped to internal element pads)
          - `internal_element_id` string, required — Which internal element and pad this maps to
          - `internal_pad_name` string, required
          - `label` string, nullable — Optional display label (shown in graph editor)
          - `media_type` 'Generic' | 'Audio' | 'Video', required — Media type classification for pads.
          - `name` string, required — External name for this pad
        - `outputs` ExternalPad[], required — Output pads (mapped to internal element pads)
          - `internal_element_id` string, required — Which internal element and pad this maps to
          - `internal_pad_name` string, required
          - `label` string, nullable — Optional display label (shown in graph editor)
          - `media_type` 'Generic' | 'Audio' | 'Video', required — Media type classification for pads.
          - `name` string, required — External name for this pad
      - `id` string, required — Unique ID for this instance
      - `name` string, nullable — User-assigned name for this instance
      - `position` Position, required — Position in the visual editor
        - `x` number, float, required
        - `y` number, float, required
      - `properties` object, required — Property values for this instance
      - `runtime_data` object, nullable — Runtime data (not persisted to storage, only available when flow is running) Used for things like generated SDP for AES67 blocks
    - `elements` Element[] — Elements in this flow
      - `element_type` string, required — GStreamer element type (e.g., "videotestsrc", "x264enc", "filesink")
      - `id` string, required
      - `pad_properties` object — Pad properties (pad_name -> property_name -> value)
      - `position` number[], required — Display position in the visual editor (x, y)
      - `properties` object — Element properties as key-value pairs
    - `gst_state` 'Null' | 'Ready' | 'Paused' | 'Playing' — GStreamer pipeline state. These states correspond to the GStreamer GST_STATE enum.
    - `id` string, uuid, required — Unique identifier for this flow
    - `links` Link[] — Links between element pads and/or block external pads
      - `from` string, required — Source element and pad (format: "element_id" or "element_id:pad_name")
      - `to` string, required — Destination element and pad (format: "element_id" or "element_id:pad_name")
    - `name` string, required — Human-readable name
    - `properties` FlowProperties — Flow configuration properties.
      - `auto_restart` boolean — Whether this flow should be automatically restarted when the backend starts (set to true when starting a flow, false when manually stopping it)
      - `clock_sync_status` 'synced' | 'not_synced' | 'unknown' — Clock synchronization status.
      - `clock_type` 'monotonic' | 'realtime' | 'tai' | 'ptp' | 'ntp' — GStreamer clock type selection. Maps to GStreamer's clock implementations: - `Monotonic`: SystemClock with GST_CLOCK_TYPE_MONOTONIC (default) - `Realtime`: SystemClock with GST_CLOCK_TYPE_REALTIME (UTC wall clock) - `Tai`: SystemClock with GST_CLOCK_TYPE_TAI (linear atomic time, no leap seconds) - `Ptp`: PtpClock for IEEE 1588 PTP synchronization - `Ntp`: NtpClock for NTP synchronization
      - `cpu_affinity` 'off' | 'single_core' — CPU affinity strategy for GStreamer streaming threads. Controls whether pipeline threads are pinned to a single CPU core for better cache locality and reduced context switches.
      - `created_at` string, nullable — Timestamp when the flow was created ISO 8601 format with timezone
      - `description` string, nullable — Human-readable description (multiline text)
      - `direct_media_timing` boolean, nullable — Force direct media timing (`base_time=0`, `start_time=NONE`) so buffer PTS corresponds to absolute pipeline-clock time. - `Some(true)`: explicitly on. - `Some(false)`: explicitly off. - `None` (default): follow the clock-type default — `true` for `Ptp` (AES67 contract, RFC 7273 `mediaclk:direct=0`), `false` otherwise. Use this for narrow pipelines where every element cooperates with wall-clock timing (PTP+AES67, or TAI disciplined by `ptp4l`/`phc2sys` feeding AES67 with TAI timestamps). Avoid for general pipelines (MPEG-TS demuxers, RTP jitter buffers, WHEP session sinks) that assume `running_time` starts near 0.
      - `ephemeral` boolean — When true, the flow is not persisted to storage. Useful for temporary or API-created flows that should not survive a server restart.
      - `last_modified` string, nullable — Timestamp when the flow was last modified (any change to flow config) ISO 8601 format with timezone
      - `ntp_info` NtpInfo — NTP clock information (GStreamer GstNtpClock / NetClientClock). Populated at read-time from the running NtpClock instance. Values are snapshots from the clock's internal state at the moment the flow was queried.
        - `last_update` integer, nullable — Timestamp of last read (Unix seconds)
        - `minimum_update_interval_ns` integer, required — Minimum update interval between polls, in nanoseconds (from clock property)
        - `offset_ns` integer, nullable — Current offset between external (server) and internal (local) clocks at the calibration reference point, in nanoseconds. Positive = server ahead.
        - `port` integer, required — Server port
        - `rate` number, double, nullable — Current calibration rate (external clock speed / local speed). 1.0 = same speed, <1.0 = server slower than local, >1.0 = server faster.
        - `round_trip_limit_ns` integer, required — Maximum RTT for accepted samples, in nanoseconds (from clock property)
        - `server` string, required — Server hostname/IP the NtpClock is polling
        - `synced` boolean, required — Whether the clock has collected enough observations to be considered stable
      - `ntp_port` integer, nullable — NTP server port (only used when clock_type is NTP). Defaults to 123.
      - `ntp_server` string, nullable — NTP server address (hostname or IP, only used when clock_type is NTP) If not set but clock_type is NTP, will signal as "ntp=/traceable/"
      - `ptp_domain` integer, nullable — PTP domain (0-255, only used when clock_type is PTP)
      - `ptp_info` PtpInfo — PTP clock information (IEEE 1588). Contains detailed information about the PTP clock state including grandmaster and master clock identities, and synchronization statistics.
        - `domain` integer, required — PTP domain currently in use by the running pipeline (0-255)
        - `grandmaster_clock_id` string, nullable — Grandmaster clock ID (EUI-64 format as hex string, e.g., "00:11:22:FF:FE:33:44:55")
        - `master_clock_id` string, nullable — Master clock ID (EUI-64 format as hex string)
        - `restart_needed` boolean — True if configured domain differs from running domain (restart needed)
        - `stats` PtpStats — PTP clock synchronization statistics. Contains measurements from PTP clock synchronization including path delay, clock offset, and estimation quality.
          - `clock_offset_ns` integer, nullable — Clock offset/discontinuity in nanoseconds (positive = local clock ahead) This is the correction being applied to keep clocks synchronized
          - `clock_rate` number, double, nullable — Clock rate ratio (local clock speed relative to PTP master) 1.0 means clocks run at same speed, <1.0 means local is slower
          - `last_update` integer, nullable — Timestamp of last statistics update (Unix timestamp in seconds)
          - `mean_path_delay_ns` integer, nullable — Mean path delay to master clock in nanoseconds
          - `r_squared` number, double, nullable — R-squared value of clock estimation regression (0.0-1.0, higher is better) Values close to 1.0 indicate stable, accurate synchronization
        - `synced` boolean, required — Whether the clock is synchronized with a PTP master
      - `started_at` string, nullable — Timestamp when the flow was started (entered Playing state) ISO 8601 format with timezone (e.g., "2024-01-15T14:30:00+01:00") None if the flow has never been started or is currently stopped
      - `thread_priority` 'normal' | 'high' | 'realtime' — Thread priority level for GStreamer streaming threads. Controls the scheduling priority of GStreamer's internal streaming threads. Higher priorities help ensure smooth media processing under system load.
      - `thread_priority_status` ThreadPriorityStatus — Status of thread priority configuration for a running pipeline.
        - `achieved` boolean, required — Whether the requested priority was successfully applied
        - `error` string, nullable — Error message if priority could not be set (empty if achieved)
        - `requested` 'normal' | 'high' | 'realtime', required — Thread priority level for GStreamer streaming threads. Controls the scheduling priority of GStreamer's internal streaming threads. Higher priorities help ensure smooth media processing under system load.
        - `threads_configured` integer, required — Number of threads that had priority set
    - `running` boolean — Whether the pipeline is actively running (data flowing). This is the field most callers should use. It is `true` when the GStreamer pipeline is in `Playing` *or* in `Paused` due to an async element that has not yet completed its transition.

## Other responses

- `409` — A flow with the supplied id already exists
- `500` — Internal server error

## Changes

> 25 revisions in range; 24 could not be searched.

- **2026-04-07** `1e67862a080e` — 11 warning, 2 info
  - removed the request property `blocks`
  - removed the request property `elements`
  - removed the request property `gst_state`
  - removed the request property `id`
  - …9 more

[Change history](https://skmtc.dev/eyevinn/apis/strom-api/changes/api/flows/post.md)

---

[API](https://skmtc.dev/eyevinn/apis/strom-api.md) · [All operations](https://skmtc.dev/eyevinn/apis/strom-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/eyevinn/strom-api/revisions/0df7ca64263f/schema)