{"openapi":"3.0.3","info":{"title":"AgentStudio Core API","description":"AI agent marketplace API by LiminaHub. Publishers create autonomous AI agents,\nusers discover, install, configure, and chat with them.\n\n## Authentication\nAll authenticated endpoints require a JWT token in an httpOnly cookie named `token`.\nThe cookie is set automatically by the OAuth sign-in flow.\nFor programmatic access, use the `Authorization: Bearer <token>` header.\n\n## Response Envelope\nAll endpoints return `{ data: T }`. Error responses return `{ error: \"message\" }`.\n\n## Streaming (SSE)\nChat and Try endpoints use Server-Sent Events. Event types:\n`text`, `tool_start`, `tool_result`, `message_id`, `sandbox_info`, `error`, `done`.\n\n## AGNTCY / OASF\nAgentStudio implements the AGNTCY protocol for agent interoperability.\nDirectory and discovery endpoints follow OASF (Open Agent Schema Format) v1.0.0.\n","version":"1.0.0","contact":{"name":"LiminaHub","url":"https://liminahub.ai"},"license":{"name":"Proprietary"}},"servers":[{"url":"http://localhost:4000","description":"Local development"},{"url":"https://api.agentstudio.liminahub.ai","description":"Production"}],"tags":[{"name":"Auth","description":"OAuth sign-in, session management, sign-out"},{"name":"Agents","description":"Browse, search, detail, chat, try, execute agents"},{"name":"Installs","description":"Install, uninstall, manage agent installations"},{"name":"Runs","description":"Agent execution runs and message history"},{"name":"Integrations","description":"Integration manifests, credentials, configuration"},{"name":"Publishers","description":"Publisher profile, agent CRUD, AI generation"},{"name":"Bundles","description":"Multi-agent solution bundles and pipeline execution"},{"name":"Background","description":"Cron/webhook/manual background agent execution"},{"name":"Reviews","description":"Agent ratings and reviews"},{"name":"Recommendations","description":"Personalized and collaborative-filtering recommendations"},{"name":"Messages","description":"Message feedback (thumbs up/down)"},{"name":"Categories","description":"Agent categories"},{"name":"Stripe","description":"Stripe Connect onboarding, checkout, webhooks"},{"name":"User Keys","description":"BYOK LLM provider API keys"},{"name":"Admin","description":"Admin agent review and approval"},{"name":"Directory","description":"AGNTCY-compatible agent directory (OASF)"},{"name":"Webhooks","description":"External webhook triggers for background agents"},{"name":"Cron","description":"Internal cron scheduler"},{"name":"Discovery","description":"Agent capability-based search and OASF taxonomy"},{"name":"Reputation","description":"Agent performance scoring, badges, and trending"},{"name":"Well-Known","description":"AGNTCY instance discovery"},{"name":"MCP","description":"Model Context Protocol server (StreamableHTTP transport)"}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"token","description":"JWT httpOnly cookie set by OAuth sign-in"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"cronSecret":{"type":"http","scheme":"bearer","description":"CRON_SECRET environment variable"},"webhookSecret":{"type":"apiKey","in":"header","name":"x-webhook-secret","description":"Per-install webhook secret"}},"schemas":{"AgentStatus":{"type":"string","enum":["DRAFT","SUBMITTED","IN_REVIEW","APPROVED","PUBLISHED","DEPRECATED","REMOVED"]},"PricingModel":{"type":"string","enum":["FREE","ONE_TIME","SUBSCRIPTION","USAGE_BASED"]},"DeploymentType":{"type":"string","enum":["MANAGED","SELF_HOSTED","MCP_REMOTE","AGNTCY_SLIM"]},"InstallStatus":{"type":"string","enum":["ACTIVE","PAUSED","UNINSTALLED"]},"RunStatus":{"type":"string","enum":["RUNNING","COMPLETED","FAILED","CANCELLED"]},"MessageRole":{"type":"string","enum":["USER","ASSISTANT","TOOL","SYSTEM"]},"ForkPolicy":{"type":"string","enum":["ALLOWED","PERSONAL_ONLY","NOT_ALLOWED"]},"LlmBillingMode":{"type":"string","enum":["PLATFORM_MANAGED","PUBLISHER_MANAGED","USER_BRINGS_KEY"]},"LicenceStatus":{"type":"string","enum":["ACTIVE","PAST_DUE","CANCELLED","EXPIRED"]},"PublisherTier":{"type":"string","enum":["FREE","PROFESSIONAL"]},"PublisherLevel":{"type":"string","enum":["NEW","ACTIVE","TRUSTED","PARTNER"]},"DataFlow":{"type":"string","enum":["SEQUENTIAL","PARALLEL","ORCHESTRATED"]},"AuthType":{"type":"string","enum":["OAUTH2","API_KEY","DIRECT_CONNECTION","NONE"]},"User":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"image":{"type":"string","nullable":true}}},"AgentCard":{"type":"object","description":"Compact agent representation for listings","properties":{"id":{"type":"string"},"slug":{"type":"string"},"bundleId":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"iconUrl":{"type":"string","nullable":true},"categoryName":{"type":"string"},"categorySlug":{"type":"string"},"categoryIcon":{"type":"string","nullable":true},"publisherName":{"type":"string"},"publisherAvatar":{"type":"string","nullable":true},"publisherVerified":{"type":"boolean"},"pricingModel":{"$ref":"#/components/schemas/PricingModel"},"price":{"type":"number","nullable":true},"avgRating":{"type":"number","format":"float"},"totalRatings":{"type":"integer"},"totalInstalls":{"type":"integer"},"tags":{"type":"array","items":{"type":"string"}},"integrations":{"type":"array","items":{"type":"string"}},"isFeatured":{"type":"boolean"},"isVerified":{"type":"boolean"}}},"AgentDetail":{"allOf":[{"$ref":"#/components/schemas/AgentCard"},{"type":"object","properties":{"description":{"type":"string"},"goal":{"type":"string"},"screenshotUrls":{"type":"array","items":{"type":"string"}},"autonomyLevel":{"type":"string"},"forkPolicy":{"$ref":"#/components/schemas/ForkPolicy"},"successRate":{"type":"number"},"estimatedCostMin":{"type":"number","nullable":true},"estimatedCostMax":{"type":"number","nullable":true},"llmBillingMode":{"$ref":"#/components/schemas/LlmBillingMode"},"publisherId":{"type":"string"},"publisherBio":{"type":"string","nullable":true},"publisherLevel":{"$ref":"#/components/schemas/PublisherLevel"},"createdAt":{"type":"string","format":"date-time"},"publishedAt":{"type":"string","format":"date-time","nullable":true},"latestVersion":{"$ref":"#/components/schemas/AgentVersion"},"versions":{"type":"array","items":{"type":"object","properties":{"version":{"type":"string"},"changelog":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}]},"AgentVersion":{"type":"object","properties":{"version":{"type":"string"},"changelog":{"type":"string","nullable":true},"skills":{"type":"array","items":{"type":"string"}},"integrations":{"type":"array","items":{"type":"string"}},"modelPreferences":{"type":"object","description":"JSON — e.g. { preferred_model: 'sonnet' }"},"memoryConfig":{"type":"object","description":"JSON — e.g. { sessionMemory: 'true' }"},"composition":{"type":"object","nullable":true},"configTemplate":{"type":"object","nullable":true,"description":"Publisher-defined user config fields"}}},"AgentInstallRecord":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string"},"agentSlug":{"type":"string"},"agentName":{"type":"string"},"agentTagline":{"type":"string"},"agentIconUrl":{"type":"string","nullable":true},"categoryName":{"type":"string"},"publisherName":{"type":"string"},"versionInstalled":{"type":"string"},"status":{"$ref":"#/components/schemas/InstallStatus"},"installedAt":{"type":"string","format":"date-time"},"hasBackground":{"type":"boolean"},"backgroundEnabled":{"type":"boolean"},"backgroundTriggerType":{"type":"string","nullable":true},"backgroundNextRunAt":{"type":"string","format":"date-time","nullable":true},"backgroundLastRunAt":{"type":"string","format":"date-time","nullable":true},"backgroundLastRunStatus":{"type":"string","nullable":true}}},"RunDetail":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/RunStatus"},"totalTokens":{"type":"integer"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentMessage"}},"install":{"type":"object","properties":{"agent":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"id":{"type":"string"}}}}}}},"RunSummary":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/RunStatus"},"messageCount":{"type":"integer"},"totalTokens":{"type":"integer"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}}},"AgentMessage":{"type":"object","properties":{"id":{"type":"string"},"role":{"$ref":"#/components/schemas/MessageRole"},"content":{"type":"string"},"toolName":{"type":"string","nullable":true},"toolInput":{"type":"object","nullable":true},"toolResult":{"type":"object","nullable":true},"tokens":{"type":"integer"},"feedback":{"type":"string","nullable":true,"enum":["positive","negative",null]},"createdAt":{"type":"string","format":"date-time"}}},"ChatMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}}},"IntegrationManifest":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"authType":{"$ref":"#/components/schemas/AuthType"},"requiredScopes":{"type":"array","items":{"type":"string"}},"setupSteps":{"type":"array","items":{"type":"string"}},"configFields":{"type":"object","nullable":true,"description":"JSON schema for integration config form fields"},"category":{"type":"string","nullable":true}}},"PublisherProfile":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"displayName":{"type":"string"},"bio":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"websiteUrl":{"type":"string","nullable":true},"githubUrl":{"type":"string","nullable":true},"level":{"$ref":"#/components/schemas/PublisherLevel"},"isVerified":{"type":"boolean"},"tier":{"$ref":"#/components/schemas/PublisherTier"},"stripeAccountId":{"type":"string","nullable":true},"stripeAccountStatus":{"type":"string","nullable":true}}},"BundleSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"dataFlow":{"$ref":"#/components/schemas/DataFlow"},"installMode":{"type":"string"},"pricingModel":{"$ref":"#/components/schemas/PricingModel"},"price":{"type":"number","nullable":true},"agentCount":{"type":"integer"},"combinedIntegrations":{"type":"array","items":{"type":"string"}},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string"},"orderIndex":{"type":"integer"}}}},"createdAt":{"type":"string","format":"date-time"}}},"BundleDetail":{"allOf":[{"$ref":"#/components/schemas/BundleSummary"},{"type":"object","properties":{"description":{"type":"string"},"goal":{"type":"string"},"estimatedCostMin":{"type":"number","nullable":true},"estimatedCostMax":{"type":"number","nullable":true},"publisherId":{"type":"string"}}}]},"OASFRecord":{"type":"object","description":"OASF v1.0.0 agent descriptor (AGNTCY standard)","properties":{"name":{"type":"string"},"version":{"type":"string"},"schema_version":{"type":"string","example":"1.0.0"},"description":{"type":"string"},"authors":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"domains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"modules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"data":{"type":"object"}}}},"annotations":{"type":"object","additionalProperties":{"type":"string"}}}},"BackgroundSchedule":{"type":"object","properties":{"id":{"type":"string"},"installId":{"type":"string"},"enabled":{"type":"boolean"},"triggerType":{"type":"string","enum":["cron","webhook","manual"]},"cronExpression":{"type":"string","nullable":true},"taskPrompt":{"type":"string"},"webhookSecret":{"type":"string","nullable":true},"nextRunAt":{"type":"string","format":"date-time","nullable":true},"lastRunAt":{"type":"string","format":"date-time","nullable":true},"lastRunStatus":{"type":"string","nullable":true},"maxConcurrentRuns":{"type":"integer"},"timeoutSeconds":{"type":"integer"}}},"Review":{"type":"object","properties":{"id":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string","nullable":true},"review":{"type":"string","nullable":true},"isVerifiedInstall":{"type":"boolean"},"userName":{"type":"string"},"userImage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"UserProviderKey":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["anthropic","openai","huggingface","google","mistral"]},"label":{"type":"string","nullable":true},"maskedKey":{"type":"string","description":"e.g. sk-ant-...x7JF"},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"Category":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"iconName":{"type":"string","nullable":true},"agentCount":{"type":"integer"}}},"SSEEvent":{"type":"object","description":"Server-Sent Event payload (one of the types below)","oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"content":{"type":"string"}}},{"type":"object","properties":{"type":{"type":"string","enum":["tool_start"]},"tool":{"type":"string"},"input":{"type":"object"},"toolCallId":{"type":"string"}}},{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"]},"tool":{"type":"string"},"result":{"type":"string"},"toolCallId":{"type":"string"}}},{"type":"object","properties":{"type":{"type":"string","enum":["message_id"]},"messageId":{"type":"string"}}},{"type":"object","properties":{"type":{"type":"string","enum":["sandbox_info"]},"remaining":{"type":"integer"}}},{"type":"object","properties":{"type":{"type":"string","enum":["error"]},"message":{"type":"string"}}},{"type":"object","properties":{"type":{"type":"string","enum":["done"]}}}]},"AgentCapability":{"type":"object","description":"Machine-readable capability descriptor for agent discovery","properties":{"agentId":{"type":"string"},"slug":{"type":"string"},"bundleId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"OASF taxonomy skill ID"},"name":{"type":"string"}}}},"domains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"integrations":{"type":"array","items":{"type":"string"}},"successRate":{"type":"number","description":"0.0-1.0, % of runs completed successfully"},"avgResponseTimeMs":{"type":"integer","nullable":true},"avgTokenCost":{"type":"number","nullable":true},"totalExecutions":{"type":"integer"},"reputationScore":{"type":"number","description":"Composite 0.0-1.0 score"},"estimatedCostMin":{"type":"number","nullable":true},"estimatedCostMax":{"type":"number","nullable":true},"latencySlaMs":{"type":"integer","nullable":true},"pricingModel":{"$ref":"#/components/schemas/PricingModel"},"supportedProtocols":{"type":"array","items":{"type":"string","enum":["sse","mcp","slim"]}},"deploymentType":{"$ref":"#/components/schemas/DeploymentType"},"publisherName":{"type":"string"},"publisherVerified":{"type":"boolean"},"avgRating":{"type":"number"},"totalInstalls":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}},"PaginatedResponse":{"type":"object","properties":{"items":{"type":"array","items":{}},"total":{"type":"integer"},"page":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"paths":{"/health":{"get":{"summary":"Health check","tags":["Discovery"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"core-api"}}}}}}}}},"/v1/auth/session":{"get":{"summary":"Get current session","description":"Returns the authenticated user from JWT cookie, or null if not signed in.","tags":["Auth"],"responses":{"200":{"description":"Session info","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"oneOf":[{"$ref":"#/components/schemas/User"},{"type":"null"}]}}}}}}}}},"/v1/auth/oauth/google":{"get":{"summary":"Initiate Google OAuth","description":"Redirects to Google OAuth consent screen. Sets JWT cookie on callback.","tags":["Auth"],"parameters":[{"name":"callbackUrl","in":"query","schema":{"type":"string"},"description":"URL to redirect after sign-in"},{"name":"agentId","in":"query","schema":{"type":"string"},"description":"If provided, auto-creates AgentInstall on callback"}],"responses":{"302":{"description":"Redirects to Google OAuth"}}}},"/v1/auth/oauth/google/callback":{"get":{"summary":"Google OAuth callback","tags":["Auth"],"parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string","description":"Base64url encoded JSON with callbackUrl and agentId"}}],"responses":{"302":{"description":"Sets JWT cookie and redirects to callbackUrl"}}}},"/v1/auth/oauth/github":{"get":{"summary":"Initiate GitHub OAuth","tags":["Auth"],"parameters":[{"name":"callbackUrl","in":"query","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirects to GitHub OAuth"}}}},"/v1/auth/oauth/github/callback":{"get":{"summary":"GitHub OAuth callback","tags":["Auth"],"parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Sets JWT cookie and redirects to callbackUrl"}}}},"/v1/auth/signout":{"post":{"summary":"Sign out","description":"Clears the JWT cookie.","tags":["Auth"],"responses":{"200":{"description":"Signed out","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}}}}},"/v1/agents":{"get":{"summary":"List agents","description":"Browse agents with filtering, sorting, and pagination.","tags":["Agents"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":12}},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug"},{"name":"minRating","in":"query","schema":{"type":"number"}},{"name":"pricingModel","in":"query","schema":{"$ref":"#/components/schemas/PricingModel"}},{"name":"verifiedOnly","in":"query","schema":{"type":"boolean"}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Full-text search on name + description"},{"name":"sort","in":"query","schema":{"type":"string","enum":["popular","rating","newest","name"]}},{"name":"integrations","in":"query","schema":{"type":"string"},"description":"Comma-separated integration slugs (e.g. slack,github)"}],"responses":{"200":{"description":"Paginated agent list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentCard"}},"total":{"type":"integer"},"page":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}}}},"/v1/agents/featured":{"get":{"summary":"Get featured agents","tags":["Agents"],"responses":{"200":{"description":"Featured agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentCard"}}}}}}}}}},"/v1/agents/trending":{"get":{"summary":"Get trending agents","tags":["Agents"],"responses":{"200":{"description":"Trending agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentCard"}}}}}}}}}},"/v1/agents/by-slug/{slug}":{"get":{"summary":"Get agent detail","description":"Returns full agent detail including description, versions, publisher info.\n**Important:** Use `/by-slug/:slug` not `/:slug`.\n","tags":["Agents"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentDetail"}}}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/search":{"get":{"summary":"Search agents (for dependency picker)","tags":["Agents"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Matching agents","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"bundleId":{"type":"string"},"publisher":{"type":"object","properties":{"handle":{"type":"string"},"displayName":{"type":"string"}}}}}}}}}}}}}},"/v1/agents/{slug}/oasf":{"get":{"summary":"Export agent as OASF Record","description":"Returns the agent in OASF v1.0.0 format for AGNTCY directory interop.","tags":["Agents","Directory"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OASF Record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OASFRecord"}}}},"404":{"description":"Agent not found"}}}},"/v1/agents/import/oasf":{"post":{"summary":"Import/preview OASF Record","description":"Parses an OASF Record and returns a preview of the agent that would be created.","tags":["Agents","Directory"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","version","schema_version","description"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"schema_version":{"type":"string"},"description":{"type":"string"},"skills":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"name":{"type":"string"}}}]}},"modules":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"name":{"type":"string"}}}]}},"authors":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"name":{"type":"string"}}}]}}}}}}},"responses":{"200":{"description":"Import preview","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","example":"preview"},"import":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"schemaVersion":{"type":"string"},"authors":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"string"}},"integrations":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"/v1/agents/{agentId}/chat":{"post":{"summary":"Chat with agent (SSE streaming)","description":"Sends a message and streams the response via Server-Sent Events.\nThe agent has access to configured integrations and tools.\n\n**SSE Event Types:**\n- `text` — Streamed text content\n- `tool_start` — Agent is calling a tool\n- `tool_result` — Tool execution result\n- `message_id` — DB message ID (for feedback submission)\n- `error` — Error occurred\n- `done` — Stream complete\n","tags":["Agents"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"User message to send"},"runId":{"type":"string","description":"Existing run ID to continue conversation"},"history":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"},"description":"Previous messages for context"}}}}}},"responses":{"200":{"description":"SSE stream","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/SSEEvent"}}}},"401":{"description":"Not authenticated"},"404":{"description":"Agent not found or not installed"}}}},"/v1/agents/{agentId}/execute":{"post":{"summary":"Execute agent (non-streaming)","description":"Runs agent without streaming. Used by webhooks, cron, and background tasks.\nReturns the complete result in one response.\n","tags":["Agents"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"triggerType":{"type":"string","enum":["chat","webhook","schedule","manual"]},"installId":{"type":"string"},"runId":{"type":"string"},"history":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}}}}},"responses":{"200":{"description":"Execution result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"response":{"type":"string"},"tokensUsed":{"type":"integer"},"error":{"type":"string","nullable":true}}}}}}}}},"/v1/agents/{agentId}/try":{"post":{"summary":"Try agent in sandbox (SSE streaming)","description":"Free sandbox mode — 5 messages per user per agent.\nNo integrations or tools available. Agent demonstrates capabilities.\nRequires sign-in (no guest mode).\n\nReturns same SSE events as `/chat` plus `sandbox_info` with remaining messages.\n","tags":["Agents"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"history":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}}}}},"responses":{"200":{"description":"SSE stream with sandbox_info events","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/SSEEvent"}}}},"403":{"description":"Sandbox limit reached (5 messages)"}}}},"/v1/installs":{"get":{"summary":"List installed agents","tags":["Installs"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"User's active installs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentInstallRecord"}}}}}}}}},"post":{"summary":"Install an agent","tags":["Installs"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentId"],"properties":{"agentId":{"type":"string"}}}}}},"responses":{"200":{"description":"Install created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentInstallRecord"}}}}}}}}},"/v1/installs/agent/{agentId}":{"get":{"summary":"Get install record for agent","tags":["Installs"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Install record or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/AgentInstallRecord"},{"type":"null"}]}}}}}}}}},"/v1/installs/status/{agentId}":{"get":{"summary":"Check install status","tags":["Installs"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Install status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","nullable":true}}}}}}}}}}},"/v1/installs/{agentId}":{"patch":{"summary":"Update install (pause/resume)","tags":["Installs"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ACTIVE","PAUSED"]}}}}}},"responses":{"200":{"description":"Updated install"}}},"delete":{"summary":"Uninstall agent","tags":["Installs"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Uninstalled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/v1/runs":{"get":{"summary":"List recent runs","tags":["Runs"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"installId","in":"query","schema":{"type":"string"},"description":"Filter by install ID"}],"responses":{"200":{"description":"Run list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunSummary"}}}}}}}}},"post":{"summary":"Create a new run","tags":["Runs"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["installId"],"properties":{"installId":{"type":"string"}}}}}},"responses":{"200":{"description":"Run created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string"}}}}}}}}}}},"/v1/runs/{id}":{"get":{"summary":"Get run detail with messages","tags":["Runs"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Run with messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunDetail"}}}}}}}}},"/v1/runs/install/{agentId}":{"get":{"summary":"Get install for agent (with agent details)","tags":["Runs"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Install record with agent info"}}}},"/v1/integrations":{"get":{"summary":"List all integrations","description":"Returns all 15 integration manifests with their config field schemas.","tags":["Integrations"],"responses":{"200":{"description":"Integration list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationManifest"}}}}}}}}}},"/v1/integrations/agent/{agentId}":{"get":{"summary":"Get integrations required by agent","tags":["Integrations"],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Required integrations with configFields"}}}},"/v1/integrations/config/{agentId}":{"get":{"summary":"Get saved integration config","tags":["Integrations"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Config values or null"}}},"post":{"summary":"Save integration credentials","description":"Saves integration credentials (API keys, tokens) for an installed agent.\nCredentials are stored in AgentInstall.configValues.\n","tags":["Integrations"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["configValues"],"properties":{"configValues":{"type":"object","description":"Key-value pairs matching the integration's configFields schema","example":{"slack_bot_token":"xoxb-...","slack_channel":"#general"}}}}}}},"responses":{"200":{"description":"Config saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/v1/integrations/user-config/{agentId}":{"get":{"summary":"Get user-specific config","tags":["Integrations"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"User config or null"}}},"post":{"summary":"Save user-specific config","tags":["Integrations"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userConfig"],"properties":{"userConfig":{"type":"object"}}}}}},"responses":{"200":{"description":"Saved"}}}},"/v1/integrations/validate":{"post":{"summary":"Test integration credentials","description":"Validates credentials by making a test API call to the integration.","tags":["Integrations"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["integrationSlug","configValues"],"properties":{"integrationSlug":{"type":"string","description":"e.g. \"slack\", \"github\", \"notion\""},"configValues":{"type":"object","description":"Credentials to test"}}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"error":{"type":"string"}}}}}}}}},"/v1/publishers/me":{"get":{"summary":"Get my publisher profile","tags":["Publishers"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Publisher profile or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/PublisherProfile"},{"type":"null"}]}}}}}}}},"post":{"summary":"Become a publisher","tags":["Publishers"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["displayName"],"properties":{"displayName":{"type":"string","minLength":2}}}}}},"responses":{"200":{"description":"Publisher created (handle auto-generated)"}}},"patch":{"summary":"Update publisher profile","tags":["Publishers"],"security":[{"cookieAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string"},"bio":{"type":"string"},"websiteUrl":{"type":"string"},"githubUrl":{"type":"string"},"llmApiKey":{"type":"string","description":"Publisher's LLM API key (encrypted at rest)"}}}}}},"responses":{"200":{"description":"Updated profile"}}}},"/v1/publishers/me/agents":{"get":{"summary":"List my agents","tags":["Publishers"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Publisher's agents"}}}},"/v1/publishers/me/stats":{"get":{"summary":"Get publisher stats","tags":["Publishers"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Stats","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalAgents":{"type":"integer"},"totalInstalls":{"type":"integer"},"avgRating":{"type":"number"},"totalRatings":{"type":"integer"},"level":{"type":"string"},"isVerified":{"type":"boolean"}}}}}}}}}}},"/v1/publishers/me/earnings":{"get":{"summary":"Get publisher earnings","tags":["Publishers"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Earnings breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"lifetimeRevenue":{"type":"number"},"trailingMonthRevenue":{"type":"number"},"pendingBalanceCents":{"type":"number"},"commissionRate":{"type":"number","description":"0.15 (15%) or 0.10 (10% for VIP)"},"tier":{"type":"string"},"stripeAccountStatus":{"type":"string"}}}}}}}}}}},"/v1/publishers/agents":{"post":{"summary":"Create a new agent","description":"Creates a new agent with all configuration. The agent starts in DRAFT status.\nSubmit for review with `/submit` endpoint after creation.\n","tags":["Publishers"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug","tagline","categoryId","description","goal"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier (unique per store)"},"tagline":{"type":"string","maxLength":120},"categoryId":{"type":"string"},"description":{"type":"string"},"goal":{"type":"string"},"tags":{"oneOf":[{"type":"string","description":"Comma-separated"},{"type":"array","items":{"type":"string"}}]},"pricingModel":{"$ref":"#/components/schemas/PricingModel"},"price":{"type":"number"},"autonomyLevel":{"type":"string","default":"L2_supervised"},"forkPolicy":{"$ref":"#/components/schemas/ForkPolicy"},"version":{"type":"string","default":"1.0.0"},"changelog":{"type":"string"},"integrations":{"type":"array","items":{"type":"string"},"description":"Integration slugs (e.g. [\"slack\", \"github\"])"},"skills":{"type":"array","items":{"type":"string"}},"customInstructions":{"type":"string","description":"System prompt / custom instructions"},"personality":{"type":"string"},"saveDraft":{"type":"boolean"},"deploymentType":{"$ref":"#/components/schemas/DeploymentType"},"endpointUrl":{"type":"string","description":"Required for SELF_HOSTED / MCP_REMOTE"},"endpointAuthType":{"type":"string"},"preferredModel":{"type":"string","description":"Model alias: sonnet, haiku, opus, deepseek, gpt-4o, etc."},"dependencies":{"type":"array","items":{"type":"string"},"description":"Bundle IDs of dependent agents"},"backgroundEnabled":{"type":"boolean"},"backgroundTriggerType":{"type":"string","enum":["cron","webhook","manual"]},"backgroundCron":{"type":"string","description":"Cron expression (e.g. \"0 9 * * 1-5\")"},"backgroundTaskPrompt":{"type":"string"},"backgroundTimeout":{"type":"integer"},"configFields":{"type":"array","items":{"type":"object"},"description":"User-configurable fields schema"}}}}}},"responses":{"200":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"slug":{"type":"string"}}}}}}}}},"/v1/publishers/agents/{agentId}":{"get":{"summary":"Get agent for editing","tags":["Publishers"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full agent with versions and dependencies"}}},"put":{"summary":"Update an agent","description":"Same fields as create. Updates the latest version.","tags":["Publishers"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Same fields as POST /publishers/agents"}}}},"responses":{"200":{"description":"Agent updated"}}}},"/v1/publishers/agents/{agentId}/submit":{"post":{"summary":"Submit agent for review","description":"Changes status from DRAFT to SUBMITTED.","tags":["Publishers"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submitted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/v1/publishers/agents/{agentId}/endpoint-secret":{"post":{"summary":"Generate HMAC signing secret","description":"Creates a new HMAC-SHA256 secret for external agent endpoints.","tags":["Publishers"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Secret generated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"secret":{"type":"string","description":"32-byte hex string (show once, then hashed)"},"algorithm":{"type":"string","example":"hmac_sha256"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Revoke signing secret","tags":["Publishers"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Secret revoked"}}}},"/v1/publishers/generate-agent":{"post":{"summary":"AI-powered agent generation","description":"Describe what you want in 2-3 sentences. AI generates full agent spec:\nname, slug, tagline, description, goal, tags, integrations, skills,\nsystem prompt, config fields, autonomy level, pricing, background config.\n","tags":["Publishers"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":10,"description":"Natural language description of the agent","example":"I want an agent that monitors my Gmail for invoices, extracts the amounts, and logs them in a Google Sheet"}}}}}},"responses":{"200":{"description":"Generated agent specification (JSON matching create agent schema)"}}}},"/v1/publishers/agent-chat":{"post":{"summary":"Conversational agent creation via SSE","description":"Multi-turn conversational endpoint for creating agents. Send the full\nmessage history each call. The LLM streams back text tokens as SSE\nevents. When enough context has been gathered (typically 3-5 turns),\nthe response includes an `agent_spec` SSE event with the validated\nJSON specification.\n\nSSE event types:\n- `text`        — streaming token: `{ type: \"text\", content: \"...\" }`\n- `agent_spec`  — validated spec: `{ type: \"agent_spec\", agentSpec: {...}, isComplete: true }`\n- `error`       — error: `{ type: \"error\", error: \"...\" }`\n- `done`        — stream finished: `{ type: \"done\" }`\n","tags":["Publishers"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}}},"description":"Full conversation history (user and assistant turns)","example":[{"role":"user","content":"I want an agent that monitors Slack for customer complaints"}]}}}}}},"responses":{"200":{"description":"SSE stream of text tokens and optional agent_spec","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Missing or invalid messages array"},"403":{"description":"Not a publisher"}}}},"/v1/publishers/agents/import":{"post":{"summary":"Import external agent","tags":["Publishers"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Agent imported"}}}},"/v1/publishers/validate-endpoint":{"post":{"summary":"Validate external endpoint URL","tags":["Publishers"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"authType":{"type":"string"}}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"isValid":{"type":"boolean"},"error":{"type":"string"}}}}}}}}},"/v1/publishers/{id}":{"get":{"summary":"Public publisher profile","tags":["Publishers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Publisher profile"}}}},"/v1/bundles":{"get":{"summary":"List solution bundles","tags":["Bundles"],"responses":{"200":{"description":"Bundle list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BundleSummary"}}}}}}}}},"post":{"summary":"Create a bundle","tags":["Bundles"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","tagline","description","goal","agents"],"properties":{"name":{"type":"string"},"tagline":{"type":"string"},"description":{"type":"string"},"goal":{"type":"string"},"dataFlow":{"$ref":"#/components/schemas/DataFlow"},"installMode":{"type":"string","enum":["ALL_OR_NOTHING","MODULAR"]},"agents":{"type":"array","minItems":2,"items":{"type":"object","required":["agentId","role"],"properties":{"agentId":{"type":"string"},"role":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Bundle created"}}}},"/v1/bundles/by-slug/{slug}":{"get":{"summary":"Get bundle detail","tags":["Bundles"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Bundle detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BundleDetail"}}}}}}}}},"/v1/bundles/{bundleId}/install":{"post":{"summary":"Install all agents in bundle","tags":["Bundles"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"bundleId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Install results per agent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"agentName":{"type":"string"},"installed":{"type":"boolean"}}}}}}}}}}}},"/v1/bundles/{bundleId}/execute":{"post":{"summary":"Execute bundle pipeline","description":"Runs agents sequentially, passing each output as context to the next.","tags":["Bundles"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"bundleId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["initialMessage"],"properties":{"initialMessage":{"type":"string"}}}}}},"responses":{"200":{"description":"Pipeline result"}}}},"/v1/background/{installId}":{"get":{"summary":"Get background schedule","tags":["Background"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"installId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Schedule","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BackgroundSchedule"}}}}}}}},"put":{"summary":"Create or update background schedule","tags":["Background"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"installId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"triggerType":{"type":"string","enum":["cron","webhook","manual"]},"cronExpression":{"type":"string","description":"e.g. '0 9 * * 1-5' (weekdays at 9am)"},"taskPrompt":{"type":"string","description":"The prompt executed each run. Supports {{configField}} substitution."},"timeoutSeconds":{"type":"integer","default":300},"maxConcurrentRuns":{"type":"integer","default":1}}}}}},"responses":{"200":{"description":"Schedule saved"}}}},"/v1/background/{installId}/toggle":{"patch":{"summary":"Enable/disable schedule","tags":["Background"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"installId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Toggled"}}}},"/v1/background/{installId}/runs":{"get":{"summary":"Get background run history","tags":["Background"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"installId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Run history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"triggerType":{"type":"string"},"taskPrompt":{"type":"string"},"status":{"$ref":"#/components/schemas/RunStatus"},"totalTokens":{"type":"integer"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}}},"/v1/background/{installId}/run":{"post":{"summary":"Manually trigger background run","tags":["Background"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"installId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Run triggered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"},"error":{"type":"string","nullable":true}}}}}}}}}}},"/v1/reviews/{agentId}":{"get":{"summary":"Get reviews for agent","tags":["Reviews"],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Review list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Review"}}}}}}}}}},"/v1/reviews":{"post":{"summary":"Submit or update review","description":"One review per user per agent. Submitting again updates the existing review.","tags":["Reviews"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentId","rating"],"properties":{"agentId":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string"},"review":{"type":"string"}}}}}},"responses":{"200":{"description":"Review saved"}}}},"/v1/messages/{messageId}/feedback":{"post":{"summary":"Submit message feedback","description":"Thumbs up/down on assistant messages. Negative feedback auto-saved to agent memory for self-improvement.","tags":["Messages"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["feedback"],"properties":{"feedback":{"type":"string","enum":["positive","negative"],"nullable":true,"description":"null to remove feedback"}}}}}},"responses":{"200":{"description":"Feedback saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"feedback":{"type":"string","nullable":true}}}}}}}}},"/v1/recommendations":{"get":{"summary":"Personalized recommendations","description":"Returns agents based on user's installed categories, integrations, and popularity.","tags":["Recommendations"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":6}}],"responses":{"200":{"description":"Recommended agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentCard"}}}}}}}}}},"/v1/recommendations/similar/{agentId}":{"get":{"summary":"Similar agents (collaborative filtering)","description":"Users who installed X also installed Y","tags":["Recommendations"],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":4}}],"responses":{"200":{"description":"Similar agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentCard"}}}}}}}}}},"/v1/categories":{"get":{"summary":"List all categories","tags":["Categories"],"responses":{"200":{"description":"Category list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}}}},"/v1/stripe/connect/onboard":{"post":{"summary":"Start Stripe Connect onboarding","description":"Creates a Stripe Express account and returns the onboarding URL.","tags":["Stripe"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Onboarding URL","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}}}}}}},"/v1/stripe/connect/callback":{"get":{"summary":"Stripe Connect callback","description":"Verifies Stripe account status after onboarding.","tags":["Stripe"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Account status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["active","pending"]}}}}}}}}}}},"/v1/stripe/checkout":{"post":{"summary":"Create checkout session","description":"Creates a Stripe Checkout session for a paid agent (subscription or one-time).","tags":["Stripe"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentId"],"properties":{"agentId":{"type":"string"}}}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"checkoutUrl":{"type":"string","format":"uri"}}}}}}}}}}},"/v1/stripe/webhooks":{"post":{"summary":"Stripe webhook handler","description":"Receives Stripe lifecycle events. Raw body with signature verification.\nHandles: checkout.session.completed, invoice.payment_succeeded,\ninvoice.payment_failed, customer.subscription.deleted\n","tags":["Stripe"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Event received","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"}}}}}}}}},"/v1/user/keys":{"get":{"summary":"List saved LLM provider keys","description":"Returns keys with masked values (e.g. \"sk-ant-...x7JF\")","tags":["User Keys"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Key list","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/UserProviderKey"}}}}}}}}},"post":{"summary":"Save a new provider key","description":"Key is encrypted with AES-256-GCM before storage.","tags":["User Keys"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","apiKey"],"properties":{"provider":{"type":"string","enum":["anthropic","openai","huggingface","google","mistral"]},"apiKey":{"type":"string","description":"Raw API key (encrypted before storage)"},"label":{"type":"string","description":"User-friendly label"}}}}}},"responses":{"200":{"description":"Key saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProviderKey"}}}}}}},"/v1/user/keys/{id}":{"delete":{"summary":"Delete a saved key","tags":["User Keys"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key deleted"}}}},"/v1/user/keys/{id}/test":{"post":{"summary":"Test a saved key","description":"Makes a tiny LLM call to verify the key works.","tags":["User Keys"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"response":{"type":"string"},"error":{"type":"string"}}}}}}}}},"/v1/admin/agents":{"get":{"summary":"List agents for review","tags":["Admin"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"All agents with full details"}}}},"/v1/admin/agents/{id}/status":{"patch":{"summary":"Approve, publish, or reject agent","tags":["Admin"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["approve","publish","reject"]}}}}}},"responses":{"200":{"description":"Status updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"action":{"type":"string"}}}}}}}}},"/v1/directory":{"get":{"summary":"AGNTCY-compatible directory listing","description":"Public OASF directory API. Returns agents as OASF Records for\ninteroperability with the AGNTCY ecosystem.\n","tags":["Directory"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by name or description"},{"name":"domain","in":"query","schema":{"type":"string"},"description":"Filter by domain/category"},{"name":"skill","in":"query","schema":{"type":"string"},"description":"Filter by skill name"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Paginated OASF records","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OASFRecord"}}}}}}}}}},"/v1/directory/{slug}":{"get":{"summary":"Single agent OASF descriptor","tags":["Directory"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OASF Record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OASFRecord"}}}},"404":{"description":"Agent not found"}}}},"/.well-known/agntcy.json":{"get":{"summary":"AGNTCY instance discovery","description":"Returns metadata about this AgentStudio instance for AGNTCY network discovery.\nOther AGNTCY-compatible services use this to find our directory endpoint.\n","tags":["Discovery"],"responses":{"200":{"description":"Discovery document","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"AgentStudio by LiminaHub"},"type":{"type":"string","example":"marketplace"},"version":{"type":"string","example":"1.0.0"},"directory_endpoint":{"type":"string","example":"/v1/directory"},"oasf_schema_version":{"type":"string","example":"1.0.0"},"supported_protocols":{"type":"array","items":{"type":"string"},"example":["oasf","http","sse","slim","mcp"]},"mcp_endpoint":{"type":"string","example":"/mcp"},"agent_count":{"type":"integer"}}}}}}}}},"/mcp":{"post":{"summary":"MCP JSON-RPC endpoint","description":"StreamableHTTP transport for the Model Context Protocol.\nSend JSON-RPC requests (initialize, tools/list, tools/call, etc.).\nFirst request must be an `initialize` call; the response sets the\n`Mcp-Session-Id` header for subsequent requests.\n","tags":["MCP"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Mcp-Session-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Session ID returned from initialize (required after first request)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"method":{"type":"string","example":"initialize"},"params":{"type":"object"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]}},"required":["jsonrpc","method","id"]}}}},"responses":{"200":{"description":"JSON-RPC response","headers":{"Mcp-Session-Id":{"schema":{"type":"string"},"description":"Session ID (set on initialize)"}},"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"object"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]}}}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Session not found"}}},"get":{"summary":"MCP SSE stream","description":"Server-Sent Events stream for server-initiated MCP messages.\nRequires an active session via `Mcp-Session-Id` header.\n","tags":["MCP"],"parameters":[{"name":"Mcp-Session-Id","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SSE event stream","content":{"text/event-stream":{}}},"404":{"description":"Session not found"}}},"delete":{"summary":"Terminate MCP session","description":"Clean up server resources for an MCP session.","tags":["MCP"],"parameters":[{"name":"Mcp-Session-Id","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session terminated"},"404":{"description":"Session not found"}}}},"/v1/webhooks/{installId}":{"post":{"summary":"External webhook trigger","description":"Triggers a background agent run from an external system.\nValidates webhook secret from header or query param.\n","tags":["Webhooks"],"security":[{"webhookSecret":[]}],"parameters":[{"name":"installId","in":"path","required":true,"schema":{"type":"string"}},{"name":"secret","in":"query","schema":{"type":"string"},"description":"Alternative to x-webhook-secret header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"taskPrompt":{"type":"string","description":"Override the scheduled task prompt"},"payload":{"type":"object","description":"Webhook payload appended to task prompt as context"}}}}}},"responses":{"200":{"description":"Run result","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"},"tokensUsed":{"type":"integer"},"response":{"type":"string","description":"First 5000 chars of response"},"error":{"type":"string","nullable":true}}}}}},"401":{"description":"Invalid webhook secret"},"429":{"description":"Max concurrent runs reached"}}}},"/v1/discovery/search":{"get":{"summary":"Structured capability search","description":"Find agents by capability, domain, cost, latency, reputation, protocol, and more.\nReturns structured capability descriptors with OASF-mapped skills and domains.\nDesigned for orchestrators, CI/CD pipelines, and external systems to programmatically discover agents.\n","tags":["Discovery"],"parameters":[{"name":"skill","in":"query","schema":{"type":"string"},"description":"OASF skill name or ID (e.g. \"summarization\", \"workflow_automation\")"},{"name":"domain","in":"query","schema":{"type":"string"},"description":"Domain/category filter (e.g. \"finance\", \"marketing\")"},{"name":"integration","in":"query","schema":{"type":"string"},"description":"Required integration (e.g. \"slack\", \"github\")"},{"name":"maxCost","in":"query","schema":{"type":"number"},"description":"Max estimated cost per execution"},{"name":"maxLatency","in":"query","schema":{"type":"integer"},"description":"Max response time in ms"},{"name":"minReputation","in":"query","schema":{"type":"number"},"description":"Minimum reputation score (0.0-1.0)"},{"name":"minRating","in":"query","schema":{"type":"number"},"description":"Minimum average rating"},{"name":"pricingModel","in":"query","schema":{"$ref":"#/components/schemas/PricingModel"}},{"name":"protocol","in":"query","schema":{"type":"string","enum":["sse","mcp","slim"]},"description":"Required protocol support"},{"name":"deploymentType","in":"query","schema":{"$ref":"#/components/schemas/DeploymentType"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Text search on name + description + tagline"},{"name":"sort","in":"query","schema":{"type":"string","enum":["popular","rating","reputation","newest","cost"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Matching agents with capability descriptors","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentCapability"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"filters":{"type":"object"}}}}}}}}}},"post":{"summary":"Semantic natural language search","description":"Search for agents using natural language. The system extracts skills and domains\nfrom the query, scores agents by relevance, and returns ranked results.\nExample: \"I need an agent that can analyze quarterly earnings reports\"\n","tags":["Discovery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Natural language capability search","example":"I need an agent to process invoices from email with OCR"},"limit":{"type":"integer","default":10,"maximum":50}}}}}},"responses":{"200":{"description":"Ranked agent matches","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"matchedSkills":{"type":"array","items":{"type":"string"}},"matchedDomains":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AgentCapability"},{"type":"object","properties":{"relevanceScore":{"type":"number"}}}]}},"total":{"type":"integer"}}}}}}}}}}},"/v1/discovery/skills":{"get":{"summary":"List OASF skill taxonomy","description":"Returns all 121 OASF skills with IDs, names, and captions.","tags":["Discovery"],"responses":{"200":{"description":"Skill taxonomy","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"caption":{"type":"string"}}}}}}}}}}}}}},"/v1/discovery/domains":{"get":{"summary":"List OASF domain taxonomy","description":"Returns all 15 OASF domains with IDs, names, and captions.","tags":["Discovery"],"responses":{"200":{"description":"Domain taxonomy"}}}},"/v1/discovery/{slug}/capabilities":{"get":{"summary":"Full capability descriptor for an agent","description":"Returns a machine-readable capability descriptor with OASF-mapped skills,\ndomains, performance metrics, cost/SLA, and protocol support.\n","tags":["Discovery"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent capability descriptor","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentCapability"}}}}}},"404":{"description":"Agent not found"}}}},"/v1/reputation/{agentId}":{"get":{"summary":"Full reputation breakdown","description":"Returns detailed performance metrics and reputation score for an agent.","tags":["Reputation"],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reputation metrics"}}}},"/v1/reputation/{agentId}/badges":{"get":{"summary":"Agent reputation badges","description":"Returns earned badges based on performance thresholds.\nBadges: fast_responder, high_accuracy, cost_efficient, top_rated, trending.\n","tags":["Reputation"],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Badge list"}}}},"/v1/store/trending":{"get":{"summary":"Reputation-weighted trending agents","description":"Returns trending agents scored by reputation (40%), recent installs (30%),\nexecutions (20%), and rating (10%). Better than install-count-only trending.\n","tags":["Reputation"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"Trending agents"}}}},"/v1/reputation/refresh":{"post":{"summary":"Recompute all agent reputations","description":"Admin endpoint to batch-update reputation scores for all published agents.","tags":["Reputation"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Reputations refreshed"}}}},"/v1/cron/agent-scheduler":{"post":{"summary":"Process due background schedules","description":"Internal endpoint called by cron job. Processes all schedules\nwhere nextRunAt <= now and enabled = true.\n","tags":["Cron"],"security":[{"cronSecret":[]}],"responses":{"200":{"description":"Schedules processed"}}}}}}