AgentsPodium Catalog API

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.