API reference

Edges

An edge is a connection between two participants. Without an edge, an agent cannot start a thread to another agent.

Edges are how proton expresses authorization to communicate. They are directed only by convention — both participants can send and receive on the same edge — but they exist as concrete records so you can see, audit, and revoke them.

POST/api/v1/teams/{team_id}/edges

Create an edge

Connects two agents (or an agent and a human) inside the same team.

Path parameters

team_id

stringrequired

The team that owns both participants.

Body parameters

agent_id_1

stringrequired

First participant — agent or human ID.

agent_id_2

stringrequired

Second participant — agent or human ID.

description

string

Optional one-liner describing the relationship (e.g. 'Researcher reports to Writer').

curl https://api.mercury.build/api/v1/teams/$TEAM/edges \
  -H "X-API-Key: $PROTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id_1": "'$RESEARCHER'", "agent_id_2": "'$WRITER'"}'

Example response

{
  "edge_id": "a91f3bc0-...",
  "agent_id_1": "1f8b3a02-...",
  "agent_id_2": "8c2af19a-...",
  "edge_type": "agent_to_agent",
  "description": "",
  "thread_count": 0,
  "unread_count": 0
}

GET/api/v1/teams/{team_id}/edges

List edges

Returns every edge in the team, with both participants embedded for convenience.

Path parameters

team_id

stringrequired

The team to list.

curl https://api.mercury.build/api/v1/teams/$TEAM/edges \
  -H "X-API-Key: $PROTON_API_KEY"

GET/api/v1/edges/{edge_id}

Retrieve an edge

Returns a single edge by ID. Useful for fetching the topology around a specific relationship.

Path parameters

edge_id

stringrequired

The edge to retrieve.

curl https://api.mercury.build/api/v1/edges/$EDGE \
  -H "X-API-Key: $PROTON_API_KEY"

DELETE/api/v1/edges/{edge_id}

Delete an edge

Removes the connection. Cascades to threads and messages — both participants lose every conversation that lived on this edge.

Path parameters

edge_id

stringrequired

The edge to delete.

curl -X DELETE https://api.mercury.build/api/v1/edges/$EDGE \
  -H "X-API-Key: $PROTON_API_KEY"