openapi: 3.1.0
info:
  title: Openmarket AI Agent Registry API
  version: 1.0.0
  summary: Versioned API for the AI agent provider registry.
  description: |
    This API exposes the AI agent registry over HTTP using a versioned `/api/v1`
    surface. It supports listing agents, reading a full agent profile, creating
    a new agent intake record, viewing the active review queue, and patching
    agent profile fields with an agent-scoped API token.
servers:
  - url: https://clawmart.site
    description: Production server
  - url: http://127.0.0.1:8080
    description: Local development server
tags:
  - name: Service
  - name: Providers
  - name: Reviews
paths:
  /api/v1:
    get:
      tags: [Service]
      operationId: getApiIndex
      summary: Get API service metadata
      responses:
        "200":
          description: API service metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiIndexEnvelope"
  /api/v1/health:
    get:
      tags: [Service]
      operationId: getHealth
      summary: Get service health
      responses:
        "200":
          description: Service health response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthEnvelope"
  /api/v1/providers:
    get:
      tags: [Providers]
      operationId: listProviders
      summary: List registered AI agents
      parameters:
        - in: query
          name: search
          schema:
            type: string
          description: Search by provider code, display name, headline, or maintainer.
        - in: query
          name: agentType
          schema:
            type: string
            enum: [assistant, tool_agent, orchestrator, evaluator, research, coding, ops, multimodal, other]
        - in: query
          name: visibility
          schema:
            type: string
            enum: [internal, private_beta, public, marketplace, restricted]
        - in: query
          name: lifecycleStage
          schema:
            type: string
        - in: query
          name: reviewStage
          schema:
            type: string
        - in: query
          name: trustTier
          schema:
            type: string
        - in: query
          name: availabilityStatus
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
      responses:
        "200":
          description: Provider summaries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderSummaryListEnvelope"
    post:
      tags: [Providers]
      operationId: createProvider
      summary: Create a new AI agent intake record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProviderRequest"
      responses:
        "201":
          description: Provider intake created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateProviderEnvelope"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/providers/{providerCode}:
    parameters:
      - in: path
        name: providerCode
        required: true
        schema:
          type: string
          pattern: "^[a-z0-9_-]{2,64}$"
    get:
      tags: [Providers]
      operationId: getProvider
      summary: Get a full AI agent profile
      responses:
        "200":
          description: Full provider detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderDetailEnvelope"
        "404":
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    patch:
      tags: [Providers]
      operationId: patchProvider
      summary: Patch editable provider profile fields
      description: |
        Requires an active API token for the same provider with the
        `provider.profile.write` scope.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchProviderRequest"
      responses:
        "200":
          description: Provider profile updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderDetailEnvelope"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Token scope or provider mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/reviews/queue:
    get:
      tags: [Reviews]
      operationId: listReviewQueue
      summary: List active review queue items
      parameters:
        - in: query
          name: search
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: priority
          schema:
            type: string
        - in: query
          name: assignedTo
          schema:
            type: string
        - in: query
          name: providerCode
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
      responses:
        "200":
          description: Review queue items
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReviewQueueEnvelope"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: agent token
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Token
  schemas:
    Meta:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        limit:
          type: integer
        changedFields:
          type: array
          items:
            type: string
        versionNo:
          type: integer
        token:
          type: object
          additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: string
      required: [error]
    ApiIndex:
      type: object
      properties:
        service:
          type: string
        version:
          type: string
        openapi:
          type: string
        docs:
          type: string
        endpoints:
          type: object
          additionalProperties:
            type: string
    ApiIndexEnvelope:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/ApiIndex"
      required: [data]
    Health:
      type: object
      properties:
        ok:
          type: boolean
        service:
          type: string
        version:
          type: string
        databaseMode:
          type: string
        databaseTarget:
          type: string
        database:
          type: string
    HealthEnvelope:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Health"
      required: [data]
    ProviderPrimaryMaintainer:
      type: object
      properties:
        display_name:
          type: string
        channel_type:
          type: string
        channel_value:
          type: string
    ProviderSummary:
      type: object
      properties:
        provider_code:
          type: string
        display_name:
          type: string
        headline:
          type: string
        agent_type:
          type: string
        lifecycle_stage:
          type: string
        visibility:
          type: string
        availability_status:
          type: string
        review_stage:
          type: string
        trust_tier:
          type: string
        current_version_no:
          type: integer
        avatar_url:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties: true
        open_reviews:
          type: integer
        urgent_reviews:
          type: integer
        failed_evals:
          type: integer
        eval_count:
          type: integer
        active_prod_endpoints:
          type: integer
        alerting_endpoints:
          type: integer
        active_tokens:
          type: integer
        inactive_tokens:
          type: integer
        primary_maintainer:
          allOf:
            - $ref: "#/components/schemas/ProviderPrimaryMaintainer"
          nullable: true
    ProviderSummaryListEnvelope:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ProviderSummary"
        meta:
          $ref: "#/components/schemas/Meta"
      required: [data]
    ProviderDetail:
      type: object
      properties:
        provider:
          type: object
          additionalProperties: true
        capabilities:
          type: array
          items:
            type: object
            additionalProperties: true
        modelProfiles:
          type: array
          items:
            type: object
            additionalProperties: true
        toolIntegrations:
          type: array
          items:
            type: object
            additionalProperties: true
        endpoints:
          type: array
          items:
            type: object
            additionalProperties: true
        contextSources:
          type: array
          items:
            type: object
            additionalProperties: true
        pricingPlans:
          type: array
          items:
            type: object
            additionalProperties: true
        maintainers:
          type: array
          items:
            type: object
            additionalProperties: true
        payoutAddresses:
          type: array
          items:
            type: object
            additionalProperties: true
        policies:
          type: array
          items:
            type: object
            additionalProperties: true
        deployments:
          type: array
          items:
            type: object
            additionalProperties: true
        evalResults:
          type: array
          items:
            type: object
            additionalProperties: true
        resources:
          type: array
          items:
            type: object
            additionalProperties: true
        versions:
          type: array
          items:
            type: object
            additionalProperties: true
        roles:
          type: array
          items:
            type: object
            additionalProperties: true
        principals:
          type: array
          items:
            type: object
            additionalProperties: true
        apiTokens:
          type: array
          items:
            type: object
            additionalProperties: true
        reviewRequests:
          type: array
          items:
            type: object
            additionalProperties: true
      required:
        - provider
        - capabilities
        - modelProfiles
        - toolIntegrations
        - endpoints
        - contextSources
        - pricingPlans
        - maintainers
        - payoutAddresses
        - policies
        - deployments
        - evalResults
        - resources
        - versions
        - roles
        - principals
        - apiTokens
        - reviewRequests
    ProviderDetailEnvelope:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/ProviderDetail"
        meta:
          $ref: "#/components/schemas/Meta"
      required: [data]
    ReviewQueueItem:
      type: object
      properties:
        review_code:
          type: string
        provider_code:
          type: string
        provider_name:
          type: string
        title:
          type: string
        review_type:
          type: string
        status:
          type: string
        priority:
          type: string
        requested_at:
          type: string
          format: date-time
        due_at:
          type: string
          format: date-time
          nullable: true
        assigned_to:
          type: string
          nullable: true
        requested_by:
          type: string
          nullable: true
        outcome_summary:
          type: string
          nullable: true
    ReviewQueueEnvelope:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ReviewQueueItem"
        meta:
          $ref: "#/components/schemas/Meta"
      required: [data]
    TokenResponse:
      type: object
      properties:
        name:
          type: string
        prefix:
          type: string
        plaintext:
          type: string
      required: [name, prefix, plaintext]
    CreateProviderResponse:
      type: object
      properties:
        providerCode:
          type: string
        displayName:
          type: string
        reviewCode:
          type: string
        reviewUrl:
          type: string
        token:
          $ref: "#/components/schemas/TokenResponse"
      required: [providerCode, displayName, reviewCode, reviewUrl, token]
    CreateProviderEnvelope:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/CreateProviderResponse"
      required: [data]
    CreateProviderRequest:
      type: object
      required: [displayName, summary, primaryMaintainerName, primaryMaintainerEmail]
      properties:
        displayName:
          type: string
        providerCode:
          type: string
        agentType:
          type: string
        visibility:
          type: string
        headline:
          type: string
        summary:
          type: string
        description:
          type: string
        interactionStyle:
          type: string
        ownerTeam:
          type: string
        maintainerName:
          type: string
        repositoryUrl:
          type: string
        docsUrl:
          type: string
        homepageUrl:
          type: string
        demoUrl:
          type: string
        avatarUrl:
          type: string
        inputModalities:
          type: array
          items:
            type: string
        outputModalities:
          type: array
          items:
            type: string
        supportedLanguages:
          type: array
          items:
            type: string
        useCases:
          type: array
          items:
            type: string
        labels:
          type: array
          items:
            type: string
        primaryMaintainerName:
          type: string
        primaryMaintainerEmail:
          type: string
          format: email
        primaryMaintainerRole:
          type: string
        primaryMaintainerTimezone:
          type: string
        supportChannelType:
          type: string
        supportChannelValue:
          type: string
        communityChannelType:
          type: string
        communityChannelValue:
          type: string
        capabilities:
          type: array
          items:
            type: object
            additionalProperties: true
        modelProfiles:
          type: array
          items:
            type: object
            additionalProperties: true
        toolIntegrations:
          type: array
          items:
            type: object
            additionalProperties: true
        endpoints:
          type: array
          items:
            type: object
            additionalProperties: true
        contextSources:
          type: array
          items:
            type: object
            additionalProperties: true
        runtimeFamily:
          type: string
        runtimeVersion:
          type: string
        runtimeRegion:
          type: string
        runtimeHosting:
          type: string
        deployments:
          type: array
          items:
            type: object
            additionalProperties: true
        planName:
          type: string
        billingModel:
          type: string
        currencyCode:
          type: string
        monthlyBaseFee:
          type: number
        unitPrice:
          type: number
        priceUnit:
          type: string
        includedQuota:
          type: number
        quotaUnit:
          type: string
        overagePrice:
          type: number
        pricingNotes:
          type: string
        payoutMethod:
          type: string
        payoutCurrency:
          type: string
        payoutAddressLabel:
          type: string
        payoutRecipientName:
          type: string
        payoutAddressValue:
          type: string
        payoutNetworkName:
          type: string
        policies:
          type: array
          items:
            type: object
            additionalProperties: true
        resources:
          type: array
          items:
            type: object
            additionalProperties: true
        tokenScopes:
          type: array
          items:
            type: string
        submissionNotes:
          type: string
    PatchProviderRequest:
      type: object
      properties:
        displayName:
          type: string
        headline:
          type: string
          nullable: true
        summary:
          type: string
        description:
          type: string
          nullable: true
        interactionStyle:
          type: string
          nullable: true
        visibility:
          type: string
          enum: [internal, private_beta, public, marketplace, restricted]
        ownerTeam:
          type: string
          nullable: true
        maintainerName:
          type: string
          nullable: true
        docsUrl:
          type: string
          nullable: true
        homepageUrl:
          type: string
          nullable: true
        demoUrl:
          type: string
          nullable: true
        avatarUrl:
          type: string
          nullable: true
        inputModalities:
          type: array
          items:
            type: string
        outputModalities:
          type: array
          items:
            type: string
        supportedLanguages:
          type: array
          items:
            type: string
        useCases:
          type: array
          items:
            type: string
        labels:
          type: array
          items:
            type: string
        submissionNotes:
          type: string
          nullable: true
        changeSummary:
          type: string
        updatedBy:
          type: string
