> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirurobotics.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create
> Create a new release.
| Scope | Required |
| ---------------- | -------- |
| `releases:write` | Yes |
Consider using the Miru CLI in a CI/CD pipeline to create releases instead of calling this endpoint directly.
## OpenAPI
````yaml /references/platform-api/2026-08-17.yaml post /releases
openapi: 3.0.3
info:
title: Miru Platform API
description: The API between Miru and any external client
version: 2026-08-17.everglades
license:
name: MIT
url: https://opensource.org/licenses/MIT
x-release-version: 2026-08-17.everglades
x-git-commit:
sha: b0d008b18d840e3f7ad65ae4beb60b19863b665e
url: >-
https://github.com/mirurobotics/openapi/commit/b0d008b18d840e3f7ad65ae4beb60b19863b665e
message: >-
refactor(platform): remove bulk device move (#251)
## What
Removes device→group *movement* from the platform audience. Two things
go, together:
1. **`POST /devices/move/bulk` (`bulkMoveDevices`)** — the path item in
`apis/apps/backend-server/platform/paths/devices.yaml`, its entry in
`platform/openapi.yaml`, and the `devices.bulk_move` method in
`tools/stainless/platform.yml`.
2. **`group_id` on the platform `CreateDeviceRequest`** — the only place
`group_id` appeared in a platform request body.
Device→group membership is now **fully read-only** on the platform API.
## What deliberately stays
Nothing on the *read* side moved, and group structure stays writable:
| Kept | Why |
|---|---|
| `group_id` on the `Device` schema | read field, unaffected |
| `expand=group` on `Device`, and `group` in `DeviceExpansion` /
`DeviceListExpansion` | read surface |
| `group_id` filter on `GET /devices` (`device_search_group_id`) | read
surface |
| `GET /groups`, `GET /groups/{group_id}`, `POST /groups`, `PATCH
/groups/{group_id}` | group CRUD is orthogonal to device membership |
| **`POST /groups/{group_id}/move` (`moveGroup`)** | reparents a
**group** in the tree, not devices between groups — different resource,
different scope, and reversible by another reparent |
| `apis/configs/components/requests/device.yaml#/BulkMoveDevicesRequest`
| still referenced by `frontend` and `cli`, which keep their `bulk_move`
methods |
`moveGroup` surviving is the thing worth double-checking in review,
since "move" appears on both resources. Verification below gates on it
explicitly.
## Why create-time `group_id` goes with the endpoint
This is the load-bearing part, not an incidental tidy-up.
Without a move operation, a create-time `group_id` is a **one-way
door**. A device could be placed into a group at provision time and then
never moved out, reassigned, or relocated in the tree — through the API,
ever. Shipping a write that can be exercised exactly once per resource
lifetime is worse than shipping no write at all, because it hands
customers a state they cannot get out of without the dashboard.
So both go together, and the result is coherent: you can *see* which
group a device is in, expand the group object, and filter a device list
by group. You cannot set or change it.
## Not breaking
`platform/2026-05-06.rainier` — the last **stable** platform release —
has **no bulk-move endpoint and no groups resource at all**. `POST
/devices/move/bulk` and create-time `group_id` existed only in the
prereleases `platform/2026-08-17.everglades-beta.3` and
`everglades-beta.4`.
Withdrawing beta-only surface before everglades goes stable is free;
after it goes stable it would not be. Same reasoning as #244 (upload
collections) and #250 (the `devices:move` scope).
## Verification
`./scripts/regen.sh`, `./scripts/lint.sh`, and `./scripts/preflight.sh`
(`=== All checks passed ===`) all clean; `./scripts/is-stale.sh` reports
`All generated specs are up to date.`
- **Platform route count 25 → 24.**
- **Scope histogram: `devices:write` 3 → 2**, `groups:write` unchanged
at **3**, everything else unchanged.
- Zero hits for `move/bulk`, `bulkMoveDevices`, or `BulkMoveDevices`
anywhere in the platform tree or bundle; zero `bulk` in
`tools/stainless/platform.yml`.
- `CreateDeviceRequest` in the bundle is down to `name` alone — no
`group_id`.
- The generated `Device` block still carries `group_id` (required +
property) and the `group` expandable; `group` present in **both**
expansion enums; two `name: group_id` query params still in the bundle.
- All five group routes present, `moveGroup` included.
- Platform bundle diff is `0 55` — a pure deletion. No other audience's
bundle changed and `apis/configs/` is untouched.
A bare `grep group_id` is useless here — it matches the group path
param, the `Device` read field, the `DvcSearch` enum member, and the
list filter, all of which survive. Every check above is scoped to a
specific schema block or uses a precise pattern.
Plan: `plans/active/20260817-remove-platform-bulk-device-move.md`.
## Follow-ups
**Release.** A new `platform/2026-08-17.everglades-beta.5` must be cut
after merge — **tag the squash-merge commit on `main`**, not the branch
head. Tagging a branch head makes the release job skip silently and
publish nothing.
**Backend.** Three changes:
- Remove the `bulkMoveDevices` HTTP wiring.
- Re-stub `CreateDevice.GetGroupID()` back to `optnull.None[string]()`.
- Revert `Perms.Devices.Move` out of **both** `devices:write` and
`devices:manage` — it was added to `devices:write` in #624 solely for
this endpoint.
**Docs.** docs#158 must drop the endpoint from the everglades changelog
and from `authz.mdx`.
---
Need help on this PR? Tag @codesmith with what you
need. Autofix is disabled.
---------
Co-authored-by: Claude
author: ben-miru
branch: HEAD
dirty: false
x-build:
built_at: '2026-08-17T04:08:03.448835+00:00'
servers:
- url: https://api.mirurobotics.com/beta
description: Miru Platform API
security:
- ApiKeyAuth: []
paths:
/releases:
parameters:
- $ref: '#/components/parameters/MiruVersion'
post:
tags:
- Releases
summary: Create
description: Create a new release.
operationId: createRelease
parameters:
- $ref: '#/components/parameters/release_expansions'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateReleaseRequest'
responses:
'200':
description: Successfully created the release.
content:
application/json:
schema:
$ref: '#/components/schemas/Release'
components:
parameters:
MiruVersion:
name: Miru-Version
in: header
required: true
schema:
type: string
example: 2026-08-17.everglades
description: The API version the client was built against.
release_expansions:
name: expand
in: query
required: false
description: Fields to expand on the release resource.
schema:
type: array
items:
$ref: '#/components/schemas/ReleaseExpansion'
example:
- config_schemas
schemas:
CreateReleaseRequest:
title: Create Release Request
type: object
required:
- version
- config_schema_ids
properties:
version:
type: string
example: v1.0.0
description: The version of the release.
config_schema_ids:
type: array
description: The IDs of the config schemas included in the release.
items:
type: string
example: cfg_sch_123
git_commit_ref:
$ref: '#/components/schemas/GitCommitRef'
Release:
title: Release
allOf:
- $ref: '#/components/schemas/BaseRelease'
- type: object
properties:
config_schemas:
type: array
items:
$ref: '#/components/schemas/ConfigSchema'
description: >-
Expand the config schemas using 'expand=config_schemas' in the
query string.
example:
- object: config_schema
id: cfg_sch_123
digest: sha256:1234567890
config_type_name: Motion Control
instance_slots:
- key: default
name: Default
filepath: /srv/miru/configs/v1/motion-control.json
required: true
instance_format: json
created_at: '2021-01-01T00:00:00Z'
updated_at: '2021-01-01T00:00:00Z'
config_type_id: cfg_typ_123
language: jsonschema
format: json
- object: config_schema
id: cfg_sch_124
digest: sha256:1234567890
config_type_name: Localization
instance_slots:
- key: primary
name: Primary
filepath: /srv/miru/configs/v1/localization/primary.json
required: true
- key: secondary
name: Secondary
filepath: /srv/miru/configs/v1/localization/secondary.json
required: false
instance_format: json
created_at: '2021-01-01T00:00:00Z'
updated_at: '2021-01-01T00:00:00Z'
config_type_id: cfg_typ_124
language: jsonschema
format: json
example:
object: release
id: rls_123
version: v1.0.0
git_commit_id: git_commit_123
created_at: '2024-01-01T00:00:00Z'
updated_at: '2024-01-01T00:00:00Z'
ReleaseExpansion:
type: string
enum:
- config_schemas
x-enum-varnames:
- RELEASE_EXPAND_CONFIG_SCHEMAS
GitCommitRef:
title: Git Commit Reference
description: >-
A reference to a git commit. At least one of `id` or `sha` must be
provided. When both are provided, `id` takes precedence and `sha` is
ignored.
type: object
properties:
id:
type: string
description: >-
ID of the git commit. Takes precedence over `sha` when both are
provided.
example: git_cmt_123
sha:
type: string
description: The SHA hash of the git commit. Used only when `id` is not provided.
example: 1a2b3c4d...
BaseRelease:
title: Base Release
type: object
required:
- object
- id
- version
- git_commit_id
- created_at
- updated_at
properties:
object:
type: string
enum:
- release
example: release
x-stainless-const: true
description: The object type, which is always `release`.
id:
type: string
example: rls_123
description: ID of the release.
version:
type: string
example: v1.0.0
description: The version of the release.
git_commit_id:
type: string
nullable: true
example: git_commit_123
description: The ID of the git commit associated with this release.
created_at:
type: string
format: date-time
example: '2024-01-01T00:00:00Z'
description: Timestamp of when the release was created.
updated_at:
type: string
format: date-time
example: '2024-01-01T00:00:00Z'
description: Timestamp of when the release was last updated.
ConfigSchema:
title: Config Schema
allOf:
- $ref: '#/components/schemas/BaseConfigSchema'
- type: object
properties:
config_type:
allOf:
- $ref: '#/components/schemas/ConfigType'
description: >-
Expand the config type using 'expand=config_type' in the query
string.
example:
object: config_schema
id: cfg_sch_123
digest: sha256:1234567890
config_type_name: Motion Control
instance_slots:
- key: default
name: Default
filepath: /srv/miru/configs/v1/motion-control.json
required: true
instance_format: json
created_at: '2021-01-01T00:00:00Z'
updated_at: '2021-01-01T00:00:00Z'
config_type_id: cfg_typ_123
language: jsonschema
format: json
BaseConfigSchema:
title: Base Config Schema
type: object
required:
- object
- id
- digest
- config_type_name
- instance_format
- created_at
- updated_at
- config_type_id
- language
- format
- instance_slots
properties:
object:
type: string
enum:
- config_schema
example: config_schema
x-stainless-const: true
description: The object type, which is always `config_schema`.
id:
type: string
example: cfg_sch_123
description: ID of the config schema.
digest:
type: string
example: sha256:1234567890
description: The digest of the config schema.
config_type_name:
type: string
example: Motion Control
description: The name of the config type.
instance_slots:
type: array
minItems: 1
description: >-
The file system destinations this config schema writes to. Every
config schema has at least one slot. Slots share the schema's
validation and differ only in where the file is written; a file
needing different validation is a different config type, not a slot.
Slot keys and filepaths must each be unique within the schema, and
slot filepaths must be unique across every config schema in a
release.
items:
$ref: '#/components/schemas/InstanceSlot'
example:
- key: default
name: Default
filepath: /srv/miru/configs/v1/motion-control.json
required: true
instance_format:
$ref: '#/components/schemas/InstanceFormat'
created_at:
type: string
format: date-time
example: '2021-01-01T00:00:00Z'
description: Timestamp of when the config schema was created.
updated_at:
type: string
format: date-time
example: '2021-01-01T00:00:00Z'
description: Timestamp of when the config schema was last updated.
config_type_id:
type: string
example: cfg_typ_123
description: ID of the config type.
language:
$ref: '#/components/schemas/SchemaLanguage'
format:
$ref: '#/components/schemas/SchemaFormat'
documents:
allOf:
- $ref: '#/components/schemas/SchemaDocuments'
description: >-
Expand the config schema documents using `expand=documents` in the
query string.
example:
- id: doc_123
name: main.json
data: |
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object"
}
ConfigType:
allOf:
- $ref: '#/components/schemas/BaseConfigType'
example:
object: config_type
id: cfg_typ_123
name: Motion Control
slug: motion-control
created_at: '2021-01-01T00:00:00Z'
updated_at: '2021-01-01T00:00:00Z'
created_by_id: usr_123
updated_by_id: usr_123
InstanceSlot:
title: Instance Slot
type: object
required:
- key
- name
- filepath
- required
properties:
key:
type: string
pattern: ^[a-z0-9][a-z0-9_-]*$
maxLength: 128
example: controller_2
description: >-
An immutable, code-friendly identifier for this slot, unique within
the schema. Lowercase alphanumerics, underscores, and hyphens; must
start with an alphanumeric; at most 128 characters.
name:
type: string
example: Controller 2
description: The human-readable name of this slot.
filepath:
type: string
example: >-
/var/local/forge/configuration/robot_drivers/controller_2/topic_list.yaml
description: >-
The absolute file system path where instances bound to this slot are
written. Must be unique within the schema, and unique across every
config schema in a release.
required:
type: boolean
example: true
description: >-
Whether every deployment of a release containing this schema must
include an instance for this slot. A deployment includes at most one
config instance per slot.
description:
type: string
example: Topic list for the second motor controller.
description: An optional human-readable description of this slot.
example:
key: controller_2
name: Controller 2
filepath: >-
/var/local/forge/configuration/robot_drivers/controller_2/topic_list.yaml
required: true
description: Topic list for the second motor controller.
InstanceFormat:
title: Instance Format
type: string
description: >
The on-disk format used when a config instance is written to the device
filesystem.
- `json`: standard JSON.
- `yaml`: YAML 1.2.
- `jsonc`: JSON with comments (JSON plus `//` and `/* */` comment
syntax).
- `xml`: XML.
- `text`: plain, unstructured text with no specific format.
enum:
- json
- yaml
- jsonc
- xml
- text
x-enum-varnames:
- INSTANCE_FORMAT_JSON
- INSTANCE_FORMAT_YAML
- INSTANCE_FORMAT_JSONC
- INSTANCE_FORMAT_XML
- INSTANCE_FORMAT_TEXT
SchemaLanguage:
title: Schema Language
type: string
example: jsonschema
enum:
- jsonschema
- cue
- opaque
x-enum-varnames:
- JSONSCHEMA
- CUE
- OPAQUE
SchemaFormat:
title: Schema Format
type: string
enum:
- json
- yaml
- cue
x-enum-varnames:
- SCHEMA_FORMAT_JSON
- SCHEMA_FORMAT_YAML
- SCHEMA_FORMAT_CUE
SchemaDocuments:
type: array
items:
$ref: '#/components/schemas/SchemaDocument'
example:
- id: doc_123
name: main.json
data: |
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object"
}
BaseConfigType:
title: Config Type
type: object
required:
- object
- id
- name
- slug
- created_at
- updated_at
properties:
object:
type: string
enum:
- config_type
example: config_type
x-stainless-const: true
description: The object type, which is always `config_type`.
id:
type: string
example: cfg_123
description: ID of the config type.
name:
type: string
example: My Config Type
description: Name of the config type.
slug:
type: string
example: my-config-type
description: An immutable, code-friendly name for the config type.
created_at:
type: string
format: date-time
example: '2021-01-01T00:00:00Z'
description: Timestamp of when the config type was created.
updated_at:
type: string
format: date-time
example: '2021-01-01T00:00:00Z'
description: Timestamp of when the config type was last updated.
SchemaDocument:
title: Schema Document
type: object
required:
- id
- name
- data
properties:
id:
type: string
description: The unique identifier for this document.
example: doc_123
name:
type: string
description: The document filename.
example: main.json
data:
type: string
description: The raw document content.
example:
id: doc_123
name: main.json
data: |
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object"
}
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: The API key to use for authentication.
````
![View with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg)
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg)