openapi: 3.1.0
info:
  title: Agentifact API
  version: "1.0"
  description: >
    Public API for the Agentifact agent ecosystem index.
    953+ tools scored across 5 trust dimensions.
  contact:
    email: security@agentifact.com
  license:
    name: Proprietary

servers:
  - url: https://agentifact.com
    description: Production

paths:
  /api/tools:
    get:
      operationId: listTools
      summary: List scored tools
      description: >
        Returns tools from the Agentifact index, filtered and sorted by
        composite trust score (descending). Supports category, approval mode,
        protocol, score, and workflow filters.
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum:
              - MCP_SERVER
              - HITL_PROVIDER
              - A2A_AGENT
              - FRAMEWORK
              - WORKFLOW_TEMPLATE
              - PROTOCOL
              - MODEL_PROVIDER
              - MONITORING
              - CODE_AGENT
              - MEMORY_CONTEXT
              - DATA_RETRIEVAL
              - COMPUTER_USE
              - WORKFLOW_CONNECTOR
              - EVAL_TESTING
          description: Filter by agent category
        - name: approvalMode
          in: query
          schema:
            type: string
            enum:
              - FULL_AUTO
              - REQUIRES_APPROVAL
              - HUMAN_IN_LOOP
              - NOT_APPLICABLE
          description: Filter by approval control mode
        - name: minScore
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100
          description: Minimum composite trust score
        - name: mcp
          in: query
          schema:
            type: string
            enum: ["true"]
          description: Filter to MCP-capable tools only
        - name: a2a
          in: query
          schema:
            type: string
            enum: ["true"]
          description: Filter to A2A-capable tools only
        - name: workflow
          in: query
          schema:
            type: string
          description: Filter by workflow fit tag
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of results (max 100)
        - name: format
          in: query
          schema:
            type: string
            enum: [json, ndjson]
            default: json
          description: Response format
      responses:
        "200":
          description: Tool listing
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: "#/components/schemas/Meta"
                  tools:
                    type: array
                    items:
                      $ref: "#/components/schemas/Tool"
            application/x-ndjson:
              schema:
                type: string
                description: Newline-delimited JSON (one Tool object per line)
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until rate limit resets

components:
  schemas:
    Meta:
      type: object
      properties:
        total:
          type: integer
        filters:
          type: object
        schema_version:
          type: string
        generated_at:
          type: string
          format: date-time
        methodology:
          type: string
          description: Path to scoring methodology page

    Tool:
      type: object
      properties:
        id:
          type: string
          description: URL slug
        name:
          type: string
        url:
          type: string
          nullable: true
        category:
          type: string
        description:
          type: string
        scores:
          type: object
          properties:
            composite:
              type: integer
              nullable: true
            agentReadiness:
              type: integer
              nullable: true
            trust:
              type: integer
              nullable: true
            interop:
              type: integer
              nullable: true
            security:
              type: integer
              nullable: true
            documentation:
              type: integer
              nullable: true
        approvalControlMode:
          type: string
          nullable: true
        protocols:
          type: object
          properties:
            mcp:
              type: boolean
            a2a:
              type: boolean
            a2h:
              type: boolean
            rest:
              type: boolean
            agentCallable:
              type: boolean
        knownFailureModes:
          type: array
          items:
            type: string
        governanceControls:
          type: array
          items:
            type: string
        workflowFitTags:
          type: array
          items:
            type: string
        transactionCapable:
          type: boolean
        acpSupport:
          type: boolean
        auditTraceAvailable:
          type: boolean
        pricing:
          type: object
          properties:
            model:
              type: string
              nullable: true
            range:
              type: string
              nullable: true
        tier:
          type: string
          enum: [DIRECTORY, REGISTRY]
        lastVerified:
          type: string
          format: date-time
          nullable: true
        stale:
          type: boolean
        tags:
          type: array
          items:
            type: string