{
  "openapi": "3.1.0",
  "info": {
    "title": "Twitter API — Network",
    "version": "1.0.0",
    "description": "Followers, following, and audience graph lookups."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/twitter"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/following": {
      "post": {
        "operationId": "following",
        "tags": [
          "Network"
        ],
        "summary": "Fetch following list",
        "description": "Retrieve accounts followed by a user with basic profile metadata per account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "handle": {
                    "type": "string",
                    "description": "Twitter handle without @."
                  },
                  "count": {
                    "type": "number",
                    "description": "Number of accounts (max 100).",
                    "example": "25"
                  },
                  "cursor": {
                    "type": "string",
                    "description": "Pagination cursor."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "handle"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "handle": "sama",
                    "count": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "handle": {
                            "type": "string",
                            "description": "User handle."
                          },
                          "displayName": {
                            "type": "string",
                            "description": "Display name."
                          },
                          "description": {
                            "type": "string",
                            "description": "Bio text."
                          },
                          "isVerified": {
                            "type": "boolean",
                            "description": "Verification status."
                          },
                          "followersCount": {
                            "type": "number",
                            "description": "Follower count."
                          },
                          "avatarUrl": {
                            "type": "string",
                            "description": "Profile image URL."
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "cursor": {
                      "type": "string",
                      "description": "Pagination cursor."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "users": [
                        {
                          "handle": "gdb",
                          "displayName": "Greg Brockman",
                          "description": "President & Co-Founder @OpenAI.",
                          "isVerified": true,
                          "followersCount": 1200000,
                          "avatarUrl": "https://pbs.twimg.com/profile_images/gdb_normal.jpg"
                        },
                        {
                          "handle": "miramurati",
                          "displayName": "Mira Murati",
                          "description": "CTO @OpenAI.",
                          "isVerified": true,
                          "followersCount": 450000,
                          "avatarUrl": "https://pbs.twimg.com/profile_images/mira_normal.jpg"
                        }
                      ],
                      "cursor": "DAABCgABF8zK9v__-Z2"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/followers": {
      "post": {
        "operationId": "followers",
        "tags": [
          "Network"
        ],
        "summary": "Fetch followers list",
        "description": "Retrieve follower accounts for a user with the same profile metadata shape as the following endpoint.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "handle": {
                    "type": "string",
                    "description": "Twitter handle without @."
                  },
                  "count": {
                    "type": "number",
                    "description": "Number of accounts (max 100).",
                    "example": "25"
                  },
                  "cursor": {
                    "type": "string",
                    "description": "Pagination cursor."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "handle"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "handle": "sama",
                    "count": 2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "handle": {
                            "type": "string",
                            "description": "User handle."
                          },
                          "displayName": {
                            "type": "string",
                            "description": "Display name."
                          },
                          "description": {
                            "type": "string",
                            "description": "Bio text."
                          },
                          "isVerified": {
                            "type": "boolean",
                            "description": "Verification status."
                          },
                          "followersCount": {
                            "type": "number",
                            "description": "Follower count."
                          },
                          "avatarUrl": {
                            "type": "string",
                            "description": "Profile image URL."
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "cursor": {
                      "type": "string",
                      "description": "Pagination cursor."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "users": [
                        {
                          "handle": "karpathy",
                          "displayName": "Andrej Karpathy",
                          "description": "Building @EurekaLabsAI. Previously: Director of AI @Tesla, founding team @OpenAI, CS PhD @Stanford.",
                          "isVerified": true,
                          "followersCount": 1100000,
                          "avatarUrl": "https://pbs.twimg.com/profile_images/karpathy_normal.jpg"
                        },
                        {
                          "handle": "ylecun",
                          "displayName": "Yann LeCun",
                          "description": "Professor at NYU. Chief AI Scientist at Meta. Turing Award. Researcher in AI, Machine Learning, Robotics, etc.",
                          "isVerified": true,
                          "followersCount": 850000,
                          "avatarUrl": "https://pbs.twimg.com/profile_images/ylecun_normal.jpg"
                        }
                      ],
                      "cursor": "DAABCgABF8zK9v__-Z3"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/verified-followers": {
      "post": {
        "operationId": "verified-followers",
        "tags": [
          "Network"
        ],
        "summary": "Fetch blue-verified followers",
        "description": "Retrieve blue-verified followers for a user — useful for filtering high-signal accounts from large follower lists. Returns the same profile shape as the followers endpoint.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "handle": {
                    "type": "string",
                    "description": "Twitter handle without @."
                  },
                  "count": {
                    "type": "number",
                    "description": "Number of accounts (max 100).",
                    "example": "25"
                  },
                  "cursor": {
                    "type": "string",
                    "description": "Pagination cursor."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "handle"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "handle": "openai",
                    "count": 2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "handle": {
                            "type": "string",
                            "description": "User handle."
                          },
                          "displayName": {
                            "type": "string",
                            "description": "Display name."
                          },
                          "description": {
                            "type": "string",
                            "description": "Bio text."
                          },
                          "isVerified": {
                            "type": "boolean",
                            "description": "Always true for this endpoint."
                          },
                          "followersCount": {
                            "type": "number",
                            "description": "Follower count."
                          },
                          "avatarUrl": {
                            "type": "string",
                            "description": "Profile image URL."
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "cursor": {
                      "type": "string",
                      "description": "Pagination cursor."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "users": [
                        {
                          "handle": "satyanadella",
                          "displayName": "Satya Nadella",
                          "description": "Chairman and CEO at Microsoft.",
                          "isVerified": true,
                          "followersCount": 3200000,
                          "avatarUrl": "https://pbs.twimg.com/profile_images/satya_normal.jpg"
                        },
                        {
                          "handle": "elonmusk",
                          "displayName": "Elon Musk",
                          "description": "Mars & Cars, Chips & Dips",
                          "isVerified": true,
                          "followersCount": 180000000,
                          "avatarUrl": "https://pbs.twimg.com/profile_images/elon_normal.jpg"
                        }
                      ],
                      "cursor": "DAABCgABF8zK9v__-Z4"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}