{
  "title": "agent-registrations",
  "description": "Agent registrations bound to the organization. The `machinemail agent-registrations` commands: arguments, flags, examples and the API routes they call.",
  "canonical": "https://machinemail.dev/docs/cli/commands/agent-registrations",
  "content": {
    "introduction": "Agent registrations bound to the organization. Also spelled `agents`.",
    "commands": [
      {
        "command": "agent-registrations delete",
        "summary": "Revoke agent registration",
        "aliases": ["machinemail agent-registrations rm"],
        "details": {
          "description": "Revokes the registration; its tokens stop working immediately. Returns the registration with status: revoked (revoking twice is not an error). Requires an organization-scoped credential with api_key_delete.",
          "usage": "```bash\nmachinemail agent-registrations delete <agent-id> [flags]\n```",
          "arguments": [
            {
              "field": "<agent-id>",
              "type": "string",
              "required": true,
              "description": "ID of the registration."
            }
          ],
          "examples": ["```bash\nmachinemail agent-registrations delete reg_01m4fykg1y0000pkp9n2xbbzhg\n```"],
          "api": "[`DELETE /v0/agent-registrations/{agent_id}`](/content/docs/reference/api/agent-registrations#revoke-agent-registration/index.html)"
        }
      },
      {
        "command": "agent-registrations get",
        "summary": "Get agent registration",
        "details": {
          "description": "Requires an organization-scoped credential with api_key_read.",
          "usage": "```bash\nmachinemail agent-registrations get <agent-id> [flags]\n```",
          "arguments": [
            {
              "field": "<agent-id>",
              "type": "string",
              "required": true,
              "description": "ID of the registration."
            }
          ],
          "examples": ["```bash\nmachinemail agent-registrations get reg_01m4fykg1y0000pkp9n2xbbzhg\n```"],
          "api": "[`GET /v0/agent-registrations/{agent_id}`](/content/docs/reference/api/agent-registrations#get-agent-registration/index.html)"
        }
      },
      {
        "command": "agent-registrations list",
        "summary": "List agent registrations",
        "aliases": ["machinemail agent-registrations ls"],
        "details": {
          "description": "Agent registrations bound to the organization. Requires an organization-scoped credential with api_key_read; pod, inbox and sandbox credentials get 403.",
          "usage": "```bash\nmachinemail agent-registrations list [flags]\n```",
          "flags": [
            {
              "field": "--limit <n>",
              "type": "integer",
              "description": "Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`."
            },
            {
              "field": "--page-token <value>",
              "type": "string",
              "description": "next_page_token from the previous page."
            },
            {
              "field": "--ascending",
              "type": "boolean",
              "description": "Sort oldest first."
            },
            {
              "field": "--status",
              "type": "string",
              "description": "Only registrations with this status."
            },
            {
              "field": "--all",
              "type": "boolean",
              "description": "Follow next_page_token and return every page."
            }
          ],
          "examples": [
            "```bash\nmachinemail agent-registrations list\n```",
            "```bash\nmachinemail agent-registrations list --all --json | jq '.agent_registrations | length'\n```" 
          ],
          "api": "[`GET /v0/agent-registrations`](/content/docs/reference/api/agent-registrations#list-agent-registrations/index.html)"
        }
      }
    ]
  }
}