Agent mesh

Serverhttps://mqqsoutginqsajeuttyp.supabase.co/functions/v1

An organization's private agent mesh (agentsmesh.one): quote, approve, status, and enroll, bind or revoke its members. Callable with a developer key (developerKey); a key always acts on its own organization.

Approve or dismiss the organization's agent mesh request

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/agent-mesh-approve

The approval card's click, or the same decision by a developer key. A request is opened by the organization's avatar; approving it provisions the mesh (up to ~90 s) and enrolls the requesting avatar as the first member. The outcome is recorded on the request.

A signed-in company admin's JWT moves the request through their own RLS client.
A developer key may approve or dismiss only a request its own organization holds and that exists (another organization's request is 404). It acts on behalf of the admin who created the key: the order still requires that person to be a company admin of the organization (403 otherwise), and each click is recorded in developer_audit_events before the request moves (503 when that record cannot be written).

Approve or dismiss the organization's agent mesh request › Request Body

MeshApproveRequest

requestId

Uuid · uuid · required

action

string · enum · required

Enum values:

approve

cancel

Approve or dismiss the organization's agent mesh request › Responses

The click was recorded; a re-click on a completed request answers its slug.

requestId

string · uuid · required

approved

boolean · const

Const value:

cancelled

boolean · const

Const value:

status

string · const

Const value: completed

slug

string | null

result_code

string | null

Bind a member's publish role once its node has joined

PUT

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/agent-mesh-enroll

After agentmesh-node join with the member's token: looks the node up on the control plane and binds the member's own a2a://<name> publish role to its peer id. 409 not_joined before the join. The service role, or a developer key on its own organization (the external agent's developer calls this after the join, as cowork does for avatars).

Bind a member's publish role once its node has joined › Request Body

An existing member of the organization's mesh (re-mint its token, or confirm its node joined).

MeshMemberRef

mesh_id

Uuid · uuid · required

member_id

Uuid · uuid · required

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

Bind a member's publish role once its node has joined › Responses

The member is enrolled under its peer id.

MeshJoined

member_id

Uuid · uuid · required

state

string · const · required

Const value: enrolled

peer_id

string · required

service

string · required

PUT/agent-mesh-enroll

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/agent-mesh-enroll \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "mesh_id": "00000000-0000-0000-0000-000000000000",
  "member_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "mesh_id": "00000000-0000-0000-0000-000000000000",
  "member_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "member_id": "00000000-0000-0000-0000-000000000000",
  "state": "enrolled",
  "peer_id": "peer_id",
  "service": "service"
}

json

application/json

Invite an agent to the mesh, or re-mint an invited member's token

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/agent-mesh-enroll

Two forms. Invite (MeshInviteRequest): admits an avatar or an external agent and returns a one-use bootstrap token, valid 24 h and shown once, for agentmesh-node join. Re-mint (MeshMemberRef): a fresh token for an existing invited member; no new row.

A developer key may use both forms, always on its own organization (a body organization_id is ignored). A signed-in company admin may invite. The service role (cowork's mesh runner) may use both.

Invite an agent to the mesh, or re-mint an invited member's token › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: principal
	type = object · requires: mesh_id, member_id

Properties for Variant 1:

MeshInviteRequest

MeshPrincipal · required

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

display_name

string · minLength: 1 · maxLength: 80

labels

string[] · maxItems: 16

Invite an agent to the mesh, or re-mint an invited member's token › Responses

The member and its bootstrap token (Cache-Control: no-store).

Shown once (`Cache-Control: no-store`). The bootstrap token is one-use and valid 24 h.

MeshEnrollment

member_id

Uuid · uuid · required

service_name

string · required

control_plane_url

string · uri · required

bootstrap_token

string · required

expires_at

string | null · date-time · required

POST/agent-mesh-enroll

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/agent-mesh-enroll \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "principal": {
    "kind": "avatar",
    "avatar_type": "avatar_type"
  },
  "display_name": "display_name",
  "labels": [
    "string"
  ]
}'

Example Request Body

{
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "principal": {
    "kind": "avatar",
    "avatar_type": "avatar_type"
  },
  "display_name": "display_name",
  "labels": [
    "string"
  ]
}

json

Example Responses

{
  "member_id": "00000000-0000-0000-0000-000000000000",
  "service_name": "service_name",
  "control_plane_url": "https://www.example.com/path/to/resource",
  "bootstrap_token": "bootstrap_token",
  "expires_at": "2024-08-25T15:00:00Z"
}

json

application/json

Revoke a member of the mesh

DELETE

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/agent-mesh-enroll

Bans the member's node when its peer id is known, revokes its unused token otherwise, and marks the member revoked. A developer key (its own organization), a signed-in company admin, or the service role.

Revoke a member of the mesh › Request Body

MeshRevokeRequest

member_id

Uuid · uuid · required

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

reason

string · maxLength: 200

Revoke a member of the mesh › Responses

The member is revoked.

MeshRevoked

member_id

Uuid · uuid · required

state

string · const · required

Const value: revoked

method

string · enum · required

Enum values:

ban

token_revoke

none

Quote the organization's private agent mesh

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/agent-mesh-quote

Search only, never a side effect: the mesh's public name (slug), the host it would run on and the plan gate, plus the existing mesh if there is one. A mesh is provisioned only when a request is approved (/agent-mesh-approve).

A developer key is always quoted for its own organization; a body organization_id is ignored. The service role (the avatar worker) names the organization in the body.

Quote the organization's private agent mesh › Request Body

MeshQuoteRequest

avatar_type

MeshAvatarType · pattern: ^[a-z][a-z0-9_]{1,63… · required

An avatar type from the persona registry, e.g. language_tutor.

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

Quote the organization's private agent mesh › Responses

The quote. available is false with a reason when the mesh cannot be ordered now.

MeshQuote

slug

string · required

host

string · enum · required

Enum values:

fly

local

available

boolean · required

object · required

reason

string · enum

Enum values:

unknown_avatar

payment_not_confirmed

mesh_being_released

host_unconfigured

MeshStatus

Where the organization's mesh stands. Never a credential.

POST/agent-mesh-quote

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/agent-mesh-quote \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "avatar_type": "avatar_type"
}'

Example Request Body

{
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "avatar_type": "avatar_type"
}

json

Example Responses

{
  "slug": "slug",
  "host": "fly",
  "available": true,
  "price": {
    "plan_gate": "paid_plan"
  },
  "reason": "unknown_avatar",
  "existing": {
    "mesh_id": "00000000-0000-0000-0000-000000000000",
    "state": "reserved",
    "slug": "slug",
    "host": "fly",
    "control_plane_url": "https://www.example.com/path/to/resource",
    "ready": true,
    "last_error": "last_error",
    "members": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "principal_kind": "avatar",
        "avatar_type": "avatar_type",
        "external_agent_id": "00000000-0000-0000-0000-000000000000",
        "display_name": "display_name",
        "service": "service",
        "state": "invited",
        "peer_id": "peer_id"
      }
    ]
  }
}

json

application/json

Read where the organization's agent mesh stands

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/agent-mesh-status

Reads, never acts; never a credential. POST with a body, like the other ACP reads. A developer key reads its own organization's mesh; a body organization_id is ignored. The service role (worker, cowork) names the organization in the body.

Read where the organization's agent mesh stands › Request Body

MeshStatusRequest

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

Read where the organization's agent mesh stands › Responses

The mesh and its live members.

Where the organization's mesh stands. Never a credential.

MeshStatus

mesh_id

Uuid · uuid · required

state

string · enum · required

Enum values:

reserved

provisioning

active

releasing

released

failed

slug

string · required

The mesh's public name, <org-slug>-<4 hex>.

host

string · enum · required

Enum values:

fly

local

control_plane_url

string | null · uri · required

ready

boolean · required

last_error

string | null · required

MeshMember[] · required

POST/agent-mesh-status

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/agent-mesh-status \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "organization_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "organization_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "mesh_id": "00000000-0000-0000-0000-000000000000",
  "state": "reserved",
  "slug": "slug",
  "host": "fly",
  "control_plane_url": "https://www.example.com/path/to/resource",
  "ready": true,
  "last_error": "last_error",
  "members": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "principal_kind": "avatar",
      "avatar_type": "avatar_type",
      "external_agent_id": "00000000-0000-0000-0000-000000000000",
      "display_name": "display_name",
      "service": "service",
      "state": "invited",
      "peer_id": "peer_id"
    }
  ]
}

json

application/json

Agent claims