Support Scope3 Storefront REST API (/api/v1)

[bokelley]

Context

The snap-adcp server (yokohama-v11 branch bokelley/client-agent-creator) now exposes a publisher REST API at /api/v1 with WorkOS OAuth authentication. This is the same auth mechanism the builder MCP uses.

New Endpoints Available

All endpoints are owner-scoped (JWT sub = WorkOS user ID).

Public (no auth):

• GET /api/v1/openapi.json — OpenAPI 3.1 spec
• GET /api/v1/skill.md — Claude-readable API documentation
• GET /api/v1/.well-known/oauth-authorization-server — OAuth metadata
• GET /api/v1/.well-known/oauth-protected-resource — Resource metadata

Authenticated (Bearer token):

• Agent CRUD: GET/POST/PUT/DELETE /api/v1/agents
• Traces: GET/POST /api/v1/agents/{id}/traces
• Tasks: GET /api/v1/agents/{id}/tasks, GET/POST /api/v1/tasks/{id}/*
• Config: PUT /api/v1/agents/{id}/capabilities|notifications|llm-provider|inbound-filters
• Policy: POST /api/v1/agents/{id}/synthesize-policy
• Files: POST /api/v1/agents/{id}/upload, GET /api/v1/agents/{id}/file-uploads
• Evals: POST /api/v1/agents/{id}/evals, GET /api/v1/evals/{id}, POST /api/v1/evals/compare
• Audit: GET /api/v1/agents/{id}/config-changes

What agentic-client needs

1. Add publisher API support — new persona or environment pointing at /api/v1 base URL
2. Fetch skill.md — GET /api/v1/skill.md for Claude-readable reference
3. Optionally use OpenAPI spec — GET /api/v1/openapi.json for type generation or request validation
4. Auth — WorkOS OAuth (same flow as builder MCP)

References

• PR with the publisher API will be on branch bokelley/client-agent-creator
• Skill.md content documents all endpoints with examples and common workflows