> ## 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. # Get > Retrieve a file rule by its ID. ## OpenAPI ````yaml /references/device-api/v0.2.3/api.yaml get /file_rules/{file_rule_id} openapi: 3.0.3 info: title: Miru Agent API description: >- The API between the Miru Agent and any external client living on the same device as the Miru Agent. On Linux the agent serves it over the Unix socket `/run/miru/miru.sock` with no authentication. Over loopback TCP, which is on by default on Windows at `127.0.0.1:6478`, every route requires `Authorization: Bearer `. Clients read the port and token from the agent's discovery file, `%ProgramData%\Miru\device-api\device-api.json` on Windows; the token changes every time the agent starts. version: v0.2 license: name: MIT url: https://opensource.org/licenses/MIT x-release-version: v0.2.3 x-git-commit: sha: 850e23bf5fc36a890d36b5a2d9156f68d141f645 url: >- https://github.com/mirurobotics/openapi/commit/850e23bf5fc36a890d36b5a2d9156f68d141f645 message: >- feat(device): rename component_slug to component in CreateCalibrationRequest (#359) _Requested by **bens-agent** · [project thread](https://claude.ai/code/project/chan_015imaa8aZrnubYZcZCvjeHx?thread=cmsg_015imaa8aZrnubYZcZCvjeHxMkwTnPSSvfAHZA9NT4YaSe)_ ## Summary Renames `CreateCalibrationRequest.component_slug` to `component` in the Device API's `POST /calibrations`. #339 already renamed it this way in the agent API. The field is still required and still holds the component's slug, so it now matches `role` and `aspect`, which are slugs without a `_slug` suffix. The description uses the same wording as the agent API's. The published `device/v0.2.3` release is being removed, so it can be re-released from this change. ## Changes - `apis/apps/device-server/components/requests/calibration.yaml`: the field and its `required` entry are renamed, with a new description. - `apis/apps/device-server/openapi.gen.yaml`: regenerated. ## Not in this PR - The agent's Device API handler must accept `component` before an agent release serves this version. - The docs follow in mirurobotics/docs#269. ## Test plan - `./scripts/regen.sh` and `./scripts/lint.sh` pass. --- _Generated by [Claude Code](https://claude.ai/code/session_01XYr7RpV2F8ueBW98eeY8W5)_ --- View with [code]smith Autofix with [code]smith Need help on this PR? Tag @codesmith with what you need. Co-authored-by: Claude author: Ben's Agent branch: HEAD dirty: false x-build: built_at: '2026-10-25T21:22:34.230221+00:00' servers: - url: http://localhost/v0.2 description: localhost security: - {} - BearerAuth: [] paths: /file_rules/{file_rule_id}: get: tags: - File Rules summary: Get description: Retrieve a file rule by its ID. operationId: getFileRule parameters: - $ref: '#/components/parameters/file_rule_id' responses: '200': description: Successfully retrieved the file rule. content: application/json: schema: $ref: '#/components/schemas/BaseFileRule' x-codeSamples: - lang: curl label: curl (Linux) source: |- curl \ --unix-socket /run/miru/miru.sock \ --request GET \ --url http://localhost/v0.2/file_rules/{file_rule_id} - lang: powershell label: PowerShell (Windows) source: >- $api = Get-Content -Raw "$env:ProgramData\Miru\device-api\device-api.json" | ConvertFrom-Json; ` Invoke-RestMethod -Method Get ` -Uri "http://127.0.0.1:$($api.port)/v0.2/file_rules/{file_rule_id}" ` -Headers @{ Authorization = "Bearer $($api.token)" } - lang: Python source: |- from miru_device_sdk import Miru client = Miru() file_rule = client.file_rules.retrieve( "file_rule_123", ) print(file_rule.id) components: parameters: file_rule_id: name: file_rule_id in: path required: true description: The unique identifier of the file rule. schema: type: string example: file_rule_123 schemas: BaseFileRule: title: Base File Rule type: object description: | A file rule declares which files on a device Miru manages and what to do with them: upload them to a bucket, delete the local copies once they are no longer needed, or both. `retention` is optional and marks the rules that delete: when it is absent the device keeps matching files indefinitely — Miru never deletes them — and when it is present the rule deletes each matching file once its retention guarantee ends. A rule that both deletes and uploads always states `retention.require_upload`, so whether local deletion waits for the upload is itself an explicit decision. required: - object - id - name - digest - os - source - created_at - updated_at properties: object: type: string enum: - file_rule example: file_rule x-stainless-const: true description: The object type, which is always `file_rule`. id: type: string example: file_rule_123 description: ID of the file rule. name: type: string example: Robot Logs description: >- A human-readable name for the file rule. Not unique within a workspace: file rules are immutable, so each authored revision mints a new rule and several rules may share a name. The name participates in the rule's digest, so renaming a rule mints a new rule. digest: type: string example: sha256:1234567890 description: >- The digest of the file rule. File rules are immutable and deduplicated by digest within a workspace. os: allOf: - $ref: '#/components/schemas/OS' readOnly: true description: >- The operating system family this file rule targets, derived from `source.glob`: a glob starting with `/` is `linux`, and a glob starting with a drive letter is `windows`. Read-only: clients cannot set it. source: $ref: '#/components/schemas/FileRuleSource' upload: allOf: - $ref: '#/components/schemas/FileRuleUpload' description: >- Where matching files are uploaded. Absent when the rule only enforces local retention. retention: allOf: - $ref: '#/components/schemas/FileRuleRetention' description: >- Governs deletion of the local copies of matching files. Absent when the device keeps matching files indefinitely — Miru never deletes them; present when the rule deletes each matching file once its retention guarantee ends. created_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the file rule was created. updated_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the file rule was last updated. example: object: file_rule id: file_rule_123 name: Robot Logs digest: sha256:1234567890 os: linux source: glob: /var/log/robot/*.log stability_window_secs: 60 upload: upload_collection_id: upl_col_123 upload_collection_name: Robot Logs bucket_id: bkt_123 bucket_name: my-uploads-bucket path: '{device_id}/{year}-{month}-{day}/{upload_id}/{file_name}' timezone: utc retention: require_upload: true ttl_secs: 604800 created_at: '2021-01-01T00:00:00Z' updated_at: '2021-01-01T00:00:00Z' OS: title: OS type: string description: > An operating system family, from the agent's build-time OS vocabulary. Shared across resources (devices, config schemas, file rules, releases). This is the machine-readable OS kind, distinct from a human-readable version string. - `linux` - `windows` example: linux enum: - linux - windows x-enum-varnames: - OS_LINUX - OS_WINDOWS FileRuleSource: title: File Rule Source type: object required: - glob - stability_window_secs properties: glob: type: string pattern: ^(/|[A-Za-z]:[\\/]) maxLength: 1024 example: /var/log/robot/*.log description: >- Absolute glob of the files this rule manages (`/` on Linux, `C:\…` or `C:/…` on Windows; max 1024 bytes; no `.`, `..` or empty segments). A `{name}` capture matches like `*` within one segment and must be used in `upload.bundle` or `upload.path`. Names match `[a-z][a-z0-9_]*`, are unique, and must not reuse a built-in path variable. A segment holds at most one capture, and the rest of that segment must be constant text (no `*`, `?`, `[`, `\` or other braces). A capture may not have `**` segments both before and after it. `{a,b}` is literal. Devices see each capture as `*`. stability_window_secs: type: integer format: int64 example: 60 description: >- How long, in seconds, a matching file's size and modification time must stay unchanged (quiescent) before it is considered finished and eligible for upload. Files in a format with a finalization marker (e.g. MCAP, parquet) are detected directly; this window is the fallback for other files. example: glob: /var/log/robot/*.log stability_window_secs: 60 FileRuleUpload: title: File Rule Upload type: object required: - upload_collection_id - upload_collection_name - bucket_id - bucket_name - path - timezone properties: upload_collection_id: type: string example: upl_col_123 description: ID of the upload collection the resulting uploads are grouped into. upload_collection_name: type: string example: Robot Logs description: >- The name of the upload collection the resulting uploads are grouped into. bucket_id: type: string example: bkt_123 description: ID of the bucket this rule uploads to. bucket_name: type: string example: my-uploads-bucket description: Name of the bucket this rule uploads to. path: type: string pattern: .*\{upload_id\}.* maxLength: 1024 example: '{device_id}/{year}-{month}-{day}/{upload_id}/{file_name}' description: >- Object-path template for the uploaded file. Contains `{upload_id}`, is at most 1024 bytes, has balanced braces, and contains no `..` or empty segments. Variables: `{device_id}`, `{device_name}`, `{file_name}`, `{upload_id}`, `{bundle_id}`, `{year}`, `{month}`, `{day}`, `{hour}`, `{minute}`, `{timezone}`, plus any `source.glob` capture. `{bundle_id}` requires `bundle`. The time variables are zero-padded and rendered from the file's mtime (its last-modified time, from the device clock) in `timezone`; `{timezone}` is that instant's UTC offset in ISO 8601 basic format (`+0000`, `-0500`). timezone: allOf: - $ref: '#/components/schemas/FileRuleUploadTimezone' description: >- The time zone the time variables in `path` are rendered in: `utc`, or `device` for the device's local time zone. `utc` for a rule created without one. bundle: type: array minItems: 1 maxItems: 16 uniqueItems: true items: type: string pattern: ^[a-z][a-z0-9_]*$ example: - recording description: >- Names of the `source.glob` captures whose values group the rule's uploads into bundles: uploads from the same device and upload collection that captured the same values, in the order listed, share a bundle, across rules and over time. Capture names don't affect matching, so rules that name their captures differently still share a bundle when they list them in the same order. Every name must be a `source.glob` capture, listed once, with at most 16 names. Absent when the rule does not bundle. example: upload_collection_id: upl_col_123 upload_collection_name: Robot Logs bucket_id: bkt_123 bucket_name: my-uploads-bucket path: '{device_id}/{year}-{month}-{day}/{upload_id}/{file_name}' timezone: utc FileRuleRetention: title: File Rule Retention type: object description: | The retention block a file rule carries when it deletes local files; a rule without one keeps matching files indefinitely and Miru never deletes them. Retention operates in two phases. The retention guarantee ends once a matching file goes quiescent — its size and modification time have stayed unchanged for `source.stability_window_secs` — and, when `require_upload` is `true`, once its upload has been durably confirmed; the file is then eligible for deletion, and callers may no longer rely on it being present. `ttl_secs` schedules the enforcement that follows: how long the file lives on after the guarantee ends before the device deletes it. Both phases keep running on the device even when no release is deployed, so tearing down a deployment does not silently stop reclaiming disk. required: - ttl_secs properties: require_upload: type: boolean example: true description: >- Whether a file must have its upload durably confirmed before it may be deleted. Present exactly when the rule has an `upload` block. When `true`, a slow or failing upload keeps the local file: the device abandons an upload after 9 attempts, so a permanently failing upload retains the file indefinitely. When `false`, the upload is best-effort: the file may be deleted once eligible even if its upload has not completed, and an unfinished upload is abandoned. ttl_secs: type: integer format: int64 example: 604800 description: >- How long, in seconds, the file lives on after it becomes eligible for deletion. The clock starts when the retention guarantee ends, not when the file was written: this schedules enforcement of a guarantee that has already ended, so it defers the deletion, not the end of the guarantee. `0` means the file is deleted as soon as it becomes eligible. example: require_upload: true ttl_secs: 604800 FileRuleUploadTimezone: title: File Rule Upload Timezone type: string description: > The time zone a file rule renders its upload path's time variables (`{year}`, `{month}`, `{day}`, `{hour}`, `{minute}` and `{timezone}`) in. - `utc`: Coordinated Universal Time. - `device`: the device's local time zone, as the agent resolves it from the `TZ` environment variable or, when `TZ` is unset, the system time zone (`/etc/localtime` on Linux). The UTC offset is taken at the rendered instant, so it follows daylight saving time. A device running an agent that does not report its UTC offset renders in UTC. example: utc enum: - utc - device x-enum-varnames: - FILE_RULE_UPLOAD_TIMEZONE_UTC - FILE_RULE_UPLOAD_TIMEZONE_DEVICE securitySchemes: BearerAuth: type: http scheme: bearer description: >- The token from the agent's discovery file (`%ProgramData%\Miru\device-api\device-api.json` on Windows). Required over loopback TCP (`127.0.0.1:6478` by default on Windows) and accepted by every route; not used over the Unix socket. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.