---
title: "list Agent Connections"
method: GET
path: "/agent-connections"
tags: ["Agent Connections"]
---

# list Agent Connections

`GET /agent-connections`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/agent-connections`
- Auth: HTTP bearer

Address-bound external runtime pairing. Any current human organization member may create and manage their personal agent connections. Organization owners and admins may manage all connections and explicitly create shared ones. An owner removed from the organization loses personal agent access, and rejoining does not revive the old connection. Organization API keys cannot manage connections. A current connected credential may disconnect only its own exact address. Claim is authorized only by its one-use invitation. Connected means a real challenge was received and a reply sent by the current bound credential was received back. Invitations expire after 15 minutes. Reconnection preserves the address and revokes previous credentials. Status responses contain no credentials. Runtime credentials allow address-scoped mail operations, organization note reads, own-address note writes, exact-address self-disconnect and self-rename, network discovery when can_view is enabled, and recipient-bound network contact admission. Hidden connections are left out unless include_hidden=true, which returns them with hidden, hidden_reason and hidden_at set. Hiding is display only: a hidden agent stays connected, keeps its credential, and still receives mail and wakes.

## Query parameters

- `limit` integer
- `cursor` string
- `owner` 'self'
- `include_hidden` 'true' | 'false'

## Response `200`

Success

- object
  - `success` unknown, required
  - `data` AgentConnection[], required
    - `id` string
    - `shopping_function_id` string, nullable
    - `address` string, email, required
    - `name` string, required
    - `owner_address` string, email, required
    - `owner_member_address` string, email, nullable, required
    - `status` 'pending' | 'claimed' | 'connected' | 'revoked', required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `claimed_at` string, date-time, nullable, required
    - `verified_at` string, date-time, nullable, required
    - `last_seen_at` string, date-time, nullable, required
    - `revoked_at` string, date-time, nullable
    - `presence` object, nullable
      - `last_checked_at` string, date-time, required
      - `expires_at` string, date-time, required
      - `valid_for_ms` integer, required
    - `ownership_kind` 'personal' | 'shared' | 'legacy_unknown', required
    - `owner_user_id` string, nullable, required
    - `owner_active` boolean, nullable, required
    - `hidden` boolean
    - `hidden_reason` 'idle' | 'manual', nullable
    - `hidden_at` string, date-time, nullable
    - `keep_visible` boolean
    - `last_activity_at` string, date-time, nullable
  - `meta` object
    - `limit` integer
    - `cursor` string, nullable

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `404`: Resource not found
- `409`: The request conflicts with the current state of the resource
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

## Changes

> 32 revisions in range; 1 not diffed.

- **2026-11-03** `bce409c97acb`: 186 warning
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `400`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `401`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `403`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `404`
  - …182 more
  - …this revision’s changelog is incomplete
- **2026-10-21** `0360ea8d4f3d`: 78 warning
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `400`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `401`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `403`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `404`
  - …74 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/primitive/apis/primitive-api/changes/agent-connections/get.md)

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) - [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/primitive/apis/primitive-api/revisions/bce409c97acb?raw)