openapi: 3.0.3
info:
  title: DumplingAI Unified API
  version: "2.0.0"
  description: |
    Transport reference for DumplingAI's Unified API under `/api/v2`.
    These endpoints cover search, details, execution, usage, and balance for capabilities, providers, and endpoints.
servers:
  - url: https://app.dumplingai.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Catalog
    description: Search and inspect capabilities and provider endpoints.
  - name: Execution
    description: Execute capabilities and provider endpoints.
  - name: Usage
    description: Inspect balance, usage, and transactions for a specific API key.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        requestId:
          type: string
        error:
          type: string
        code:
          type: string
      required:
        - success
        - requestId
        - error
        - code
    SearchRequest:
      type: object
      properties:
        prompt:
          type: string
        limit:
          type: integer
        type:
          type: string
          enum: [capability, provider, endpoint]
      required:
        - prompt
    SearchResult:
      type: object
      properties:
        id:
          type: string
        objectType:
          type: string
          enum: [capability, provider, endpoint]
        title:
          type: string
        description:
          type: string
        category:
          type: string
        supportedProviders:
          type: array
          items:
            type: string
        creditsCost:
          type: integer
        score:
          type: integer
    CatalogDetailsRequest:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [capability, provider, endpoint]
        includeRelated:
          type: boolean
          description: Include related providers, endpoints, and capabilities in the response.
      required:
        - id
        - type
    RunRequest:
      type: object
      properties:
        type:
          type: string
          enum: [capability, endpoint]
        id:
          type: string
          description: Capability id like `search_news` or `extract_document`, or endpoint id like `firecrawl.scrape`.
        provider:
          type: string
          description: Optional provider override for capability runs only when that capability supports provider selection. For example, `screenshot` supports `firecrawl`, `scrapingfish`, and `phantomjscloud`, while DumplingAI-managed capabilities such as `extract_document` use `dumplingai`.
        input:
          type: object
          additionalProperties: true
        options:
          type: object
          properties:
            include_native:
              type: boolean
          additionalProperties: false
      required:
        - type
        - id
        - input
paths:
  /api/v2/search:
    post:
      tags: [Catalog]
      summary: Search capabilities, providers, and endpoints
      x-mint:
        href: /api-reference/catalog/search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Unified catalog search results
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/details:
    post:
      tags: [Catalog]
      summary: Get capability, provider, or endpoint details
      x-mint:
        href: /api-reference/catalog/details
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogDetailsRequest'
      responses:
        '200':
          description: Catalog details
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown catalog item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/run:
    post:
      tags: [Execution]
      summary: Run a capability or endpoint
      x-mint:
        href: /api-reference/execution/run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunRequest'
      responses:
        '200':
          description: Capability result
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Policy rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown capability or endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/balance:
    get:
      tags: [Usage]
      summary: Get balance and budget information for the authenticated API key
      x-mint:
        href: /api-reference/usage/balance
      responses:
        '200':
          description: Balance information
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/usage:
    get:
      tags: [Usage]
      summary: Get usage and request logs for the authenticated API key
      x-mint:
        href: /api-reference/usage/requests
      parameters:
        - in: query
          name: objectType
          schema:
            type: string
            enum: [capability, provider, endpoint]
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: provider
          schema:
            type: string
        - in: query
          name: objectId
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          description: Usage information
  /api/v2/transactions:
    get:
      tags: [Usage]
      summary: Get credit transactions for the authenticated API key
      x-mint:
        href: /api-reference/usage/transactions
      parameters:
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          description: Transaction history