{
  "openapi": "3.1.0",
  "info": {
    "title": "The Agent Registry API",
    "version": "2.0.0",
    "description": "An open protocol directory for A2A (Agent-to-Agent) and x402 (HTTP 402 Payment Protocol) implementations. Agents and services can self-register via API, humans can browse and search.",
    "contact": {
      "name": "The Agent Registry",
      "url": "https://a2alist.ai"
    }
  },
  "servers": [
    {
      "url": "https://a2alist.ai",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/agents": {
      "get": {
        "summary": "List and search protocol implementations",
        "description": "Browse and search A2A agents and x402 services with filtering by protocol, category, search query, and pagination",
        "tags": [
          "Agents"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query (searches name, description, and skills)",
            "required": false,
            "schema": {
              "type": "string",
              "example": "payment"
            }
          },
          {
            "name": "protocol",
            "in": "query",
            "description": "Filter by protocol type",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "a2a",
                "x402"
              ],
              "example": "x402"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category",
            "required": false,
            "schema": {
              "type": "string",
              "example": "facilitator"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of results per page",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 25,
              "enum": [
                25,
                50,
                100
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order",
            "required": false,
            "schema": {
              "type": "string",
              "default": "created_at",
              "enum": [
                "name",
                "stars",
                "created_at"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agents": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Agent"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of agents matching the query"
                    },
                    "page": {
                      "type": "integer",
                      "description": "Current page number"
                    },
                    "per_page": {
                      "type": "integer",
                      "description": "Number of results per page"
                    }
                  }
                },
                "example": {
                  "agents": [
                    {
                      "id": 1,
                      "name": "Example Agent",
                      "slug": "example-agent",
                      "description": "An example A2A protocol agent",
                      "category": "Development",
                      "url": "https://example.com/agent",
                      "agent_card_url": "https://example.com/.well-known/agent.json",
                      "skills": [
                        "coding",
                        "debugging",
                        "code-review"
                      ],
                      "input_modes": [
                        "text",
                        "application/json"
                      ],
                      "output_modes": [
                        "text",
                        "application/json"
                      ],
                      "auth_type": "apiKey",
                      "provider": "Example Corp",
                      "version": "1.0.0",
                      "streaming": true,
                      "push_notifications": false,
                      "verified": false,
                      "pricing": "free",
                      "github": "https://github.com/example/agent",
                      "submitted_by": "user@example.com",
                      "created_at": "2026-02-15T10:00:00Z",
                      "updated_at": "2026-02-15T10:00:00Z"
                    }
                  ],
                  "total": 42,
                  "page": 1,
                  "per_page": 25
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Register a new agent",
        "description": "Self-register an A2A agent in the directory. Requires an API key obtained via POST /api/keys.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentCreate"
              },
              "example": {
                "name": "My Agent",
                "description": "A helpful AI agent",
                "category": "Development",
                "url": "https://myagent.example.com",
                "agent_card_url": "https://myagent.example.com/.well-known/agent.json",
                "skills": [
                  "coding",
                  "testing"
                ],
                "input_modes": [
                  "text"
                ],
                "output_modes": [
                  "text"
                ],
                "auth_type": "apiKey",
                "provider": "My Company",
                "version": "1.0.0",
                "streaming": true,
                "push_notifications": false,
                "pricing": "free",
                "github": "https://github.com/mycompany/myagent",
                "submitted_by": "dev@example.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Missing required fields: name, description, category"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Unauthorized: Invalid API key"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - agent with this name already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Agent with slug \"my-agent\" already exists"
                }
              }
            }
          }
        }
      }
    },
    "/api/agents/{slug}": {
      "get": {
        "summary": "Get agent details",
        "description": "Get detailed information about a specific agent by slug",
        "tags": [
          "Agents"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Agent slug (URL-friendly identifier)",
            "required": true,
            "schema": {
              "type": "string",
              "example": "example-agent"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Agent not found"
                }
              }
            }
          }
        }
      }
    },
    "/api/a2a": {
      "post": {
        "summary": "A2A JSON-RPC endpoint",
        "description": "JSON-RPC 2.0 endpoint for agent-to-agent communication. Supports submitting agents, checking status, and cancelling submissions.",
        "tags": [
          "A2A"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "tasks/send": {
                  "summary": "Submit a new agent",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tasks/send",
                    "params": {
                      "name": "My API Service",
                      "url": "https://api.example.com",
                      "description": "An x402-enabled API service",
                      "protocol": "x402",
                      "category": "API",
                      "github_url": "https://github.com/example/api",
                      "pricing": "$0.01/call",
                      "endpoint_count": 5
                    }
                  }
                },
                "tasks/get": {
                  "summary": "Check submission status",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tasks/get",
                    "params": {
                      "taskId": "task_abc123_xyz789"
                    }
                  }
                },
                "tasks/cancel": {
                  "summary": "Cancel a pending submission",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tasks/cancel",
                    "params": {
                      "taskId": "task_abc123_xyz789"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful submission",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 1,
                      "result": {
                        "taskId": "task_abc123_xyz789",
                        "status": "pending",
                        "message": "Submission received and queued for review.",
                        "remainingSubmissions": 9
                      }
                    }
                  },
                  "error": {
                    "summary": "Error response",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 1,
                      "error": {
                        "code": -32602,
                        "message": "Missing required parameters: name, url",
                        "data": {
                          "required": [
                            "name",
                            "url",
                            "description",
                            "protocol",
                            "category"
                          ],
                          "missing": [
                            "name",
                            "url"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "A2A endpoint info",
        "description": "Get information about the A2A endpoint and available methods",
        "tags": [
          "A2A"
        ],
        "responses": {
          "200": {
            "description": "Endpoint information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "type": "null"
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        },
                        "methods": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "summary": "A2A Agent Card",
        "description": "Returns the A2A agent card for this directory service",
        "tags": [
          "A2A"
        ],
        "responses": {
          "200": {
            "description": "Agent card",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentCard"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys": {
      "post": {
        "summary": "Generate API key",
        "description": "Generate an API key for registering agents",
        "tags": [
          "API Keys"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Your name or organization name",
                    "example": "John Doe"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Your email address",
                    "example": "john@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string",
                      "description": "Your API key (save this securely, it cannot be retrieved again)",
                      "example": "aal_1234567890abcdef"
                    },
                    "message": {
                      "type": "string",
                      "example": "API key created successfully. Save this key securely, it cannot be retrieved again."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Missing required fields: name, email"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Agent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier"
          },
          "name": {
            "type": "string",
            "description": "Agent name"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly identifier"
          },
          "description": {
            "type": "string",
            "description": "Agent description"
          },
          "category": {
            "type": "string",
            "description": "Agent category",
            "enum": [
              "Development",
              "Research",
              "Productivity",
              "Creative",
              "Business",
              "Social",
              "Education",
              "Other"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Agent endpoint URL",
            "nullable": true
          },
          "agent_card_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to agent.json file",
            "nullable": true
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of agent skills/capabilities"
          },
          "input_modes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported input formats",
            "default": [
              "text"
            ]
          },
          "output_modes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported output formats",
            "default": [
              "text"
            ]
          },
          "auth_type": {
            "type": "string",
            "description": "Authentication type",
            "enum": [
              "none",
              "apiKey",
              "oauth",
              "basic"
            ],
            "default": "none"
          },
          "protocol": {
            "type": "string",
            "description": "Protocol type",
            "enum": [
              "a2a",
              "x402"
            ],
            "default": "a2a"
          },
          "provider": {
            "type": "string",
            "description": "Provider/organization name (A2A only)",
            "nullable": true
          },
          "version": {
            "type": "string",
            "description": "Agent version (A2A only)",
            "nullable": true
          },
          "chain": {
            "type": "string",
            "description": "Blockchain network (x402 only)",
            "nullable": true,
            "example": "Base"
          },
          "token": {
            "type": "string",
            "description": "Payment token (x402 only)",
            "nullable": true,
            "example": "USDC"
          },
          "tx_volume": {
            "type": "string",
            "description": "Transaction volume (x402 only)",
            "nullable": true,
            "example": "$24M/30d"
          },
          "tx_count": {
            "type": "string",
            "description": "Transaction count (x402 only)",
            "nullable": true,
            "example": "75.41M"
          },
          "streaming": {
            "type": "boolean",
            "description": "Supports streaming responses",
            "default": false
          },
          "push_notifications": {
            "type": "boolean",
            "description": "Supports push notifications",
            "default": false
          },
          "verified": {
            "type": "boolean",
            "description": "Legacy compatibility field. True when a listing has passed safe review.",
            "default": false
          },
          "safe_reviewed": {
            "type": "boolean",
            "description": "True when a listing is currently rated Safe.",
            "default": false
          },
          "pricing": {
            "type": "string",
            "description": "Pricing model",
            "enum": [
              "free",
              "freemium",
              "paid"
            ],
            "default": "free"
          },
          "github": {
            "type": "string",
            "format": "uri",
            "description": "GitHub repository URL",
            "nullable": true
          },
          "submitted_by": {
            "type": "string",
            "description": "Email of submitter",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp"
          }
        },
        "required": [
          "id",
          "name",
          "slug",
          "description",
          "category"
        ]
      },
      "AgentCreate": {
        "type": "object",
        "required": [
          "name",
          "description",
          "category"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Agent name",
            "example": "My Agent"
          },
          "description": {
            "type": "string",
            "description": "Agent description",
            "example": "A helpful AI agent"
          },
          "category": {
            "type": "string",
            "description": "Agent category",
            "enum": [
              "Development",
              "Research",
              "Productivity",
              "Creative",
              "Business",
              "Social",
              "Education",
              "Other"
            ],
            "example": "Development"
          },
          "protocol": {
            "type": "string",
            "description": "Protocol type",
            "enum": [
              "a2a",
              "x402"
            ],
            "default": "a2a",
            "example": "a2a"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Agent endpoint URL",
            "example": "https://myagent.example.com"
          },
          "agent_card_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to agent.json file",
            "example": "https://myagent.example.com/.well-known/agent.json"
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of agent skills/capabilities",
            "default": [],
            "example": [
              "coding",
              "testing"
            ]
          },
          "input_modes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported input formats",
            "default": [
              "text"
            ],
            "example": [
              "text",
              "application/json"
            ]
          },
          "output_modes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported output formats",
            "default": [
              "text"
            ],
            "example": [
              "text",
              "application/json"
            ]
          },
          "auth_type": {
            "type": "string",
            "description": "Authentication type",
            "enum": [
              "none",
              "apiKey",
              "oauth",
              "basic"
            ],
            "default": "none",
            "example": "apiKey"
          },
          "provider": {
            "type": "string",
            "description": "Provider/organization name",
            "example": "My Company"
          },
          "version": {
            "type": "string",
            "description": "Agent version",
            "example": "1.0.0"
          },
          "streaming": {
            "type": "boolean",
            "description": "Supports streaming responses",
            "default": false,
            "example": true
          },
          "push_notifications": {
            "type": "boolean",
            "description": "Supports push notifications",
            "default": false,
            "example": false
          },
          "pricing": {
            "type": "string",
            "description": "Pricing model",
            "enum": [
              "free",
              "freemium",
              "paid"
            ],
            "default": "free",
            "example": "free"
          },
          "github": {
            "type": "string",
            "format": "uri",
            "description": "GitHub repository URL",
            "example": "https://github.com/mycompany/myagent"
          },
          "submitted_by": {
            "type": "string",
            "format": "email",
            "description": "Email of submitter",
            "example": "dev@example.com"
          },
          "chain": {
            "type": "string",
            "description": "Blockchain network (x402 only)",
            "example": "Base"
          },
          "token": {
            "type": "string",
            "description": "Payment token (x402 only)",
            "example": "USDC"
          },
          "tx_volume": {
            "type": "string",
            "description": "Transaction volume (x402 only)",
            "example": "$1.2M/30d"
          },
          "tx_count": {
            "type": "string",
            "description": "Transaction count (x402 only)",
            "example": "500K+"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "details": {
            "type": "string",
            "description": "Additional error details"
          }
        },
        "required": [
          "error"
        ]
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ],
            "description": "JSON-RPC version (must be \"2.0\")"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Request identifier"
          },
          "method": {
            "type": "string",
            "enum": [
              "tasks/send",
              "tasks/get",
              "tasks/cancel"
            ],
            "description": "Method to invoke"
          },
          "params": {
            "type": "object",
            "description": "Method parameters"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "type": "object",
            "description": "Success result (mutually exclusive with error)"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {
                "type": "object"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "description": "Error object (mutually exclusive with result)"
          }
        }
      },
      "AgentCard": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "version": {
            "type": "string"
          },
          "provider": {
            "type": "object",
            "properties": {
              "organization": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "streaming": {
                "type": "boolean"
              },
              "pushNotifications": {
                "type": "boolean"
              }
            }
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "inputModes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "outputModes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "defaultInputModes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "defaultOutputModes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API key obtained via POST /api/keys. Use format: Bearer {your_api_key}"
      }
    }
  },
  "tags": [
    {
      "name": "Agents",
      "description": "Operations related to A2A agents and x402 services"
    },
    {
      "name": "A2A",
      "description": "A2A protocol endpoints for agent-to-agent communication"
    },
    {
      "name": "API Keys",
      "description": "API key management"
    }
  ]
}