{
  "openapi": "3.1.0",
  "info": {
    "title": "PairAgentic Registry API",
    "version": "1.0.0",
    "description": "Public read-only API for the PairAgentic registry of AI agencies, agents, and skills. Every entity carries `verified` (moderator-reviewed) and `promoted` (active paid placement \u2014 disclosed, never used for ranking). Rate limit: 120 requests/minute per IP. An MCP endpoint exposing the same registry is at https://pairagentic.com/api/mcp (Streamable HTTP).",
    "contact": {
      "url": "https://pairagentic.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://pairagentic.com/api/v1"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getDiscovery",
        "summary": "API discovery document",
        "responses": {
          "200": {
            "description": "Discovery document listing endpoints, MCP info, and rate limits."
          }
        }
      }
    },
    "/agents": {
      "get": {
        "operationId": "searchAgents",
        "summary": "Search agents",
        "parameters": [
          {
            "name": "use_case",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring match on use case."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "capability",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pricing_model",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_rating",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 5
            }
          },
          {
            "$ref": "#/components/parameters/verified_only"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching agents.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AgentSummary"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/agents/{slug}": {
      "get": {
        "operationId": "getAgent",
        "summary": "Agent details",
        "parameters": [
          {
            "$ref": "#/components/parameters/slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent detail including description and parent agency.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgentDetail"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/agencies": {
      "get": {
        "operationId": "searchAgencies",
        "summary": "Search agencies",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Matches name or description."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/verified_only"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching agencies.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AgencySummary"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/agencies/{slug}": {
      "get": {
        "operationId": "getAgency",
        "summary": "Agency details including its agents and skills",
        "parameters": [
          {
            "$ref": "#/components/parameters/slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Agency detail.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AgencyDetail"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/skills": {
      "get": {
        "operationId": "searchSkills",
        "summary": "Search skills",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Matches name, use case, or description."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "capability",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/verified_only"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching skills.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SkillSummary"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/skills/{slug}": {
      "get": {
        "operationId": "getSkill",
        "summary": "Skill details including agents that have it attached",
        "parameters": [
          {
            "$ref": "#/components/parameters/slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Skill detail.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SkillDetail"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/capabilities": {
      "get": {
        "operationId": "listCapabilities",
        "summary": "All unique capability strings across agents",
        "responses": {
          "200": {
            "description": "Capability list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/integrations": {
      "get": {
        "operationId": "listIntegrations",
        "summary": "All unique integration strings across agents",
        "responses": {
          "200": {
            "description": "Integration list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "slug": {
        "name": "slug",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "default": 20
        }
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10000,
          "default": 0
        }
      },
      "verified_only": {
        "name": "verified_only",
        "in": "query",
        "schema": {
          "type": "boolean"
        },
        "description": "Restrict to moderator-verified listings."
      }
    },
    "responses": {
      "NotFound": {
        "description": "No entity with that slug."
      },
      "RateLimited": {
        "description": "Over the 120 req/min per-IP limit. Retry-After header set."
      }
    },
    "schemas": {
      "Rating": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "avg": {
            "type": "number"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "AgencyRef": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "verified": {
            "type": "boolean"
          }
        }
      },
      "AgentSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "use_case": {
            "type": [
              "string",
              "null"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "integrations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pricing_model": {
            "type": [
              "string",
              "null"
            ]
          },
          "verified": {
            "type": "boolean",
            "description": "Moderator-reviewed listing."
          },
          "promoted": {
            "type": "boolean",
            "description": "Active paid placement. Disclosed, never used for ranking."
          },
          "rating": {
            "$ref": "#/components/schemas/Rating"
          },
          "agency": {
            "$ref": "#/components/schemas/AgencyRef"
          }
        }
      },
      "AgentDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentSummary"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "trust": {
                "$ref": "#/components/schemas/TrustSnapshot"
              }
            }
          }
        ]
      },
      "AgencySummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "location": {
            "type": [
              "string",
              "null"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "entity_type": {
            "type": "string",
            "enum": [
              "agency",
              "solo_dev"
            ]
          },
          "verified": {
            "type": "boolean"
          },
          "promoted": {
            "type": "boolean"
          },
          "rating": {
            "$ref": "#/components/schemas/Rating"
          }
        }
      },
      "AgencyDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgencySummary"
          },
          {
            "type": "object",
            "properties": {
              "linkedin_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "github_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "agents": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "skills": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "trust": {
                "$ref": "#/components/schemas/TrustSnapshot"
              }
            }
          }
        ]
      },
      "SkillSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "use_case": {
            "type": [
              "string",
              "null"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "integrations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pricing_model": {
            "type": [
              "string",
              "null"
            ]
          },
          "github_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "verified": {
            "type": "boolean"
          },
          "agency": {
            "$ref": "#/components/schemas/AgencyRef"
          }
        }
      },
      "SkillDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SkillSummary"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "agents": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          }
        ]
      },
      "TrustSnapshot": {
        "type": "object",
        "description": "Trust snapshot computed from moderator verification, listing claims, and published verified-engagement reviews.",
        "properties": {
          "level": {
            "type": "string",
            "enum": [
              "unverified",
              "verified",
              "claimed",
              "claimed_verified"
            ]
          },
          "verified": {
            "type": "boolean"
          },
          "claimed": {
            "type": "boolean"
          },
          "verified_engagement_reviews": {
            "type": "integer"
          },
          "listed_since": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}