openapi: 3.0.3
info:
  title: SingularityNET Marketplace API
  description: The SingularityNET Marketplace REST API provides service discovery, organization management, and metadata access for the decentralized AI network. Browse available AI services, retrieve service metadata, check pricing, and access organization information. Service invocation uses gRPC through the daemon (snetd).
  version: '1.0'
  contact:
    name: SingularityNET Foundation
    url: https://singularitynet.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: SingularityNET Developer Portal
  url: https://dev.singularitynet.io
servers:
- url: https://marketplace-mt-v2.singularitynet.io
  description: Marketplace Production API
tags:
- name: Organizations
  description: AI service provider organization management
- name: Services
  description: AI service discovery and metadata
- name: Service Groups
  description: Service endpoint group management
- name: Channels
  description: Payment channel management for service access
paths:
  /org:
    get:
      operationId: listOrganizations
      summary: List Organizations
      description: Retrieve all registered organizations on the SingularityNET network that publish AI services.
      tags:
      - Organizations
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100
        description: Number of organizations to return
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        description: Pagination offset
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  total:
                    type: integer
  /org/{org_id}:
    get:
      operationId: getOrganization
      summary: Get Organization
      description: Retrieve detailed information about a specific AI service provider organization.
      tags:
      - Organizations
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
        description: Unique organization identifier
      responses:
        '200':
          description: Organization details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Organization'
        '404':
          description: Organization not found
  /org/{org_id}/service:
    get:
      operationId: listOrgServices
      summary: List Organization Services
      description: Retrieve all AI services published by a specific organization.
      tags:
      - Services
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
        description: Unique organization identifier
      responses:
        '200':
          description: List of services
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Service'
  /service:
    get:
      operationId: listServices
      summary: List Services
      description: Retrieve all AI services available on the SingularityNET Marketplace with optional filtering.
      tags:
      - Services
      parameters:
      - name: search_string
        in: query
        schema:
          type: string
        description: Text search across service names and descriptions
      - name: tags
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        description: Filter services by tag
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of AI services
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Service'
                  total:
                    type: integer
  /org/{org_id}/service/{service_id}:
    get:
      operationId: getService
      summary: Get Service
      description: Retrieve detailed metadata for a specific AI service including pricing, endpoints, and API specification location.
      tags:
      - Services
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
        description: Organization identifier
      - name: service_id
        in: path
        required: true
        schema:
          type: string
        description: Service identifier within the organization
      responses:
        '200':
          description: Service details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ServiceDetail'
        '404':
          description: Service not found
  /org/{org_id}/service/{service_id}/group:
    get:
      operationId: listServiceGroups
      summary: List Service Groups
      description: Retrieve endpoint groups for a service. Each group represents a set of daemon endpoints with associated payment channel configuration.
      tags:
      - Service Groups
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
      - name: service_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Service endpoint groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceGroup'
  /channel/open:
    post:
      operationId: openPaymentChannel
      summary: Open Payment Channel
      description: Open a Multi-Party Escrow (MPE) payment channel to fund AI service calls. Channels are funded with ASI tokens.
      tags:
      - Channels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelOpenRequest'
      responses:
        '200':
          description: Payment channel opened
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentChannel'
  /channel/{channel_id}:
    get:
      operationId: getChannel
      summary: Get Channel
      description: Retrieve the current state of a payment channel including balance and expiration.
      tags:
      - Channels
      parameters:
      - name: channel_id
        in: path
        required: true
        schema:
          type: string
        description: Payment channel identifier
      responses:
        '200':
          description: Channel details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentChannel'
        '404':
          description: Channel not found
  /channel/{channel_id}/extend:
    post:
      operationId: extendChannel
      summary: Extend Channel
      description: Add funds or extend the expiration of an existing payment channel.
      tags:
      - Channels
      parameters:
      - name: channel_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: string
                  description: Additional ASI tokens to deposit (in cogs)
                expiration:
                  type: integer
                  description: New expiration block number
      responses:
        '200':
          description: Channel extended
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentChannel'
components:
  schemas:
    Organization:
      type: object
      properties:
        org_id:
          type: string
          description: Unique organization identifier
        org_name:
          type: string
          description: Human-readable organization name
        org_type:
          type: string
          enum:
          - individual
          - organization
        description:
          type: string
        short_description:
          type: string
        url:
          type: string
          description: Organization website URL
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        assets:
          type: object
          properties:
            hero_image:
              $ref: '#/components/schemas/Asset'
        metadata_uri:
          type: string
          description: IPFS URI for organization metadata
        service_count:
          type: integer
    Contact:
      type: object
      properties:
        contact_type:
          type: string
          enum:
          - general
          - support
          - technical
        email:
          type: string
          format: email
        phone:
          type: string
    Asset:
      type: object
      properties:
        url:
          type: string
          description: Direct URL to the asset
        ipfs_hash:
          type: string
          description: IPFS content hash
    Service:
      type: object
      properties:
        org_id:
          type: string
        service_id:
          type: string
          description: Service identifier within the organization
        display_name:
          type: string
        short_description:
          type: string
        tags:
          type: array
          items:
            type: string
        rating:
          type: object
          properties:
            total_users_rated:
              type: integer
            average_rating:
              type: number
              format: float
        media:
          type: array
          items:
            type: object
        is_available:
          type: boolean
    ServiceDetail:
      allOf:
      - $ref: '#/components/schemas/Service'
      - type: object
        properties:
          description:
            type: string
          url:
            type: string
          contributors:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
          groups:
            type: array
            items:
              $ref: '#/components/schemas/ServiceGroup'
          service_api_source:
            type: string
            description: IPFS URI to the service proto/API specification
          metadata_uri:
            type: string
    ServiceGroup:
      type: object
      properties:
        group_id:
          type: string
          description: Group identifier hash
        group_name:
          type: string
        pricing:
          type: array
          items:
            $ref: '#/components/schemas/Pricing'
        endpoints:
          type: array
          items:
            type: object
            properties:
              endpoint:
                type: string
                description: gRPC daemon endpoint URL
          description: Daemon gRPC endpoints for this group
        payment:
          type: object
          properties:
            payment_address:
              type: string
              description: Ethereum wallet address for payments
            payment_expiration_threshold:
              type: integer
            payment_channel_storage_type:
              type: string
    Pricing:
      type: object
      properties:
        price_model:
          type: string
          enum:
          - fixed_price
          - fixed_price_per_kilo_bytes
          description: Pricing model
        price_in_cogs:
          type: integer
          description: Price per call in cogs (1 ASI = 10^8 cogs)
        default:
          type: boolean
    PaymentChannel:
      type: object
      properties:
        channel_id:
          type: string
          description: Payment channel identifier
        nonce:
          type: integer
          description: Current channel nonce
        balance_in_cogs:
          type: string
          description: Available balance in cogs
        pending:
          type: string
          description: Pending balance commitment
        endpoint:
          type: string
          description: Associated service endpoint
        expiration:
          type: integer
          description: Channel expiration block number
        signer:
          type: string
          description: Ethereum address of channel signer
    ChannelOpenRequest:
      type: object
      required:
      - org_id
      - service_id
      - group_id
      - amount_in_cogs
      - expiration
      properties:
        org_id:
          type: string
        service_id:
          type: string
        group_id:
          type: string
        amount_in_cogs:
          type: string
          description: Amount of ASI tokens to deposit (in cogs)
        expiration:
          type: integer
          description: Channel expiration block number