---
title: "Declare which ports a flow uses."
method: POST
path: "/api/ports/reservations/{id}/assign"
tags: ["ports"]
---

# Declare which ports a flow uses.

`POST /api/ports/reservations/{id}/assign`

## Request

- The document declares no server URL.
- Auth: none declared

Records that these ports of this reservation are used by that flow. The pool will not return them while the flow exists, so a reservation that lapses under a running pipeline releases only its idle ports. Replaces whatever was recorded for the same flow, so a caller can correct itself by assigning again. Nothing verifies that the flow actually binds them.

## Path parameters

- `id` string, uuid, required

## Request body

- AssignPortsRequest: Tell the pool which of a reservation's ports a flow uses. Replaces whatever was recorded for that flow, so a caller can correct itself by assigning again.
  - `flow_id` string, uuid, required: The flow using them.
  - `ports` integer[], required: Ports, all of which must belong to this reservation.

## Response `200`

The reservation

- PortReservation: Ports held by one owner. `ports` is an explicit list, ascending. Allocation prefers a contiguous run and growth prefers extending the existing one, but neither is guaranteed — a port the operator left out of the pool, one another owner holds, or one found blocked can put a hole anywhere. Callers must not assume contiguity.
  - `created_at` string, required: When the reservation was first granted (RFC 3339, UTC).
  - `expires_at` string, required: When it lapses unless renewed (RFC 3339, UTC).
  - `id` string, uuid, required: Reservation identifier, used to renew, release and assign.
  - `in_use` PortInUse[]: Which of `ports` the owner has told the pool are used by a flow.
    - `flow_id` string, uuid, required: The flow the owner says uses it.
    - `port` integer, required: The port.
  - `owner_id` string, required: The owner's stable name. One reservation per owner; asking again returns it.
  - `ports` integer[], required: The ports held, ascending.

## Other responses

- `400`: A port does not belong to this reservation
- `404`: No live reservation with that id, or no flow with that id
- `409`: A port is already assigned to another flow
- `500`: Reservation could not be persisted
- `503`: No port pool is configured on this server

## Changes

- **2026-09-28** `fd671a19e55a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/eyevinn/apis/strom-api/changes/api/ports/reservations/:id/assign/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.dev/eyevinn/apis/strom-api/revisions/8cd4dbc44175?raw)