sentryagent-idp/openspec/changes/phase-4-developer-growth/specs/agent-marketplace/spec.md

ADDED Requirements

Requirement: Marketplace listing endpoint returns public agent registry

The system SHALL expose GET /marketplace/agents returning a paginated list of publicly visible agents. Each listing SHALL include: agentId, name, description, capabilities (array of strings), publisherName, did, createdAt. The endpoint SHALL be unauthenticated (public access). Agents are included in the marketplace when their isPublic flag is true.

Scenario: Unauthenticated user lists marketplace agents

• WHEN an unauthenticated client calls GET /marketplace/agents
• THEN the response is HTTP 200 with a paginated list of public agents

Scenario: Pagination works correctly

• WHEN a client calls GET /marketplace/agents?page=2&limit=20
• THEN the response returns the correct page of results with totalCount, page, and totalPages in the response envelope

Requirement: Marketplace search filters agents by capability, publisher, or name

The system SHALL support GET /marketplace/agents?q=<search> performing a case-insensitive search across agent name, description, and capabilities. The system SHALL also support GET /marketplace/agents?capability=<cap> and GET /marketplace/agents?publisher=<name> for structured filtering.

Scenario: Full-text search returns relevant agents

• WHEN a client calls GET /marketplace/agents?q=translation
• THEN agents whose name, description, or capabilities contain "translation" are returned

Scenario: Capability filter returns matching agents

• WHEN a client calls GET /marketplace/agents?capability=nlp
• THEN only agents with "nlp" in their capabilities array are returned

Requirement: Marketplace detail endpoint returns agent with DID document

The system SHALL expose GET /marketplace/agents/:agentId returning the full public agent profile including the W3C DID document and AGNTCY agent card. The endpoint SHALL be unauthenticated.

Scenario: Agent detail includes DID document

• WHEN a client calls GET /marketplace/agents/:agentId for a public agent
• THEN the response includes agentId, name, description, capabilities, did, didDocument, agentCard, and publisherName

Scenario: Private agent returns 404 on marketplace

• WHEN a client calls GET /marketplace/agents/:agentId for an agent with isPublic: false
• THEN the response is HTTP 404

Requirement: Agents can be published to or withdrawn from the marketplace

The system SHALL allow authenticated tenant users to set isPublic: true on an agent via PATCH /agents/:agentId ({ "isPublic": true }), making it appear in the marketplace. Setting isPublic: false removes it from marketplace listings without deleting the agent.

Scenario: Agent published to marketplace

• WHEN an authenticated user calls PATCH /agents/:agentId with { "isPublic": true }
• THEN the agent appears in GET /marketplace/agents results

Scenario: Agent withdrawn from marketplace

• WHEN an authenticated user calls PATCH /agents/:agentId with { "isPublic": false }
• THEN the agent no longer appears in GET /marketplace/agents results