List agents

GET /api/v2/storefront/agents Returns the partner agents registered to this storefront as compact summary rows, each with capability metadata and a per-agent account count. Filter by agent type, status, relationship, name, or supportsRegistration, and page with limit and offset.

Request

curl "https://api.apostra.com/api/v2/storefront/agents?type=SALES&status=ACTIVE&limit=10" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl "https://api.apostra.com/api/v2/storefront/agents?relationship=SELF&limit=10&offset=0" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Param	Type	Required	Notes
`type`	enum	No	Filter by agent type: `SALES`, `SIGNAL`, `CREATIVE`, or `OUTCOME`
`status`	enum	No	Filter by status: `PENDING`, `ACTIVE`, or `DISABLED`
`relationship`	enum	No	`SELF` = owned by you; `MARKETPLACE` = all other agents listed on Apostra
`name`	string	No	Partial, case-insensitive match on agent name
`supportsRegistration`	enum	No	`"true"` returns only agents that require operator authentication; `"false"` the rest
`limit`	integer	No	Page size (default 20, max 100)
`offset`	integer	No	Rows to skip (default 0)

Response

{
  "items": [
    {
      "agentId": "agt_premium_ctv",
      "type": "SALES",
      "name": "Premium CTV — Direct",
      "protocol": "MCP",
      "status": "ACTIVE",
      "relationship": "SELF",
      "requiresOperatorAuth": true,
      "requiresAccount": false,
      "authConfigured": true,
      "createdAt": "2026-05-01T12:00:00Z",
      "customerAccountCount": 2
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextOffset": null
}

status is PENDING, ACTIVE, or DISABLED, plus COMING_SOON for PENDING agents you don’t own. customerAccountCount is your own account count on the agent and replaces the embedded accounts array. When hasMore is true, pass nextOffset back as offset to walk pages.

Errors

400 VALIDATION_ERROR — invalid type, status, or relationship value, or out-of-range limit/offset.

See Errors for the full error contract.

Agent tasks

All agent operations

Agents overview

Agent types and OAuth concepts

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Agent tasks

Agents overview

​Request

​Parameters

​Response

​Errors

​Related

Agent tasks

Agents overview

Request

Parameters

Response

Errors

Related