openapi: 3.2.0 info: title: AgentsPodium account API (agent-facing subset) Catalog API version: 1.0.0 description: 'Create, configure, pay for and watch AI agent pods, meant to be driven directly by an agent. This document covers the subset an agent (rather than a human operator) needs: auth, agent lifecycle, tools/models/personas catalog, payment, A2A directory. See https://hosting.defispace.com/docs/quickstart.md for a narrative walkthrough.' servers: - url: https://agentspodium.com/api security: - bearerAuth: [] tags: - name: Catalog description: 'Read-only reference data: personas, tiers, engines, tools, models, providers.' paths: /personas: get: summary: List the public persona catalog tags: - Catalog description: Call before creating an agent to choose a `personaId` — built-in personas plus any published community ones. No auth required; browse freely. responses: '200': description: OK. content: application/json: schema: type: object required: - personas properties: personas: type: array items: $ref: '#/components/schemas/Persona' security: [] operationId: getPersonas x-operation-id-source: derived /personas/{id}: get: summary: Read one persona's full catalog entry tags: - Catalog description: Call to inspect a persona's soul, localizations and example demo before deploying it, or to render its detail page. No auth required. parameters: - name: id in: path required: true schema: type: string description: Persona id, e.g. personal-assistant. responses: '200': description: OK. content: application/json: schema: type: object required: - persona - articles properties: persona: $ref: '#/components/schemas/Persona' articles: type: array description: Articles written about this persona (bodies omitted). items: type: object '404': description: No such persona. content: application/json: schema: type: object required: - error properties: error: type: string security: [] operationId: getPersonasById x-operation-id-source: derived /tiers: get: summary: List the pricing plans and the trial length tags: - Catalog description: Call to show or validate plan choices before POST /agents — this is the one source of truth for prices and specs, do not hard-code them. No auth required. responses: '200': description: OK. content: application/json: schema: type: object required: - tiers - trial properties: tiers: type: array items: $ref: '#/components/schemas/Tier' trial: type: object required: - days - graceDays properties: days: type: integer example: 7 graceDays: type: integer example: 3 security: [] operationId: getTiers x-operation-id-source: derived /engines: get: summary: List the platforms (engines) that can be deployed tags: - Catalog description: Call before POST /agents to pick a valid `engine` and confirm the tier you want meets its `minTier`. No auth required. responses: '200': description: OK. content: application/json: schema: type: object required: - engines - podHostSuffix properties: engines: type: array items: $ref: '#/components/schemas/Engine' podHostSuffix: type: - string - 'null' description: Host suffix agent dashboards are proxied from; null when that proxy is off. security: [] operationId: getEngines x-operation-id-source: derived /tools: get: summary: List Hermes toolsets available to enable on an agent tags: - Catalog description: Call to build the `tools.enabled` list for POST /agents or PATCH /agents/{id}/tools. responses: '200': description: OK. content: application/json: schema: type: object required: - platform - toolsets - groups - minimalToolsets properties: platform: type: string enum: - hermes toolsets: type: array items: $ref: '#/components/schemas/ToolsetInfo' groups: type: array items: type: object required: - id - label properties: id: type: string label: type: string minimalToolsets: type: array items: type: string description: Ids enabled by default when a persona is deployed with nothing chosen. security: [] operationId: getTools x-operation-id-source: derived /models: get: summary: List the curated LLM model catalog tags: - Catalog description: Call to pick a valid `model` id for PATCH /agents/{id}/llm-key or POST /agents. responses: '200': description: OK. content: application/json: schema: type: object required: - models - default properties: models: type: array items: $ref: '#/components/schemas/ModelInfo' default: type: string security: [] operationId: getModels x-operation-id-source: derived /llm-providers: get: summary: List LLM providers Hermes can take a key for tags: - Catalog description: Call to validate the `provider` value before PATCH /agents/{id}/llm-key. responses: '200': description: OK. content: application/json: schema: type: object required: - providers properties: providers: type: array items: $ref: '#/components/schemas/LlmProviderInfo' security: [] operationId: getLlmProviders x-operation-id-source: derived components: schemas: ModelInfo: type: object required: - id - provider - name - label - costTier properties: id: type: string example: anthropic:claude-sonnet-4-5 description: Passed back as `model` on create / PATCH llm-key. provider: type: string enum: - openai - anthropic - openrouter - google - gemini - groq - mistral - deepseek - xai - nous name: type: string label: type: string costTier: type: string enum: - cheap - mid - premium Tier: type: object required: - id - name - spec - monthlyUsd - annualUsd properties: id: type: string enum: - tiny - small - medium - large name: type: string spec: type: string example: 2 GB RAM · 2 vCPU · 6 GB disk monthlyUsd: type: number annualUsd: type: number description: Annual price; two months free versus paying monthly. Persona: type: object description: 'Public catalog entry: a built-in persona, or a community persona once published.' required: - id - icon - name - tagline - forWho - does - skills - channels - category - tags - tier - spec - price - risk - disclaimer properties: id: type: string example: personal-assistant icon: type: string name: type: string tagline: type: string forWho: type: string does: type: array items: type: string doesExamples: type: object additionalProperties: type: string description: One example question per `does` label, keyed by that label. skills: type: array items: type: string channels: type: array items: type: string category: type: string enum: - study - creative - gaming - career - life - social - tech - fun tags: type: array items: type: string tier: type: string enum: - tiny - small - medium - large description: Recommended minimum plan for this persona. spec: type: string price: type: string example: $4.99/mo risk: type: string enum: - low - high disclaimer: type: - string - 'null' demo: type: array items: $ref: '#/components/schemas/DemoLine' description: Scripted, illustrative conversation. Absent when none was written. ru: $ref: '#/components/schemas/PersonaL10n' es: $ref: '#/components/schemas/PersonaL10n' pt: $ref: '#/components/schemas/PersonaL10n' tr: $ref: '#/components/schemas/PersonaL10n' ind: $ref: '#/components/schemas/PersonaL10n' description: Indonesian localization (key is `ind`, not `id`). authorId: type: string description: Present for user-created (community) personas. author: type: string status: type: string enum: - builtin - draft - published soul: type: string description: The persona's system prompt. deployedCount: type: integer recommendedModels: type: array items: type: string Engine: type: object required: - id - label - description - requiresDomain - minTier - status - capabilities properties: id: type: string enum: - hermes - openclaw - n8n - claude-code - opencode - pi label: type: string description: type: string requiresDomain: type: boolean minTier: type: string enum: - tiny - small - medium - large status: type: string enum: - stable - beta capabilities: $ref: '#/components/schemas/EngineCapabilities' ToolsetInfo: type: object required: - id - name - description - defaultEnabled - group properties: id: type: string name: type: string description: type: string defaultEnabled: type: boolean group: type: string enum: - web - files - media - voice - thinking - integrations - network plugin: type: string description: Set for entries that are Hermes plugins rather than built-in toolsets. DemoLine: type: object required: - role - text properties: role: type: string enum: - user - agent text: type: string EngineCapabilities: type: object required: - skills - mcp - skillRegistry - skillUninstall - llmKey - model - sso - dashCredentials properties: skills: type: boolean mcp: type: boolean skillRegistry: type: boolean description: Whether the engine can search a skill registry itself. skillUninstall: type: boolean llmKey: type: boolean model: type: boolean llmProviders: type: array items: type: string description: Providers this engine accepts; omitted means every provider AgentsPodium offers. sso: type: boolean dashCredentials: type: boolean PersonaL10n: type: object required: - name - tagline - forWho - does properties: name: type: string tagline: type: string forWho: type: string does: type: array items: type: string disclaimer: type: - string - 'null' doesExamples: type: object additionalProperties: type: string demo: type: array items: $ref: '#/components/schemas/DemoLine' LlmProviderInfo: type: object required: - id - label - envVar properties: id: type: string enum: - openai - anthropic - openrouter - google - gemini - groq - mistral - deepseek - xai - nous label: type: string envVar: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: An API key `ak_live_…` created on the account page, or a session token from /auth/verify.