---
title: "Enqueue an operator debug request for a Link Agent"
method: POST
path: "/link/agents/{id}/operator-debug"
tags: ["LinkAgent"]
---

# Enqueue an operator debug request for a Link Agent

`POST /link/agents/{id}/operator-debug`

Append an operator-issued debug request to the Agent's `operator_debug_queue`. The Agent picks it up on its next poll (≈ 10 s), executes idempotently, and acks via `operator_debug_results` on the following heartbeat. The api drops the queued entry on ack — callers watch `operator_debug_results` for the matching `request_id` to learn the outcome.

## Path parameters

- `id` string, required

## Request body

- LinkAgentOperatorDebugRequest — Operator-issued debug request, queued by the api on the LinkAgent and pulled by the Agent on its next poll. Discriminated by `action`; each variant has its own arg shape. Idempotent by design — the Agent dedupes by `request_id` (an LRU of the last 64 ids in-process), so the api re-sending a pending request after an Agent restart is a no-op rather than a re-execute.
  - `request_id` string, required — Opaque caller-supplied identifier (recommended: ULID). Agent dedupes by this value and surfaces it back on the ack.
  - `action` 'dump-state' | 'redial-carriers' | 'redial-carrier' | 'force-peer-ca-refetch' | 'synthetic-dial', required — Discriminator. Each value maps to a typed sub-schema with that action's argument shape.
  - `requested_at` string, date-time, required — When the api enqueued this request.
  - `requested_by` string — Operator identifier (e.g. mabl user id). Audit-only — not used for authorization.

## Response `202`

Request enqueued. The Agent acks on its next heartbeat.

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `404` — Link Agent not found
- `409` — Queue is full (16 entries) or the `request_id` collides with a still-pending request. Caller should drain the queue (let the Agent ack) or pick a fresh id.
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)