List agent and team catalog cards

Read browsable agent and team entries to choose targets for subsequent operations. This API does not return an individual agent’s A2A Agent Card.

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-cards

Before you call this API

Set PRODUCT_API_BASE_URL to the product API prefix https://api.moi.matrixorigin.cn/v5; use the corresponding product API URL for a dedicated deployment.

PRODUCT_API_BASE_URL includes the product prefix for the target environment. Prepare your credentials and an authorized WORKSPACE_ID. The path ID must match X-Workspace-ID. Replace example IDs with actual values returned in that environment.

Request

curl --get "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-cards" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "catalog=workspace" \
  --data-urlencode "query=$SEARCH_TEXT" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

Query parameter

Type

Required

Description

catalog

string

No

workspace reads agents and teams in the current workspace; system reads system agents. Omission combines browsable sources.

query

string

No

Search condition for display information such as names. Do not rename it to keyword.

include_development

boolean

No

true or 1 includes development definitions of system agents in catalog filtering. Defaults to false when omitted; this does not bypass authorization.

limit

integer

No

Defaults to 50. Values at or below 0 use the default; values above 200 are capped at 200.

offset

integer

No

Defaults to 0; negative values become 0.

kind determines whether subsequent operations target an agent or a team. workspace_id is the entry’s source workspace and may be system; do not always replace it with the current workspace.

Successful response

{"code":0,"data":{"items":[{"kind":"agent","id":"agent-example","workspace_id":"system","name":"示例智能体","status":"active","version":1,"updated_at":"2026-11-12T01:02:03Z","actions":["chat","connect_im","api_invoke","create_scheduled_task"],"requires_agent_model":true}],"total":1,"limit":20,"offset":0}}

Field

Type

Description

data.items

array

Catalog cards on this page.

data.items[].kind

string

agent or team.

data.items[].id

string

Object ID for the corresponding kind.

data.items[].workspace_id

string

Object source workspace; retain it together with kind and id.

data.items[].name

string

Display name in the current language.

data.items[].description

string

Optional description.

data.items[].avatar_ref

string

Optional avatar reference.

data.items[].status

string

Entry status. The current catalog selects active entries.

data.items[].version

integer

Optional agent version; team entries do not guarantee this field.

data.items[].updated_at

string

Most recent update time.

data.items[].actions

string[]

Action identifiers shown in the catalog. They do not replace authorization or establish success for specific actions.

data.items[].requires_agent_model

boolean

Optional. true means an agent model must still be prepared. Omission or false does not guarantee that all runtime prerequisites are satisfied.

data.total

integer

Total entries for the selected sources and filters, not the number on this page.

data.limit

integer

Effective page limit.

data.offset

integer

Current offset.

Display language follows the current Content-Language and actual response. Results sort by updated_at descending, then by kind, workspace_id, and id for ties. Catalog changes during pagination may affect subsequent pages.

Paginate and continue

Keep the same filters and increase offset by the returned limit. Stop when offset + limit >= total. The following reads the next page only if the preceding page actually returned limit 20 and total greater than 20:

curl --get "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-cards" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "catalog=workspace" \
  --data-urlencode "query=$SEARCH_TEXT" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=20"

For an agent entry, retrieve that agent’s A2A invocation information. For a team entry, use team APIs; do not pass a team ID directly to agent A2A. actions is a display reference. Each invocation revalidates identity, roles, and resource conditions.

Errors

Invalid input such as an unsupported source category can return HTTP 400. Handle identity, authorization, dependency, and read failures according to the actual response. Ordinary domain errors for this action use numeric code/message/details; the authorization layer may use a string code. Do not assume one uniform envelope for all errors. A failed read provides no successful page from which to continue pagination.

Last updated on