{
  "openapi": "3.1.0",
  "info": {
    "title": "Twitter API — Search",
    "version": "1.0.0",
    "description": "Keyword and product-based Twitter search."
  },
  "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": {
    "/search": {
      "post": {
        "operationId": "search",
        "tags": [
          "Search"
        ],
        "summary": "Search X/Twitter by keyword",
        "description": "Run a Twitter search using the selected product view such as Top, Latest, People, Media, or Lists. Results include tweet text, author info, engagement counts, and media metadata.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search query."
                  },
                  "product": {
                    "type": "string",
                    "description": "Twitter product tab.",
                    "example": "Top"
                  },
                  "count": {
                    "type": "number",
                    "description": "Number of results (max 100).",
                    "example": "25"
                  },
                  "cursor": {
                    "type": "string",
                    "description": "Pagination cursor for next page."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "openai",
                    "product": "Latest",
                    "count": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Unique tweet identifier."
                          },
                          "text": {
                            "type": "string",
                            "description": "Full tweet text with URLs t.co-unwrapped."
                          },
                          "author": {
                            "type": "object",
                            "properties": {
                              "handle": {
                                "type": "string",
                                "description": "Author handle without @."
                              },
                              "displayName": {
                                "type": "string",
                                "description": "Author display name."
                              },
                              "isVerified": {
                                "type": "boolean",
                                "description": "Whether the author is verified."
                              }
                            },
                            "additionalProperties": false
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "ISO 8601 timestamp."
                          },
                          "likeCount": {
                            "type": "number",
                            "description": "Number of likes."
                          },
                          "replyCount": {
                            "type": "number",
                            "description": "Number of replies."
                          },
                          "retweetCount": {
                            "type": "number",
                            "description": "Number of retweets/reposts."
                          },
                          "viewCount": {
                            "type": "number",
                            "description": "Impression count (when available)."
                          },
                          "url": {
                            "type": "string",
                            "description": "Canonical tweet URL."
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "cursor": {
                      "type": "string",
                      "description": "Pagination cursor for the next page."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "results": [
                        {
                          "id": "1942939879222220800",
                          "text": "Just tried the new GPT-4o vision features on the OpenAI playground — it correctly described a screenshot of our dashboard in one prompt. Incredible.",
                          "author": {
                            "handle": "devuser",
                            "displayName": "Dev User",
                            "isVerified": false
                          },
                          "createdAt": "2026-07-01T18:42:00.000Z",
                          "likeCount": 142,
                          "replyCount": 23,
                          "retweetCount": 31,
                          "viewCount": 8200,
                          "url": "https://x.com/devuser/status/1942939879222220800"
                        },
                        {
                          "id": "1942939879222220801",
                          "text": "OpenAI just dropped a new fine-tuning API endpoint. Docs are live at platform.openai.com",
                          "author": {
                            "handle": "aibuilder",
                            "displayName": "AI Builder",
                            "isVerified": true
                          },
                          "createdAt": "2026-07-01T18:30:00.000Z",
                          "likeCount": 891,
                          "replyCount": 156,
                          "retweetCount": 210,
                          "viewCount": 51000,
                          "url": "https://x.com/aibuilder/status/1942939879222220801"
                        }
                      ],
                      "cursor": "DAABCgABF8zK9v__-V8"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}