Menu
GET browser-runtimes/ Service tier

GET /api/internal/v1/browser-runtimes/

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/browser-runtimes/

Responses

200 bare JSON object (no envelope)

{
  "data": [
    {
      "url": "...",
      "internal_url": "...",
      "name": "...",
      "zone": "...",
      "version": "...",
      "max_sessions": "...",
      "active_sessions": "...",
      "free": "...",
      "draining": "...",
      "enabled": true,
      "status": "...",
      "uptime_s": "...",
      "age_s": "...",
      "last_seen_at": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "count": 0,
    "live": "...",
    "env_fallback": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/browser-runtimes/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/browser_views.py (browser_views.browser_runtimes_list)

POST browser-runtimes/heartbeat/ Service tier

POST /api/internal/v1/browser-runtimes/heartbeat/ Body = the runtime's fleet.describe(): {url, name, zone, version, max_sessions, active_sessions, draining, uptime_s}.

This read is not paginated. It returns at most 80 rows and does not report a total, so a result of exactly 80 may be truncated.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/browser-runtimes/heartbeat/

Body keys (JSON)

KeyRequiredDefault
drainingoptional or conditionalnone
internal_urloptional or conditionalnone
nameoptional or conditionalnone
urloptional or conditionalnone
versionoptional or conditionalnone
zoneoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 bare JSON object (no envelope)

{
  "data": {
    "registered": true,
    "created": true,
    "enabled": true
  },
  "meta": {}
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
400url_required

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/browser-runtimes/heartbeat/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "draining": "...",
  "internal_url": "...",
  "name": "...",
  "url": "...",
  "version": "...",
  "zone": "..."
}'

Source: MatterCore/browser_views.py (browser_views.browser_runtime_heartbeat)

GET calls/{channel}/screens/ Service tier

GET /api/internal/v1/calls/<channel>/screens/ : the agents sharing their browser on this call right now.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/calls/{channel}/screens/

Path parameters

NameType
channelstr

Responses

200 bare JSON object (no envelope)

{
  "data": [
    {
      "...": "..."
    }
  ],
  "meta": {
    "count": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/calls/CHANNEL/screens/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/browser_views.py (browser_views.call_screens)

GET calls/{channel}/screens/{share_id}/frame/ Service tier

GET /api/internal/v1/calls/<channel>/screens/<share_id>/frame/?after=N

The latest frame of a shared screen if newer than N, else 204. X-Sharing: no when the share has ended (Comms drops the tile).

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/calls/{channel}/screens/{share_id}/frame/

Path parameters

NameType
channelstr
share_idstr

Query parameters

NameDefault
afternone

Responses

204 non-JSON body

binary or text body

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X GET "https://agents.mattering.io/api/internal/v1/calls/CHANNEL/screens/SHARE_ID/frame/?after=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/browser_views.py (browser_views.call_screen_frame)

POST calls/{channel}/screens/{share_id}/input/ Service tier

POST /api/internal/v1/calls/<channel>/screens/<share_id>/input/ {kind, x, y, dy, text, key}: a driving person's click / scroll / typing, relayed to the runtime (which refuses it unless take-over is on).

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/calls/{channel}/screens/{share_id}/input/

Path parameters

NameType
channelstr
share_idstr

Responses

200 bare JSON object (no envelope)

...

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400bad_json
404share_not_found

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/calls/CHANNEL/screens/SHARE_ID/input/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/browser_views.py (browser_views.call_screen_input)

POST calls/{channel}/screens/{share_id}/takeover/ Service tier

POST /api/internal/v1/calls/<channel>/screens/<share_id>/takeover/ {on}. A person on the call takes (or gives back) the agent's browser. Comms has already checked they are a member IN the call; the viewer's email rides in X-Internal-User-Email for the log.

URL

  • Service tierhttps://agents.mattering.io/api/internal/v1/calls/{channel}/screens/{share_id}/takeover/

Path parameters

NameType
channelstr
share_idstr

Responses

200 bare JSON object (no envelope)

...

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400bad_json
404share_not_found

Example

curl -X POST "https://agents.mattering.io/api/internal/v1/calls/CHANNEL/screens/SHARE_ID/takeover/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: MatterCore/browser_views.py (browser_views.call_screen_takeover)

All Agents resources
Start Free Explore our Products