foundry-mcp-com Tier Guest API

openapi: 3.2.0
info:
  description: Public API for Foundry VTT instances connected via the bridge module.
  title: Foundry Tier Guest API
  version: 1.0.0
servers:
- description: API v1
  url: /v1
tags:
- description: Available to any caller with a valid API key, regardless of Patreon subscription status. The minimum authenticated surface.
  name: tier-guest
  x-displayName: Guest tier
paths:
  /world:
    get:
      description: Returns the metadata snapshot of the tenant's currently-loaded Foundry world (id, title, game system, engine and system versions). Backed by a `get-world-info` command sent over the bridge module's WebSocket connection — requires the user's Foundry instance to be online and connected.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorldInfoResponse'
          description: World metadata
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      security:
      - bearerAuth: []
      summary: Get world metadata
      tags:
      - tier-guest
      operationId: getWorld
      x-operation-id-source: derived
components:
  responses:
    ServiceUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: 'Service unavailable: the user''s Foundry module is not currently connected to the WebSocket bridge. Either the module isn''t installed, the user hasn''t opened a world, or the connection dropped while the request was in flight. Retry once a connection re-establishes.'
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: 'Authentication required: missing, malformed, or invalid API key.'
    BadGateway:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: 'Bad gateway: the Foundry module received the command but returned an error envelope. The body''s `error` carries the module''s reason (prefixed with our sentinel marker, e.g. `foundry command failed: world data not loaded`).'
    GatewayTimeout:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: 'Gateway timeout: the command was delivered to the Foundry module but no response arrived within the configured timeout. The module may be unresponsive or the operation may be slow on the Foundry side.'
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: An unexpected error occurred while processing the request. Retry later; contact support with the `X-Request-ID` header value if the problem persists.
  schemas:
    WorldInfoResponse:
      description: Metadata snapshot of the tenant's currently-loaded Foundry world. Wraps the world fields under `data` to match the envelope convention every public endpoint follows.
      properties:
        data:
          properties:
            foundry_version:
              description: Version string of the Foundry VTT engine.
              type: string
            id:
              description: Foundry world id. Stable across the lifetime of the world; changes only when the user switches to a different world.
              type: string
            system:
              description: 'Game system identifier. Examples: `dnd5e`, `pf2e`, `swade`.'
              type: string
            system_version:
              description: Version string of the installed game system module.
              type: string
            title:
              description: Human-readable title shown in the Foundry UI.
              type: string
          required:
          - id
          - title
          - system
          - system_version
          - foundry_version
          type: object
      required:
      - data
      type: object
    ErrorResponse:
      description: Standard error response. Used for every non-2xx outcome where the failure isn't tied to per-field request validation. The body carries a single human-readable `error` string; nothing else.
      properties:
        error:
          description: Short human-readable reason for the failure.
          type: string
      required:
      - error
      type: object
  securitySchemes:
    bearerAuth:
      description: 'API key issued via foundry-mcp Patreon registration. Include as `Authorization: Bearer <key>` on every authenticated endpoint.'
      scheme: bearer
      type: http