{
  "openapi": "3.0.3",
  "info": {
    "title": "Firecrawl API",
    "description": "API for crawling websites and extracting data with Firecrawl.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.firecrawl.dev/v1"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/crawl": {
      "post": {
        "summary": "Submit a crawl job",
        "description": "Submits a job to crawl a URL and all accessible subpages.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL to crawl."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Limit the number of pages to crawl."
                  },
                  "excludePaths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of paths to exclude from the crawl."
                  },
                  "allowBackwardLinks": {
                    "type": "boolean",
                    "description": "Allow crawling pages that are not direct descendants of the initial URL."
                  },
                  "webhook": {
                    "type": "string",
                    "description": "URL to send webhook events during the crawl process."
                  },
                  "scrapeOptions": {
                    "type": "object",
                    "description": "Scraping options",
                    "properties": {
                      "formats": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "markdown",
                            "html",
                            "extract"
                          ]
                        },
                        "description": "Output format(s) for the scraped data."
                      },
                      "extract": {
                        "type": "object",
                        "properties": {
                          "schema": {
                            "type": "string",
                            "description": "The schema for structured data extraction."
                          },
                          "systemPrompt": {
                            "type": "string",
                            "description": "The system prompt used for extraction."
                          },
                          "prompt": {
                            "type": "string",
                            "description": "Extraction prompt without schema."
                          }
                        }
                      }
                    }
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Crawl job submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "description": "The ID of the submitted crawl job."
                    },
                    "url": {
                      "type": "string",
                      "description": "API endpoint to check the status of the crawl job."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request, invalid parameters."
          },
          "401": {
            "description": "Unauthorized, invalid API key."
          }
        }
      }
    },
    "/crawl/{crawl_id}": {
      "get": {
        "summary": "Check Crawl Job Status",
        "description": "Check the status of a crawl job by its ID and retrieve the result.",
        "parameters": [
          {
            "name": "crawl_id",
            "in": "path",
            "required": true,
            "description": "The ID of the crawl job.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Crawl status retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "The current status of the crawl (e.g., scraping, completed)."
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of pages identified for crawling."
                    },
                    "completed": {
                      "type": "integer",
                      "description": "Number of pages crawled so far."
                    },
                    "creditsUsed": {
                      "type": "integer",
                      "description": "Credits used for this crawl."
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Expiry date for the crawl result."
                    },
                    "next": {
                      "type": "string",
                      "description": "URL to retrieve the next portion of crawl data if the response is large."
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "markdown": {
                            "type": "string"
                          },
                          "html": {
                            "type": "string"
                          },
                          "metadata": {
                            "type": "object",
                            "properties": {
                              "title": {
                                "type": "string"
                              },
                              "language": {
                                "type": "string"
                              },
                              "sourceURL": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "ogLocaleAlternate": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "statusCode": {
                                "type": "integer",
                                "description": "HTTP status code of the crawled page."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request."
          },
          "404": {
            "description": "Crawl job not found."
          }
        }
      }
    },
    "/crawl/websocket": {
      "post": {
        "summary": "Crawl URL with WebSocket Monitoring",
        "description": "Initiate a crawl and monitor progress in real-time using WebSocket.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL to crawl."
                  },
                  "excludePaths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of paths to exclude from the crawl."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Limit the number of pages to crawl."
                  },
                  "scrapeOptions": {
                    "type": "object",
                    "description": "Scraping options",
                    "properties": {
                      "formats": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "markdown",
                            "html",
                            "extract"
                          ]
                        },
                        "description": "Output format(s) for the scraped data."
                      },
                      "extract": {
                        "type": "object",
                        "properties": {
                          "schema": {
                            "type": "string",
                            "description": "The schema for structured data extraction."
                          },
                          "systemPrompt": {
                            "type": "string",
                            "description": "The system prompt used for extraction."
                          },
                          "prompt": {
                            "type": "string",
                            "description": "Extraction prompt without schema."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "WebSocket connection initiated successfully."
          },
          "400": {
            "description": "Bad request, invalid parameters."
          }
        }
      }
    },
    "/crawl/webhook": {
      "post": {
        "summary": "Submit a crawl job with a webhook",
        "description": "Submits a job to crawl a URL and sends webhook events during the crawl process.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL to crawl."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "Limit the number of pages to crawl."
                  },
                  "webhook": {
                    "type": "string",
                    "description": "URL to send webhook events to."
                  },
                  "excludePaths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of paths to exclude from the crawl."
                  },
                  "scrapeOptions": {
                    "type": "object",
                    "description": "Scraping options",
                    "properties": {
                      "formats": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "markdown",
                            "html",
                            "extract"
                          ]
                        },
                        "description": "Output format(s) for the scraped data."
                      },
                      "extract": {
                        "type": "object",
                        "properties": {
                          "schema": {
                            "type": "string",
                            "description": "The schema for structured data extraction."
                          },
                          "systemPrompt": {
                            "type": "string",
                            "description": "The system prompt used for extraction."
                          },
                          "prompt": {
                            "type": "string",
                            "description": "Extraction prompt without schema."
                          }
                        }
                      }
                    }
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Crawl job with webhook submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "description": "The ID of the crawl job."
                    },
                    "webhook": {
                      "type": "string",
                      "description": "Webhook URL used during the crawl process."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request, invalid parameters."
          },
          "401": {
            "description": "Unauthorized, invalid API key."
          }
        }
      }
    },
    "/scrape": {
      "post": {
        "summary": "Scrape a URL and get its content.",
        "description": "Scrape a given URL to retrieve content in markdown, HTML, or other formats. This endpoint supports structured data extraction and dynamic actions.\n",
        "operationId": "scrapeUrl",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL to scrape."
                  },
                  "formats": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "markdown",
                        "html",
                        "extract"
                      ]
                    },
                    "description": "Output format(s) for the scraped data."
                  },
                  "extract": {
                    "type": "object",
                    "properties": {
                      "schema": {
                        "type": "string",
                        "description": "The schema for structured data extraction."
                      },
                      "systemPrompt": {
                        "type": "string",
                        "description": "The system prompt used for extraction."
                      },
                      "prompt": {
                        "type": "string",
                        "description": "Extraction prompt without schema."
                      }
                    }
                  },
                  "actions": {
                    "type": "array",
                    "description": "List of actions to interact with dynamic content before scraping.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "wait",
                            "click",
                            "write",
                            "press",
                            "screenshot"
                          ]
                        },
                        "selector": {
                          "type": "string",
                          "description": "The CSS selector for `click` and `write` actions."
                        },
                        "milliseconds": {
                          "type": "integer",
                          "description": "Milliseconds to wait for `wait` action."
                        },
                        "text": {
                          "type": "string",
                          "description": "Text for `write` action."
                        },
                        "key": {
                          "type": "string",
                          "description": "Key for `press` action."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scraping successful.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "markdown": {
                          "type": "string",
                          "description": "Scraped content in markdown format."
                        },
                        "html": {
                          "type": "string",
                          "description": "Scraped content in HTML format."
                        },
                        "extract": {
                          "type": "object",
                          "description": "Extracted structured data."
                        },
                        "actions": {
                          "type": "object",
                          "properties": {
                            "screenshots": {
                              "type": "array",
                              "items": {
                                "type": "string",
                                "description": "Screenshot URLs."
                              }
                            }
                          }
                        },
                        "metadata": {
                          "type": "object",
                          "properties": {
                            "title": {
                              "type": "string"
                            },
                            "description": {
                              "type": "string"
                            },
                            "language": {
                              "type": "string"
                            },
                            "keywords": {
                              "type": "string"
                            },
                            "robots": {
                              "type": "string"
                            },
                            "ogTitle": {
                              "type": "string"
                            },
                            "ogDescription": {
                              "type": "string"
                            },
                            "ogUrl": {
                              "type": "string"
                            },
                            "ogImage": {
                              "type": "string"
                            },
                            "sourceURL": {
                              "type": "string"
                            },
                            "statusCode": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or URL."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/map": {
      "post": {
        "summary": "Map a website and get URLs",
        "description": "Map a URL and retrieve most links present on the website. Optionally, use the `search` parameter to filter URLs by a specific keyword.",
        "operationId": "mapUrl",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The URL of the website to map.",
                    "example": "https://firecrawl.dev"
                  },
                  "search": {
                    "type": "string",
                    "description": "Search term to filter specific URLs.",
                    "example": "docs"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A successful response containing the list of URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "links": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "https://firecrawl.dev",
                        "https://www.firecrawl.dev/pricing",
                        "https://www.firecrawl.dev/blog"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request due to invalid input."
          },
          "401": {
            "description": "Unauthorized request. The API key is missing or invalid."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "ExtractSchema": {
        "type": "object",
        "properties": {
          "company_mission": {
            "type": "string"
          },
          "supports_sso": {
            "type": "boolean"
          },
          "is_open_source": {
            "type": "boolean"
          },
          "is_in_yc": {
            "type": "boolean"
          }
        }
      }
    }
  }
}