openapi: 3.1.0
info:
  title: Immersa API
  version: '2026-10-18'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-18: 3 operation(s) read from 3 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Immersa has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 2
    pages-with-code: 2
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-18'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.marcopolo.dev/getting-started
  - https://docs.marcopolo.dev/getting-started/claude-code
  - https://docs.marcopolo.dev/getting-started/developer-sdk/api-reference
servers:
- url: https://mcp.marcopolo.dev
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://docs.marcopolo.dev/getting-started
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: 'http https://mcp.marcopolo.dev Plugin: Install the Claude Plugin Codex MCP: Add https://mcp.marcopolo.dev to ~/.codex/config.toml
          Plugin: Install the Codex Plugin ChatGPT Apps Marketplace → Search "MarcoPolo" Cursor / VS Code Add https://mcp.marcopolo.dev to your
          mcp.json or MCP settings. '
  /api/v1/connection-setup-sessions:
    post:
      operationId: post_api_v1_connection_setup_sessions
      tags:
      - Api
      summary: Connection setup (hosted OAuth)
      description: Starts a hosted OAuth connection‑setup session.
      x-source: https://docs.marcopolo.dev/getting-started/developer-sdk/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1ConnectionSetupSessionsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1ConnectionSetupSessionsResponse'
      x-evidence:
        kind: documentation
  /api/v1/connection-setup-sessions/{setupSessionId}:
    get:
      operationId: get_api_v1_connection_setup_sessions_setupSessionId
      tags:
      - Api
      summary: Connection setup (hosted OAuth)
      description: Retrieves the status of a hosted OAuth connection‑setup session.
      x-source: https://docs.marcopolo.dev/getting-started/developer-sdk/api-reference
      parameters:
      - name: setupSessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1ConnectionSetupSessionsSetupsessionidResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostApiV1ConnectionSetupSessionsRequest:
      type: object
      properties:
        connection_type:
          type: string
          description: The stable identifier of the connection type to set up.
        display_name:
          type: string
          description: Human‑readable name for the connection that will be created.
        return_url:
          type: string
          description: Optional URL to which the provider will return the user after OAuth flow.
        client_session_id:
          type: string
          description: Id to reuse an in‑flight session instead of creating a duplicate.
        requested_scopes:
          type: array
          description: OAuth scopes requested from the provider.
      required:
      - connection_type
      - display_name
    PostApiV1ConnectionSetupSessionsResponse:
      type: object
      properties:
        setup_session_id:
          type: string
          description: Unguessable, user‑scoped identifier for the setup session.
        status:
          type: string
          description: Literal "pending" while the flow is in progress.
        connection_type:
          type: string
          description: The connection type being set up.
        connection_name:
          type: string
          description: Name the connection will have once ready.
        display_name:
          type: string
          description: Human‑readable name supplied in the request.
        return_url:
          type: string
          description: The return URL if one was provided.
        created_at:
          type: string
          description: Timestamp when the session was created.
        expires_at:
          type: string
          description: Timestamp when the session expires (15 minutes after last change).
        failure:
          type: object
          description: Object with code and message set only if the session fails.
        authorization_url:
          type: string
          description: URL to open in the user’s browser to complete the OAuth flow (present in the start response).
    GetApiV1ConnectionSetupSessionsSetupsessionidResponse:
      type: object
      properties:
        setup_session_id:
          type: string
          description: Unguessable, user‑scoped identifier.
        status:
          type: string
          description: Literal "pending", "ready", or "failed".
        connection_type:
          type: string
          description: The connection type being set up.
        connection_name:
          type: string
          description: Name the connection will have once ready.
        display_name:
          type: string
          description: Human‑readable name supplied at start.
        return_url:
          type: string
          description: Optional return URL if one was provided.
        created_at:
          type: string
          description: When the session was created.
        expires_at:
          type: string
          description: When the session expires.
        failure:
          type: object
          description: Object with code and message set only on failure.
  securitySchemes:
    API_token:
      type: http
      scheme: bearer
      x-source: https://docs.marcopolo.dev/getting-started
tags:
- name: Api
security:
- API_token: []