7441c9f298
All findings from the inaugural LeadValidator audit resolved and confirmed. Release gate: PASS. VV_ISSUE_002 (BLOCKER): 15 OpenAPI specs verified present covering all 20 route groups (46 endpoints documented in docs/openapi/) VV_ISSUE_003 (MAJOR): Remove any types from src/db/pool.ts — replaced pool.query shim with unknown[] + Object.defineProperty, zero any types, eslint-disable suppressions removed VV_ISSUE_004 (MAJOR): Remove raw Pool from ScaffoldController and HealthDetailedController — injected AgentRepository/CredentialRepository and DbProbe interface respectively; added CredentialRepository.findActiveClientId() VV_ISSUE_005 (MAJOR): Add unit tests for 5 untested services — ComplianceStatusStore, EventPublisher, MarketplaceService, OIDCTrustPolicyService, UsageService VV_ISSUE_006 (MAJOR): Add integration tests for 7 missing route groups — analytics, billing, tiers, webhooks, marketplace, oidc-trust-policies, oidc-token-exchange VV_ISSUE_001 (MINOR): Create missing design.md and tasks.md in 4 OpenSpec archives — all archives now complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
389 lines
13 KiB
YAML
389 lines
13 KiB
YAML
openapi: "3.0.3"
|
|
|
|
info:
|
|
title: SentryAgent.ai — Public Agent Marketplace
|
|
version: 1.0.0
|
|
description: |
|
|
Public Agent Marketplace endpoints for the SentryAgent.ai AgentIdP platform.
|
|
|
|
The marketplace enables discovery of AI agents that have been explicitly
|
|
marked as public (`isPublic: true`) by their owners. It is a read-only
|
|
public catalog — no authentication required.
|
|
|
|
**Feature flag:** When `MARKETPLACE_ENABLED=false` all routes return `404`.
|
|
|
|
**Unauthenticated endpoints:**
|
|
- `GET /marketplace/agents` — Paginated list of public agents with search and filters
|
|
- `GET /marketplace/agents/:agentId` — Detailed public agent with DID Document
|
|
|
|
servers:
|
|
- url: http://localhost:3000/api/v1
|
|
description: Local development server
|
|
- url: https://api.sentryagent.ai/v1
|
|
description: Production server
|
|
|
|
tags:
|
|
- name: Marketplace
|
|
description: Public agent discovery endpoints (unauthenticated)
|
|
|
|
components:
|
|
schemas:
|
|
MinimalDIDDocument:
|
|
type: object
|
|
description: Minimal W3C DID Document returned with marketplace agent detail.
|
|
required:
|
|
- "@context"
|
|
- id
|
|
- controller
|
|
- verificationMethod
|
|
- authentication
|
|
properties:
|
|
"@context":
|
|
type: array
|
|
items:
|
|
type: string
|
|
example:
|
|
- "https://www.w3.org/ns/did/v1"
|
|
id:
|
|
type: string
|
|
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
controller:
|
|
type: string
|
|
example: "did:web:api.sentryagent.ai"
|
|
verificationMethod:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Verification methods from the DID Document.
|
|
authentication:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
MarketplaceAgentCard:
|
|
type: object
|
|
description: |
|
|
Public agent card returned by the marketplace. Contains only information
|
|
that the agent owner has explicitly made public.
|
|
required:
|
|
- agentId
|
|
- agentType
|
|
- version
|
|
- capabilities
|
|
- owner
|
|
- deploymentEnv
|
|
- publishedAt
|
|
properties:
|
|
agentId:
|
|
type: string
|
|
format: uuid
|
|
description: Unique identifier of the agent.
|
|
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
agentType:
|
|
type: string
|
|
description: Functional classification of the agent.
|
|
enum:
|
|
- screener
|
|
- classifier
|
|
- orchestrator
|
|
- extractor
|
|
- summarizer
|
|
- router
|
|
- monitor
|
|
- custom
|
|
example: "screener"
|
|
version:
|
|
type: string
|
|
description: Semantic version string of the agent.
|
|
example: "1.4.2"
|
|
capabilities:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of capability strings (`resource:action` format).
|
|
example:
|
|
- "resume:read"
|
|
- "email:send"
|
|
- "candidate:score"
|
|
owner:
|
|
type: string
|
|
description: Team or organization that owns this agent.
|
|
example: "talent-acquisition-team"
|
|
deploymentEnv:
|
|
type: string
|
|
enum:
|
|
- development
|
|
- staging
|
|
- production
|
|
example: "production"
|
|
did:
|
|
type: string
|
|
nullable: true
|
|
description: W3C DID identifier for this agent, if one has been generated.
|
|
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
didDocument:
|
|
$ref: '#/components/schemas/MinimalDIDDocument'
|
|
nullable: true
|
|
description: Minimal W3C DID Document for this agent, if a DID has been generated.
|
|
publishedAt:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when this agent was made public.
|
|
example: "2026-03-01T08:00:00.000Z"
|
|
|
|
PaginatedMarketplaceResponse:
|
|
type: object
|
|
description: Paginated marketplace listing response.
|
|
required:
|
|
- data
|
|
- total
|
|
- page
|
|
- limit
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/MarketplaceAgentCard'
|
|
total:
|
|
type: integer
|
|
description: Total number of public agents matching the query.
|
|
example: 58
|
|
page:
|
|
type: integer
|
|
description: Current page number (1-based).
|
|
example: 1
|
|
limit:
|
|
type: integer
|
|
description: Number of results per page.
|
|
example: 20
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
description: Standard error response envelope.
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
example: "AGENT_NOT_FOUND"
|
|
message:
|
|
type: string
|
|
example: "Agent with the specified ID was not found."
|
|
details:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
paths:
|
|
/marketplace/agents:
|
|
get:
|
|
operationId: listPublicAgents
|
|
tags:
|
|
- Marketplace
|
|
summary: List public agents
|
|
description: |
|
|
Returns a paginated list of agents that have been marked as public.
|
|
|
|
Supports full-text search across `owner`, `capabilities`, and `agentType`
|
|
via the `q` parameter. Results can be filtered by `capability` or `publisher`.
|
|
|
|
**Unauthenticated** — no Bearer token required.
|
|
|
|
Returns `404` when the `MARKETPLACE_ENABLED` feature flag is set to `false`.
|
|
security: []
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: false
|
|
description: |
|
|
Full-text search query across agent owner, capabilities, and agent type.
|
|
schema:
|
|
type: string
|
|
example: "resume screener"
|
|
- name: capability
|
|
in: query
|
|
required: false
|
|
description: Filter by a specific capability string (exact match).
|
|
schema:
|
|
type: string
|
|
example: "resume:read"
|
|
- name: publisher
|
|
in: query
|
|
required: false
|
|
description: Filter by owner/publisher name (exact match).
|
|
schema:
|
|
type: string
|
|
example: "talent-acquisition-team"
|
|
- name: page
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 1
|
|
example: 1
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
default: 20
|
|
example: 20
|
|
responses:
|
|
'200':
|
|
description: Paginated list of public agents returned successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PaginatedMarketplaceResponse'
|
|
example:
|
|
data:
|
|
- agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
agentType: "screener"
|
|
version: "1.4.2"
|
|
capabilities:
|
|
- "resume:read"
|
|
- "email:send"
|
|
- "candidate:score"
|
|
owner: "talent-acquisition-team"
|
|
deploymentEnv: "production"
|
|
did: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
didDocument: null
|
|
publishedAt: "2026-03-01T08:00:00.000Z"
|
|
- agentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
|
agentType: "classifier"
|
|
version: "2.1.0"
|
|
capabilities:
|
|
- "document:classify"
|
|
- "label:write"
|
|
owner: "platform-team"
|
|
deploymentEnv: "staging"
|
|
did: null
|
|
didDocument: null
|
|
publishedAt: "2026-03-10T10:00:00.000Z"
|
|
total: 58
|
|
page: 1
|
|
limit: 20
|
|
'400':
|
|
description: Invalid query parameters.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "VALIDATION_ERROR"
|
|
message: "Invalid query parameter value."
|
|
details:
|
|
field: "limit"
|
|
reason: "Must be between 1 and 100."
|
|
'404':
|
|
description: Marketplace is not enabled on this instance.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "NOT_FOUND"
|
|
message: "The Agent Marketplace is not enabled on this instance."
|
|
'500':
|
|
description: Unexpected server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "INTERNAL_SERVER_ERROR"
|
|
message: "An unexpected error occurred. Please try again later."
|
|
|
|
/marketplace/agents/{agentId}:
|
|
get:
|
|
operationId: getPublicAgent
|
|
tags:
|
|
- Marketplace
|
|
summary: Get public agent detail
|
|
description: |
|
|
Returns the full public profile for a specific marketplace-listed agent,
|
|
including its DID Document (if a DID has been generated).
|
|
|
|
Only agents with `isPublic: true` are accessible via this endpoint.
|
|
Attempting to retrieve a private agent returns `404`.
|
|
|
|
**Unauthenticated** — no Bearer token required.
|
|
|
|
Returns `404` when the `MARKETPLACE_ENABLED` feature flag is set to `false`.
|
|
security: []
|
|
parameters:
|
|
- name: agentId
|
|
in: path
|
|
required: true
|
|
description: UUID of the public agent.
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
responses:
|
|
'200':
|
|
description: Public agent detail returned successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/MarketplaceAgentCard'
|
|
example:
|
|
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
agentType: "screener"
|
|
version: "1.4.2"
|
|
capabilities:
|
|
- "resume:read"
|
|
- "email:send"
|
|
- "candidate:score"
|
|
owner: "talent-acquisition-team"
|
|
deploymentEnv: "production"
|
|
did: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
didDocument:
|
|
"@context":
|
|
- "https://www.w3.org/ns/did/v1"
|
|
id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
controller: "did:web:api.sentryagent.ai"
|
|
verificationMethod:
|
|
- id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
|
type: "JsonWebKey2020"
|
|
controller: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
publicKeyJwk:
|
|
kty: "EC"
|
|
crv: "P-256"
|
|
x: "f83OJ3D..."
|
|
y: "x_FEzRu..."
|
|
authentication:
|
|
- id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
|
publishedAt: "2026-03-01T08:00:00.000Z"
|
|
'404':
|
|
description: Agent not found, not public, or marketplace not enabled.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
examples:
|
|
agentNotFound:
|
|
summary: Agent not found or not public
|
|
value:
|
|
code: "AGENT_NOT_FOUND"
|
|
message: "Agent with the specified ID was not found."
|
|
marketplaceDisabled:
|
|
summary: Marketplace feature disabled
|
|
value:
|
|
code: "NOT_FOUND"
|
|
message: "The Agent Marketplace is not enabled on this instance."
|
|
'500':
|
|
description: Unexpected server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "INTERNAL_SERVER_ERROR"
|
|
message: "An unexpected error occurred. Please try again later."
|