Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat(.net-sdk): add .NET SDK for Firecrawl v2 API

firecrawl-spring[bot]f705a1e4efea
diff --git a/.github/scripts/check_version_has_incremented.py b/.github/scripts/check_version_has_incremented.py
index 34c56d838..2dea3b3bc 100644
--- a/.github/scripts/check_version_has_incremented.py
+++ b/.github/scripts/check_version_has_incremented.py
@@ -18,6 +18,11 @@ Local version: 1.0.0
Published version: 0.0.0 (0.0.0 means not yet published on Maven Central)
true
+python .github/scripts/check_version_has_incremented.py dotnet ./apps/.net-sdk/Firecrawl firecrawl-dotnet
+Local version: 1.0.0
+Published version: 0.0.0 (0.0.0 means not yet published on NuGet)
+true
+
"""
import json
import os
@@ -82,6 +87,26 @@ def get_maven_central_version(package_name: str) -> str:
return version_match.group(1).strip()
return "0.0.0"
+def get_csproj_version(file_path: str) -> str:
+ """Extract version string from .csproj file."""
+ csproj_file = Path(file_path).read_text()
+ version_match = re.search(r'<Version>(.*?)</Version>', csproj_file)
+ if version_match:
+ return version_match.group(1).strip()
+ raise RuntimeError("Unable to find version string in .csproj file.")
+
+def get_nuget_version(package_name: str) -> str:
+ """Get latest version of .NET package from NuGet."""
+ url = f"https://api.nuget.org/v3-flatcontainer/{package_name.lower()}/index.json"
+ response = requests.get(url)
+ if response.status_code == 404:
+ return "0.0.0"
+ response.raise_for_status()
+ versions = response.json().get('versions', [])
+ if versions:
+ return versions[-1].strip()
+ return "0.0.0"
+
# def get_rust_version(file_path: str) -> str:
# """Extract version string from Cargo.toml."""
# cargo_toml = toml.load(file_path)
@@ -121,6 +146,14 @@ if __name__ == "__main__":
current_version = get_gradle_version(os.path.join(package_path, 'build.gradle.kts'))
# Get published version from Maven Central
published_version = get_maven_central_version(package_name)
+ elif package_type == "dotnet":
+ # Get current version from .csproj file — look for any .csproj in the directory
+ csproj_files = list(Path(package_path).glob('*.csproj'))
+ if not csproj_files:
+ raise RuntimeError(f"No .csproj file found in {package_path}")
+ current_version = get_csproj_version(str(csproj_files[0]))
+ # Get published version from NuGet
+ published_version = get_nuget_version(package_name)
# if package_type == "rust":
# # Get current version from Cargo.toml
# current_version = get_rust_version(os.path.join(package_path, 'Cargo.toml'))
@@ -128,7 +161,7 @@ if __name__ == "__main__":
# published_version = get_crates_version(package_name)
else:
- raise ValueError("Invalid package type. Use 'python', 'js', or 'java'.")
+ raise ValueError("Invalid package type. Use 'python', 'js', 'java', or 'dotnet'.")
# Print versions for debugging
# print(f"Local version: {current_version}")
diff --git a/.github/workflows/publish-dotnet-sdk.yml b/.github/workflows/publish-dotnet-sdk.yml
new file mode 100644
index 000000000..33c049676
--- /dev/null
+++ b/.github/workflows/publish-dotnet-sdk.yml
@@ -0,0 +1,59 @@
+name: Publish .NET SDK
+
+on:
+ workflow_dispatch:
+ push:
+ branches:
+ - main
+ paths:
+ - 'apps/.net-sdk/**'
+
+jobs:
+ publish:
+ name: Publish to NuGet
+ runs-on: blacksmith-2vcpu-ubuntu-2404
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v5
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.x'
+
+ - name: Install version check dependencies
+ run: pip install requests packaging
+
+ - name: Run version check script
+ id: version_check
+ run: |
+ VERSION_INCREMENTED=$(python .github/scripts/check_version_has_incremented.py dotnet ./apps/.net-sdk/Firecrawl firecrawl-dotnet)
+ echo "VERSION_INCREMENTED=$VERSION_INCREMENTED" >> $GITHUB_ENV
+
+ - name: Set up .NET 8
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ uses: actions/setup-dotnet@v4
+ with:
+ dotnet-version: '8.0.x'
+
+ - name: Restore dependencies
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ working-directory: ./apps/.net-sdk
+ run: dotnet restore
+
+ - name: Build
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ working-directory: ./apps/.net-sdk
+ run: dotnet build --no-restore --configuration Release
+
+ - name: Pack
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ working-directory: ./apps/.net-sdk/Firecrawl
+ run: dotnet pack --no-build --configuration Release --output ../nupkgs
+
+ - name: Publish to NuGet
+ if: ${{ env.VERSION_INCREMENTED == 'true' }}
+ working-directory: ./apps/.net-sdk
+ env:
+ NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
+ run: dotnet nuget push ./nupkgs/*.nupkg --api-key $NUGET_API_KEY --source https://api.nuget.org/v3/index.json --skip-duplicate
diff --git a/.github/workflows/test-dotnet-sdk.yml b/.github/workflows/test-dotnet-sdk.yml
new file mode 100644
index 000000000..646bff0e3
--- /dev/null
+++ b/.github/workflows/test-dotnet-sdk.yml
@@ -0,0 +1,52 @@
+name: .NET SDK Test Suite
+
+on:
+ pull_request:
+ branches:
+ - main
+ paths:
+ - apps/.net-sdk/**
+ - .github/workflows/test-dotnet-sdk.yml
+ push:
+ branches:
+ - main
+ paths:
+ - apps/.net-sdk/**
+ workflow_dispatch:
+
+jobs:
+ build-and-test:
+ name: Build and Test
+ runs-on: blacksmith-4vcpu-ubuntu-2404
+ if: >-
+ github.event_name == 'workflow_dispatch' ||
+ github.event_name == 'pull_request' ||
+ (github.event_name == 'push' && github.ref == 'refs/heads/main')
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up .NET 8
+ uses: actions/setup-dotnet@v4
+ with:
+ dotnet-version: "8.0.x"
+
+ - name: Restore dependencies
+ working-directory: ./apps/.net-sdk
+ run: dotnet restore
+
+ - name: Build
+ working-directory: ./apps/.net-sdk
+ run: dotnet build --no-restore --configuration Release
+
+ - name: Run unit tests
+ working-directory: ./apps/.net-sdk
+ run: dotnet test --no-build --configuration Release --logger "trx;LogFileName=test-results.trx" --results-directory ./TestResults
+
+ - name: Publish test report
+ if: always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false)
+ uses: dorny/test-reporter@3eeb9fc888e82e8be2fb356bbeec2750231672bc # v1
+ with:
+ name: .NET SDK Test Report
+ path: apps/.net-sdk/TestResults/**/*.trx
+ reporter: dotnet-trx
+ fail-on-error: true
diff --git a/apps/.net-sdk/Firecrawl.Tests/ExceptionsTests.cs b/apps/.net-sdk/Firecrawl.Tests/ExceptionsTests.cs
new file mode 100644
index 000000000..2d6280aac
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl.Tests/ExceptionsTests.cs
@@ -0,0 +1,70 @@
+using Firecrawl.Exceptions;
+using Xunit;
+
+namespace Firecrawl.Tests;
+
+public class ExceptionsTests
+{
+ [Fact]
+ public void FirecrawlException_HasMessage()
+ {
+ var ex = new FirecrawlException("test error");
+ Assert.Equal("test error", ex.Message);
+ }
+
+ [Fact]
+ public void FirecrawlException_HasStatusCode()
+ {
+ var ex = new FirecrawlException("test error", 500);
+ Assert.Equal(500, ex.StatusCode);
+ }
+
+ [Fact]
+ public void FirecrawlException_HasErrorCode()
+ {
+ var ex = new FirecrawlException("test error", 400, "INVALID_REQUEST", null);
+ Assert.Equal(400, ex.StatusCode);
+ Assert.Equal("INVALID_REQUEST", ex.ErrorCode);
+ }
+
+ [Fact]
+ public void FirecrawlException_HasInnerException()
+ {
+ var inner = new InvalidOperationException("inner");
+ var ex = new FirecrawlException("wrapper", inner);
+ Assert.Equal("wrapper", ex.Message);
+ Assert.Same(inner, ex.InnerException);
+ }
+
+ [Fact]
+ public void AuthenticationException_Has401StatusCode()
+ {
+ var ex = new AuthenticationException("Unauthorized");
+ Assert.Equal(401, ex.StatusCode);
+ }
+
+ [Fact]
+ public void AuthenticationException_HasErrorCode()
+ {
+ var ex = new AuthenticationException("Unauthorized", "AUTH_FAILED");
+ Assert.Equal("AUTH_FAILED", ex.ErrorCode);
+ }
+
+ [Fact]
+ public void RateLimitException_Has429StatusCode()
+ {
+ var ex = new RateLimitException("Too many requests");
+ Assert.Equal(429, ex.StatusCode);
+ }
+
+ [Fact]
+ public void JobTimeoutException_HasJobIdAndTimeout()
+ {
+ var ex = new JobTimeoutException("job-123", 300, "Crawl");
+ Assert.Equal("job-123", ex.JobId);
+ Assert.Equal(300, ex.TimeoutSeconds);
+ Assert.Contains("job-123", ex.Message);
+ Assert.Contains("300", ex.Message);
+ Assert.Contains("Crawl", ex.Message);
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl.Tests/Firecrawl.Tests.csproj b/apps/.net-sdk/Firecrawl.Tests/Firecrawl.Tests.csproj
new file mode 100644
index 000000000..f10f4c433
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl.Tests/Firecrawl.Tests.csproj
@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+ <PropertyGroup>
+ <TargetFramework>net8.0</TargetFramework>
+ <ImplicitUsings>enable</ImplicitUsings>
+ <Nullable>enable</Nullable>
+ <IsPackable>false</IsPackable>
+ </PropertyGroup>
+
+ <ItemGroup>
+ <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
+ <PackageReference Include="xunit" Version="2.9.3" />
+ <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2">
+ <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+ <PrivateAssets>all</PrivateAssets>
+ </PackageReference>
+ </ItemGroup>
+
+ <ItemGroup>
+ <ProjectReference Include="..\Firecrawl\Firecrawl.csproj" />
+ </ItemGroup>
+
+</Project>
diff --git a/apps/.net-sdk/Firecrawl.Tests/FirecrawlClientTests.cs b/apps/.net-sdk/Firecrawl.Tests/FirecrawlClientTests.cs
new file mode 100644
index 000000000..d3c1ad26f
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl.Tests/FirecrawlClientTests.cs
@@ -0,0 +1,132 @@
+using Firecrawl.Exceptions;
+using Firecrawl.Models;
+using Xunit;
+
+namespace Firecrawl.Tests;
+
+public class FirecrawlClientTests
+{
+ [Fact]
+ public void Constructor_RequiresApiKey()
+ {
+ // Clear env variable in case it's set
+ Environment.SetEnvironmentVariable("FIRECRAWL_API_KEY", null);
+
+ var ex = Assert.Throws<FirecrawlException>(() => new FirecrawlClient(apiKey: ""));
+ Assert.Contains("API key is required", ex.Message);
+ }
+
+ [Fact]
+ public void Constructor_RequiresApiKey_WhenNull()
+ {
+ Environment.SetEnvironmentVariable("FIRECRAWL_API_KEY", null);
+
+ var ex = Assert.Throws<FirecrawlException>(() => new FirecrawlClient(apiKey: null));
+ Assert.Contains("API key is required", ex.Message);
+ }
+
+ [Fact]
+ public void Constructor_AcceptsApiKey()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+ Assert.NotNull(client);
+ }
+
+ [Fact]
+ public void Constructor_AcceptsCustomHttpClient()
+ {
+ var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
+
+ var client = new FirecrawlClient(
+ apiKey: "fc-test-key",
+ httpClient: httpClient);
+ Assert.NotNull(client);
+ }
+
+ [Fact]
+ public void Constructor_AcceptsCustomApiUrl()
+ {
+ var client = new FirecrawlClient(
+ apiKey: "fc-test-key",
+ apiUrl: "https://custom-api.firecrawl.dev");
+ Assert.NotNull(client);
+ }
+
+ [Fact]
+ public void Constructor_ReadsFromEnvironmentVariable()
+ {
+ Environment.SetEnvironmentVariable("FIRECRAWL_API_KEY", "fc-env-key");
+ try
+ {
+ var client = new FirecrawlClient();
+ Assert.NotNull(client);
+ }
+ finally
+ {
+ Environment.SetEnvironmentVariable("FIRECRAWL_API_KEY", null);
+ }
+ }
+
+ [Fact]
+ public async Task ScrapeAsync_RequiresUrl()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+
+ await Assert.ThrowsAsync<ArgumentNullException>(
+ () => client.ScrapeAsync(null!));
+ }
+
+ [Fact]
+ public async Task StartCrawlAsync_RequiresUrl()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+
+ await Assert.ThrowsAsync<ArgumentNullException>(
+ () => client.StartCrawlAsync(null!));
+ }
+
+ [Fact]
+ public async Task MapAsync_RequiresUrl()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+
+ await Assert.ThrowsAsync<ArgumentNullException>(
+ () => client.MapAsync(null!));
+ }
+
+ [Fact]
+ public async Task SearchAsync_RequiresQuery()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+
+ await Assert.ThrowsAsync<ArgumentNullException>(
+ () => client.SearchAsync(null!));
+ }
+
+ [Fact]
+ public async Task StartBatchScrapeAsync_RequiresUrls()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+
+ await Assert.ThrowsAsync<ArgumentNullException>(
+ () => client.StartBatchScrapeAsync(null!));
+ }
+
+ [Fact]
+ public async Task CancelCrawlAsync_RequiresJobId()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+
+ await Assert.ThrowsAsync<ArgumentNullException>(
+ () => client.CancelCrawlAsync(null!));
+ }
+
+ [Fact]
+ public async Task GetCrawlStatusAsync_RequiresJobId()
+ {
+ var client = new FirecrawlClient(apiKey: "fc-test-key");
+
+ await Assert.ThrowsAsync<ArgumentNullException>(
+ () => client.GetCrawlStatusAsync(null!));
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl.Tests/ModelsTests.cs b/apps/.net-sdk/Firecrawl.Tests/ModelsTests.cs
new file mode 100644
index 000000000..a51ee10dd
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl.Tests/ModelsTests.cs
@@ -0,0 +1,307 @@
+using System.Text.Json;
+using Firecrawl.Models;
+using Xunit;
+
+namespace Firecrawl.Tests;
+
+public class ModelsTests
+{
+ private static readonly JsonSerializerOptions JsonOptions = FirecrawlHttpClient.JsonOptions;
+
+ [Fact]
+ public void ScrapeOptions_SerializesCorrectly()
+ {
+ var options = new ScrapeOptions
+ {
+ Formats = new List<object> { "markdown", "html" },
+ OnlyMainContent = true,
+ Timeout = 30000,
+ Mobile = false
+ };
+
+ var json = JsonSerializer.Serialize(options, JsonOptions);
+ Assert.Contains("\"formats\"", json);
+ Assert.Contains("\"markdown\"", json);
+ Assert.Contains("\"html\"", json);
+ Assert.Contains("\"onlyMainContent\":true", json);
+ Assert.Contains("\"timeout\":30000", json);
+ Assert.Contains("\"mobile\":false", json);
+ }
+
+ [Fact]
+ public void ScrapeOptions_OmitsNullProperties()
+ {
+ var options = new ScrapeOptions
+ {
+ Formats = new List<object> { "markdown" }
+ };
+
+ var json = JsonSerializer.Serialize(options, JsonOptions);
+ Assert.Contains("\"formats\"", json);
+ Assert.DoesNotContain("\"timeout\"", json);
+ Assert.DoesNotContain("\"mobile\"", json);
+ Assert.DoesNotContain("\"headers\"", json);
+ }
+
+ [Fact]
+ public void CrawlOptions_SerializesCorrectly()
+ {
+ var options = new CrawlOptions
+ {
+ Limit = 100,
+ MaxDiscoveryDepth = 3,
+ Sitemap = "include",
+ ExcludePaths = new List<string> { "/admin/*" }
+ };
+
+ var json = JsonSerializer.Serialize(options, JsonOptions);
+ Assert.Contains("\"limit\":100", json);
+ Assert.Contains("\"maxDiscoveryDepth\":3", json);
+ Assert.Contains("\"sitemap\":\"include\"", json);
+ Assert.Contains("\"/admin/*\"", json);
+ }
+
+ [Fact]
+ public void MapOptions_SerializesCorrectly()
+ {
+ var options = new MapOptions
+ {
+ Search = "pricing",
+ Limit = 10,
+ IncludeSubdomains = true
+ };
+
+ var json = JsonSerializer.Serialize(options, JsonOptions);
+ Assert.Contains("\"search\":\"pricing\"", json);
+ Assert.Contains("\"limit\":10", json);
+ Assert.Contains("\"includeSubdomains\":true", json);
+ }
+
+ [Fact]
+ public void SearchOptions_SerializesCorrectly()
+ {
+ var options = new SearchOptions
+ {
+ Limit = 5,
+ Location = "US",
+ Tbs = "qdr:w"
+ };
+
+ var json = JsonSerializer.Serialize(options, JsonOptions);
+ Assert.Contains("\"limit\":5", json);
+ Assert.Contains("\"location\":\"US\"", json);
+ Assert.Contains("\"tbs\":\"qdr:w\"", json);
+ }
+
+ [Fact]
+ public void BatchScrapeOptions_IdempotencyKey_NotSerialized()
+ {
+ var options = new BatchScrapeOptions
+ {
+ IdempotencyKey = "my-key-123",
+ IgnoreInvalidURLs = true
+ };
+
+ var json = JsonSerializer.Serialize(options, JsonOptions);
+ Assert.DoesNotContain("idempotencyKey", json);
+ Assert.DoesNotContain("my-key-123", json);
+ Assert.Contains("\"ignoreInvalidURLs\":true", json);
+ }
+
+ [Fact]
+ public void Document_DeserializesCorrectly()
+ {
+ var json = """
+ {
+ "markdown": "# Hello World",
+ "html": "<h1>Hello World</h1>",
+ "metadata": {
+ "title": "Test",
+ "sourceURL": "https://example.com"
+ },
+ "warning": null
+ }
+ """;
+
+ var doc = JsonSerializer.Deserialize<Document>(json, JsonOptions);
+ Assert.NotNull(doc);
+ Assert.Equal("# Hello World", doc.Markdown);
+ Assert.Equal("<h1>Hello World</h1>", doc.Html);
+ Assert.NotNull(doc.Metadata);
+ Assert.Null(doc.Warning);
+ }
+
+ [Fact]
+ public void Document_IgnoresUnknownProperties()
+ {
+ var json = """
+ {
+ "markdown": "# Test",
+ "futureField": "should be ignored",
+ "anotherNewField": 42
+ }
+ """;
+
+ var doc = JsonSerializer.Deserialize<Document>(json, JsonOptions);
+ Assert.NotNull(doc);
+ Assert.Equal("# Test", doc.Markdown);
+ }
+
+ [Fact]
+ public void CrawlJob_IsDone_Completed()
+ {
+ var job = new CrawlJob { Status = "completed" };
+ Assert.True(job.IsDone);
+ }
+
+ [Fact]
+ public void CrawlJob_IsDone_Failed()
+ {
+ var job = new CrawlJob { Status = "failed" };
+ Assert.True(job.IsDone);
+ }
+
+ [Fact]
+ public void CrawlJob_IsDone_Cancelled()
+ {
+ var job = new CrawlJob { Status = "cancelled" };
+ Assert.True(job.IsDone);
+ }
+
+ [Fact]
+ public void CrawlJob_NotDone_Scraping()
+ {
+ var job = new CrawlJob { Status = "scraping" };
+ Assert.False(job.IsDone);
+ }
+
+ [Fact]
+ public void BatchScrapeJob_IsDone_Completed()
+ {
+ var job = new BatchScrapeJob { Status = "completed" };
+ Assert.True(job.IsDone);
+ }
+
+ [Fact]
+ public void BatchScrapeJob_NotDone_Scraping()
+ {
+ var job = new BatchScrapeJob { Status = "scraping" };
+ Assert.False(job.IsDone);
+ }
+
+ [Fact]
+ public void CrawlJob_DeserializesCorrectly()
+ {
+ var json = """
+ {
+ "id": "crawl-123",
+ "status": "completed",
+ "completed": 5,
+ "total": 5,
+ "creditsUsed": 5,
+ "data": [
+ { "markdown": "# Page 1" },
+ { "markdown": "# Page 2" }
+ ],
+ "next": null
+ }
+ """;
+
+ var job = JsonSerializer.Deserialize<CrawlJob>(json, JsonOptions);
+ Assert.NotNull(job);
+ Assert.Equal("crawl-123", job.Id);
+ Assert.Equal("completed", job.Status);
+ Assert.Equal(5, job.Completed);
+ Assert.Equal(5, job.Total);
+ Assert.True(job.IsDone);
+ Assert.NotNull(job.Data);
+ Assert.Equal(2, job.Data.Count);
+ }
+
+ [Fact]
+ public void JsonFormat_HasCorrectType()
+ {
+ var format = new JsonFormat
+ {
+ Prompt = "Extract the main content",
+ Schema = new Dictionary<string, object>
+ {
+ ["type"] = "object",
+ ["properties"] = new Dictionary<string, object>
+ {
+ ["title"] = new Dictionary<string, object> { ["type"] = "string" }
+ }
+ }
+ };
+
+ var json = JsonSerializer.Serialize(format, JsonOptions);
+ Assert.Contains("\"type\":\"json\"", json);
+ Assert.Contains("\"prompt\"", json);
+ Assert.Contains("\"schema\"", json);
+ }
+
+ [Fact]
+ public void WebhookConfig_SerializesCorrectly()
+ {
+ var config = new WebhookConfig
+ {
+ Url = "https://example.com/webhook",
+ Events = new List<string> { "completed", "failed" }
+ };
+
+ var json = JsonSerializer.Serialize(config, JsonOptions);
+ Assert.Contains("\"url\":\"https://example.com/webhook\"", json);
+ Assert.Contains("\"completed\"", json);
+ Assert.Contains("\"failed\"", json);
+ }
+
+ [Fact]
+ public void LocationConfig_SerializesCorrectly()
+ {
+ var config = new LocationConfig
+ {
+ Country = "US",
+ Languages = new List<string> { "en" }
+ };
+
+ var json = JsonSerializer.Serialize(config, JsonOptions);
+ Assert.Contains("\"country\":\"US\"", json);
+ Assert.Contains("\"en\"", json);
+ }
+
+ [Fact]
+ public void CrawlResponse_DeserializesCorrectly()
+ {
+ var json = """
+ {
+ "success": true,
+ "id": "crawl-abc",
+ "url": "https://api.firecrawl.dev/v2/crawl/crawl-abc"
+ }
+ """;
+
+ var response = JsonSerializer.Deserialize<CrawlResponse>(json, JsonOptions);
+ Assert.NotNull(response);
+ Assert.True(response.Success);
+ Assert.Equal("crawl-abc", response.Id);
+ }
+
+ [Fact]
+ public void BatchScrapeResponse_DeserializesCorrectly()
+ {
+ var json = """
+ {
+ "success": true,
+ "id": "batch-abc",
+ "invalidURLs": ["not-a-url"]
+ }
+ """;
+
+ var response = JsonSerializer.Deserialize<BatchScrapeResponse>(json, JsonOptions);
+ Assert.NotNull(response);
+ Assert.True(response.Success);
+ Assert.Equal("batch-abc", response.Id);
+ Assert.NotNull(response.InvalidURLs);
+ Assert.Single(response.InvalidURLs);
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl.sln b/apps/.net-sdk/Firecrawl.sln
new file mode 100644
index 000000000..650375c4d
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl.sln
@@ -0,0 +1,25 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Firecrawl", "Firecrawl\Firecrawl.csproj", "{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Firecrawl.Tests", "Firecrawl.Tests\Firecrawl.Tests.csproj", "{B2C3D4E5-F6A7-8901-BCDE-F12345678901}"
+EndProject
+Global
+ GlobalSection(SolutionConfigurationPlatforms) = preSolution
+ Debug|Any CPU = Debug|Any CPU
+ Release|Any CPU = Release|Any CPU
+ EndGlobalSection
+ GlobalSection(ProjectConfigurationPlatforms) = postSolution
+ {A1B2C3D4-E5F6-7890-ABCD-EF1234567890}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+ {A1B2C3D4-E5F6-7890-ABCD-EF1234567890}.Debug|Any CPU.Build.0 = Debug|Any CPU
+ {A1B2C3D4-E5F6-7890-ABCD-EF1234567890}.Release|Any CPU.ActiveCfg = Release|Any CPU
+ {A1B2C3D4-E5F6-7890-ABCD-EF1234567890}.Release|Any CPU.Build.0 = Release|Any CPU
+ {B2C3D4E5-F6A7-8901-BCDE-F12345678901}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+ {B2C3D4E5-F6A7-8901-BCDE-F12345678901}.Debug|Any CPU.Build.0 = Debug|Any CPU
+ {B2C3D4E5-F6A7-8901-BCDE-F12345678901}.Release|Any CPU.ActiveCfg = Release|Any CPU
+ {B2C3D4E5-F6A7-8901-BCDE-F12345678901}.Release|Any CPU.Build.0 = Release|Any CPU
+ EndGlobalSection
+EndGlobal
diff --git a/apps/.net-sdk/Firecrawl/Exceptions/AuthenticationException.cs b/apps/.net-sdk/Firecrawl/Exceptions/AuthenticationException.cs
new file mode 100644
index 000000000..497b9c249
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Exceptions/AuthenticationException.cs
@@ -0,0 +1,12 @@
+namespace Firecrawl.Exceptions;
+
+/// <summary>
+/// Thrown when the API returns a 401 Unauthorized response.
+/// </summary>
+public class AuthenticationException : FirecrawlException
+{
+ public AuthenticationException(string message, string? errorCode = null, object? details = null)
+ : base(message, 401, errorCode, details)
+ {
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl/Exceptions/FirecrawlException.cs b/apps/.net-sdk/Firecrawl/Exceptions/FirecrawlException.cs
new file mode 100644
index 000000000..a81b8238b
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Exceptions/FirecrawlException.cs
@@ -0,0 +1,46 @@
+namespace Firecrawl.Exceptions;
+
+/// <summary>
+/// Base exception for all Firecrawl SDK errors.
+/// </summary>
+public class FirecrawlException : Exception
+{
+ /// <summary>
+ /// HTTP status code (0 if not an HTTP error).
+ /// </summary>
+ public int StatusCode { get; }
+
+ /// <summary>
+ /// Error code returned by the API, if any.
+ /// </summary>
+ public string? ErrorCode { get; }
+
+ /// <summary>
+ /// Additional error details from the API response.
+ /// </summary>
+ public object? Details { get; }
+
+ public FirecrawlException(string message)
+ : base(message)
+ {
+ }
+
+ public FirecrawlException(string message, int statusCode)
+ : base(message)
+ {
+ StatusCode = statusCode;
+ }
+
+ public FirecrawlException(string message, int statusCode, string? errorCode, object? details)
+ : base(message)
+ {
+ StatusCode = statusCode;
+ ErrorCode = errorCode;
+ Details = details;
+ }
+
+ public FirecrawlException(string message, Exception innerException)
+ : base(message, innerException)
+ {
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl/Exceptions/JobTimeoutException.cs b/apps/.net-sdk/Firecrawl/Exceptions/JobTimeoutException.cs
new file mode 100644
index 000000000..64773ec21
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Exceptions/JobTimeoutException.cs
@@ -0,0 +1,24 @@
+namespace Firecrawl.Exceptions;
+
+/// <summary>
+/// Thrown when an async job (crawl, batch scrape, agent) does not complete within the specified timeout.
+/// </summary>
+public class JobTimeoutException : FirecrawlException
+{
+ /// <summary>
+ /// The ID of the job that timed out.
+ /// </summary>
+ public string JobId { get; }
+
+ /// <summary>
+ /// The timeout in seconds that was exceeded.
+ /// </summary>
+ public int TimeoutSeconds { get; }
+
+ public JobTimeoutException(string jobId, int timeoutSeconds, string jobType)
+ : base($"{jobType} job {jobId} did not complete within {timeoutSeconds} seconds")
+ {
+ JobId = jobId;
+ TimeoutSeconds = timeoutSeconds;
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl/Exceptions/RateLimitException.cs b/apps/.net-sdk/Firecrawl/Exceptions/RateLimitException.cs
new file mode 100644
index 000000000..2a0b99b4e
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Exceptions/RateLimitException.cs
@@ -0,0 +1,12 @@
+namespace Firecrawl.Exceptions;
+
+/// <summary>
+/// Thrown when the API returns a 429 Too Many Requests response.
+/// </summary>
+public class RateLimitException : FirecrawlException
+{
+ public RateLimitException(string message, string? errorCode = null, object? details = null)
+ : base(message, 429, errorCode, details)
+ {
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl/Firecrawl.csproj b/apps/.net-sdk/Firecrawl/Firecrawl.csproj
new file mode 100644
index 000000000..4d7f2ea8b
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Firecrawl.csproj
@@ -0,0 +1,31 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+ <PropertyGroup>
+ <TargetFramework>net8.0</TargetFramework>
+ <ImplicitUsings>enable</ImplicitUsings>
+ <Nullable>enable</Nullable>
+ <RootNamespace>Firecrawl</RootNamespace>
+
+ <!-- NuGet package metadata -->
+ <PackageId>firecrawl-dotnet</PackageId>
+ <Version>1.0.0</Version>
+ <Authors>Firecrawl</Authors>
+ <Company>Firecrawl</Company>
+ <Description>.NET SDK for the Firecrawl API - web scraping, crawling, and data extraction</Description>
+ <PackageLicenseExpression>MIT</PackageLicenseExpression>
+ <PackageProjectUrl>https://github.com/firecrawl/firecrawl</PackageProjectUrl>
+ <RepositoryUrl>https://github.com/firecrawl/firecrawl</RepositoryUrl>
+ <RepositoryType>git</RepositoryType>
+ <PackageTags>firecrawl;web-scraping;crawling;api;sdk</PackageTags>
+ <PackageReadmeFile>README.md</PackageReadmeFile>
+ </PropertyGroup>
+
+ <ItemGroup>
+ <PackageReference Include="System.Text.Json" Version="9.0.3" />
+ </ItemGroup>
+
+ <ItemGroup>
+ <None Include="..\README.md" Pack="true" PackagePath="\" />
+ </ItemGroup>
+
+</Project>
diff --git a/apps/.net-sdk/Firecrawl/FirecrawlClient.cs b/apps/.net-sdk/Firecrawl/FirecrawlClient.cs
new file mode 100644
index 000000000..fa2cc920a
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/FirecrawlClient.cs
@@ -0,0 +1,449 @@
+using System.Text.Json;
+using Firecrawl.Exceptions;
+using Firecrawl.Models;
+
+namespace Firecrawl;
+
+/// <summary>
+/// Client for the Firecrawl v2 API.
+///
+/// <example>
+/// <code>
+/// var client = new FirecrawlClient("fc-your-api-key");
+///
+/// // Scrape a single page
+/// var doc = await client.ScrapeAsync("https://example.com",
+/// new ScrapeOptions { Formats = new List&lt;object&gt; { "markdown" } });
+///
+/// // Crawl a website
+/// var job = await client.CrawlAsync("https://example.com",
+/// new CrawlOptions { Limit = 50 });
+/// </code>
+/// </example>
+/// </summary>
+public class FirecrawlClient
+{
+ private const string DefaultApiUrl = "https://api.firecrawl.dev";
+ private static readonly TimeSpan DefaultTimeout = TimeSpan.FromMinutes(5);
+ private const int DefaultMaxRetries = 3;
+ private const double DefaultBackoffFactor = 0.5;
+ private const int DefaultPollIntervalSec = 2;
+ private const int DefaultJobTimeoutSec = 300;
+
+ private readonly FirecrawlHttpClient _http;
+
+ /// <summary>
+ /// Creates a new FirecrawlClient with the specified API key.
+ /// </summary>
+ /// <param name="apiKey">The Firecrawl API key.</param>
+ /// <param name="apiUrl">Optional API base URL (defaults to https://api.firecrawl.dev).</param>
+ /// <param name="timeout">Optional HTTP request timeout.</param>
+ /// <param name="maxRetries">Optional maximum number of retries for transient failures.</param>
+ /// <param name="backoffFactor">Optional exponential backoff factor in seconds.</param>
+ /// <param name="httpClient">Optional pre-configured HttpClient instance.</param>
+ public FirecrawlClient(
+ string? apiKey = null,
+ string? apiUrl = null,
+ TimeSpan? timeout = null,
+ int maxRetries = DefaultMaxRetries,
+ double backoffFactor = DefaultBackoffFactor,
+ HttpClient? httpClient = null)
+ {
+ var resolvedKey = ResolveApiKey(apiKey);
+ var resolvedUrl = ResolveApiUrl(apiUrl);
+
+ _http = new FirecrawlHttpClient(
+ resolvedKey,
+ resolvedUrl,
+ timeout ?? DefaultTimeout,
+ maxRetries,
+ backoffFactor,
+ httpClient);
+ }
+
+ // ================================================================
+ // SCRAPE
+ // ================================================================
+
+ /// <summary>
+ /// Scrapes a single URL and returns the document.
+ /// </summary>
+ public async Task<Document> ScrapeAsync(
+ string url,
+ ScrapeOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(url);
+
+ var body = BuildBody(options);
+ body["url"] = url;
+
+ var response = await _http.PostAsync<ApiResponse<Document>>(
+ "/v2/scrape", body, cancellationToken: cancellationToken);
+
+ return response.Data ?? throw new FirecrawlException("Scrape response contained no data");
+ }
+
+ // ================================================================
+ // CRAWL
+ // ================================================================
+
+ /// <summary>
+ /// Starts an async crawl job and returns immediately.
+ /// </summary>
+ public async Task<CrawlResponse> StartCrawlAsync(
+ string url,
+ CrawlOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(url);
+
+ var body = BuildBody(options);
+ body["url"] = url;
+
+ return await _http.PostAsync<CrawlResponse>(
+ "/v2/crawl", body, cancellationToken: cancellationToken);
+ }
+
+ /// <summary>
+ /// Gets the status and results of a crawl job.
+ /// </summary>
+ public async Task<CrawlJob> GetCrawlStatusAsync(
+ string jobId,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(jobId);
+
+ return await _http.GetAsync<CrawlJob>(
+ $"/v2/crawl/{jobId}", cancellationToken);
+ }
+
+ /// <summary>
+ /// Crawls a website and waits for completion (auto-polling).
+ /// </summary>
+ public async Task<CrawlJob> CrawlAsync(
+ string url,
+ CrawlOptions? options = null,
+ int pollIntervalSec = DefaultPollIntervalSec,
+ int timeoutSec = DefaultJobTimeoutSec,
+ CancellationToken cancellationToken = default)
+ {
+ var start = await StartCrawlAsync(url, options, cancellationToken);
+ return await PollCrawlAsync(
+ start.Id ?? throw new FirecrawlException("Crawl start did not return a job ID"),
+ pollIntervalSec, timeoutSec, cancellationToken);
+ }
+
+ /// <summary>
+ /// Cancels a running crawl job.
+ /// </summary>
+ public async Task<Dictionary<string, object>> CancelCrawlAsync(
+ string jobId,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(jobId);
+
+ return await _http.DeleteAsync<Dictionary<string, object>>(
+ $"/v2/crawl/{jobId}", cancellationToken);
+ }
+
+ /// <summary>
+ /// Gets errors from a crawl job.
+ /// </summary>
+ public async Task<Dictionary<string, object>> GetCrawlErrorsAsync(
+ string jobId,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(jobId);
+
+ return await _http.GetAsync<Dictionary<string, object>>(
+ $"/v2/crawl/{jobId}/errors", cancellationToken);
+ }
+
+ // ================================================================
+ // BATCH SCRAPE
+ // ================================================================
+
+ /// <summary>
+ /// Starts an async batch scrape job.
+ /// </summary>
+ public async Task<BatchScrapeResponse> StartBatchScrapeAsync(
+ List<string> urls,
+ BatchScrapeOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(urls);
+
+ var body = BuildBody(options);
+ body["urls"] = urls;
+
+ // The API expects scrape options flattened at the top level
+ if (body.TryGetValue("options", out var nested) && nested is JsonElement nestedElement)
+ {
+ body.Remove("options");
+ var nestedDict = JsonSerializer.Deserialize<Dictionary<string, object>>(
+ nestedElement.GetRawText(), FirecrawlHttpClient.JsonOptions);
+ if (nestedDict != null)
+ {
+ var batchFields = new Dictionary<string, object>(body);
+ foreach (var kv in nestedDict)
+ body.TryAdd(kv.Key, kv.Value);
+ foreach (var kv in batchFields)
+ body[kv.Key] = kv.Value;
+ }
+ }
+
+ Dictionary<string, string>? extraHeaders = null;
+ if (options?.IdempotencyKey is { Length: > 0 } idempotencyKey)
+ {
+ extraHeaders = new Dictionary<string, string>
+ {
+ ["x-idempotency-key"] = idempotencyKey
+ };
+ }
+
+ return await _http.PostAsync<BatchScrapeResponse>(
+ "/v2/batch/scrape", body, extraHeaders, cancellationToken);
+ }
+
+ /// <summary>
+ /// Gets the status and results of a batch scrape job.
+ /// </summary>
+ public async Task<BatchScrapeJob> GetBatchScrapeStatusAsync(
+ string jobId,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(jobId);
+
+ return await _http.GetAsync<BatchScrapeJob>(
+ $"/v2/batch/scrape/{jobId}", cancellationToken);
+ }
+
+ /// <summary>
+ /// Batch-scrapes URLs and waits for completion (auto-polling).
+ /// </summary>
+ public async Task<BatchScrapeJob> BatchScrapeAsync(
+ List<string> urls,
+ BatchScrapeOptions? options = null,
+ int pollIntervalSec = DefaultPollIntervalSec,
+ int timeoutSec = DefaultJobTimeoutSec,
+ CancellationToken cancellationToken = default)
+ {
+ var start = await StartBatchScrapeAsync(urls, options, cancellationToken);
+ return await PollBatchScrapeAsync(
+ start.Id ?? throw new FirecrawlException("Batch scrape start did not return a job ID"),
+ pollIntervalSec, timeoutSec, cancellationToken);
+ }
+
+ /// <summary>
+ /// Cancels a running batch scrape job.
+ /// </summary>
+ public async Task<Dictionary<string, object>> CancelBatchScrapeAsync(
+ string jobId,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(jobId);
+
+ return await _http.DeleteAsync<Dictionary<string, object>>(
+ $"/v2/batch/scrape/{jobId}", cancellationToken);
+ }
+
+ // ================================================================
+ // MAP
+ // ================================================================
+
+ /// <summary>
+ /// Discovers URLs on a website.
+ /// </summary>
+ public async Task<MapData> MapAsync(
+ string url,
+ MapOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(url);
+
+ var body = BuildBody(options);
+ body["url"] = url;
+
+ var response = await _http.PostAsync<ApiResponse<MapData>>(
+ "/v2/map", body, cancellationToken: cancellationToken);
+
+ return response.Data ?? throw new FirecrawlException("Map response contained no data");
+ }
+
+ // ================================================================
+ // SEARCH
+ // ================================================================
+
+ /// <summary>
+ /// Performs a web search.
+ /// </summary>
+ public async Task<SearchData> SearchAsync(
+ string query,
+ SearchOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(query);
+
+ var body = BuildBody(options);
+ body["query"] = query;
+
+ var response = await _http.PostAsync<ApiResponse<SearchData>>(
+ "/v2/search", body, cancellationToken: cancellationToken);
+
+ return response.Data ?? throw new FirecrawlException("Search response contained no data");
+ }
+
+ // ================================================================
+ // USAGE & METRICS
+ // ================================================================
+
+ /// <summary>
+ /// Gets current concurrency usage.
+ /// </summary>
+ public async Task<ConcurrencyCheck> GetConcurrencyAsync(
+ CancellationToken cancellationToken = default)
+ {
+ return await _http.GetAsync<ConcurrencyCheck>(
+ "/v2/concurrency-check", cancellationToken);
+ }
+
+ /// <summary>
+ /// Gets current credit usage.
+ /// </summary>
+ public async Task<CreditUsage> GetCreditUsageAsync(
+ CancellationToken cancellationToken = default)
+ {
+ return await _http.GetAsync<CreditUsage>(
+ "/v2/team/credit-usage", cancellationToken);
+ }
+
+ // ================================================================
+ // INTERNAL POLLING HELPERS
+ // ================================================================
+
+ private async Task<CrawlJob> PollCrawlAsync(
+ string jobId,
+ int pollIntervalSec,
+ int timeoutSec,
+ CancellationToken cancellationToken)
+ {
+ var deadline = DateTime.UtcNow.AddSeconds(timeoutSec);
+
+ while (DateTime.UtcNow < deadline)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+
+ var job = await GetCrawlStatusAsync(jobId, cancellationToken);
+ if (job.IsDone)
+ return await PaginateCrawlAsync(job, cancellationToken);
+
+ await Task.Delay(TimeSpan.FromSeconds(pollIntervalSec), cancellationToken);
+ }
+
+ throw new JobTimeoutException(jobId, timeoutSec, "Crawl");
+ }
+
+ private async Task<BatchScrapeJob> PollBatchScrapeAsync(
+ string jobId,
+ int pollIntervalSec,
+ int timeoutSec,
+ CancellationToken cancellationToken)
+ {
+ var deadline = DateTime.UtcNow.AddSeconds(timeoutSec);
+
+ while (DateTime.UtcNow < deadline)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+
+ var job = await GetBatchScrapeStatusAsync(jobId, cancellationToken);
+ if (job.IsDone)
+ return await PaginateBatchScrapeAsync(job, cancellationToken);
+
+ await Task.Delay(TimeSpan.FromSeconds(pollIntervalSec), cancellationToken);
+ }
+
+ throw new JobTimeoutException(jobId, timeoutSec, "Batch scrape");
+ }
+
+ private async Task<CrawlJob> PaginateCrawlAsync(
+ CrawlJob job,
+ CancellationToken cancellationToken)
+ {
+ job.Data ??= new List<Document>();
+ var current = job;
+
+ while (!string.IsNullOrEmpty(current.Next))
+ {
+ var nextPage = await _http.GetAbsoluteAsync<CrawlJob>(
+ current.Next, cancellationToken);
+
+ if (nextPage.Data is { Count: > 0 })
+ job.Data.AddRange(nextPage.Data);
+
+ current = nextPage;
+ }
+
+ return job;
+ }
+
+ private async Task<BatchScrapeJob> PaginateBatchScrapeAsync(
+ BatchScrapeJob job,
+ CancellationToken cancellationToken)
+ {
+ job.Data ??= new List<Document>();
+ var current = job;
+
+ while (!string.IsNullOrEmpty(current.Next))
+ {
+ var nextPage = await _http.GetAbsoluteAsync<BatchScrapeJob>(
+ current.Next, cancellationToken);
+
+ if (nextPage.Data is { Count: > 0 })
+ job.Data.AddRange(nextPage.Data);
+
+ current = nextPage;
+ }
+
+ return job;
+ }
+
+ // ================================================================
+ // INTERNAL UTILITIES
+ // ================================================================
+
+ private static Dictionary<string, object> BuildBody(object? options)
+ {
+ if (options == null)
+ return new Dictionary<string, object>();
+
+ var json = JsonSerializer.Serialize(options, FirecrawlHttpClient.JsonOptions);
+ return JsonSerializer.Deserialize<Dictionary<string, object>>(json, FirecrawlHttpClient.JsonOptions)
+ ?? new Dictionary<string, object>();
+ }
+
+ private static string ResolveApiKey(string? apiKey)
+ {
+ if (!string.IsNullOrWhiteSpace(apiKey))
+ return apiKey;
+
+ var envKey = Environment.GetEnvironmentVariable("FIRECRAWL_API_KEY");
+ if (!string.IsNullOrWhiteSpace(envKey))
+ return envKey;
+
+ throw new FirecrawlException(
+ "API key is required. Pass it to the constructor or set the FIRECRAWL_API_KEY environment variable.");
+ }
+
+ private static string ResolveApiUrl(string? apiUrl)
+ {
+ if (!string.IsNullOrWhiteSpace(apiUrl))
+ return apiUrl;
+
+ var envUrl = Environment.GetEnvironmentVariable("FIRECRAWL_API_URL");
+ if (!string.IsNullOrWhiteSpace(envUrl))
+ return envUrl;
+
+ return DefaultApiUrl;
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl/FirecrawlHttpClient.cs b/apps/.net-sdk/Firecrawl/FirecrawlHttpClient.cs
new file mode 100644
index 000000000..b8f1cae42
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/FirecrawlHttpClient.cs
@@ -0,0 +1,236 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Firecrawl.Exceptions;
+
+namespace Firecrawl;
+
+/// <summary>
+/// Internal HTTP client for making authenticated requests to the Firecrawl API.
+/// Handles retry logic with exponential backoff.
+/// </summary>
+internal class FirecrawlHttpClient
+{
+ private readonly HttpClient _httpClient;
+ private readonly string _apiKey;
+ private readonly string _baseUrl;
+ private readonly int _maxRetries;
+ private readonly double _backoffFactor;
+
+ internal static readonly JsonSerializerOptions JsonOptions = new()
+ {
+ PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+ DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+ PropertyNameCaseInsensitive = true
+ };
+
+ internal FirecrawlHttpClient(
+ string apiKey,
+ string baseUrl,
+ TimeSpan timeout,
+ int maxRetries,
+ double backoffFactor,
+ HttpClient? httpClient = null)
+ {
+ _apiKey = apiKey;
+ _baseUrl = baseUrl.TrimEnd('/');
+ _maxRetries = maxRetries;
+ _backoffFactor = backoffFactor;
+
+ if (httpClient != null)
+ {
+ _httpClient = httpClient;
+ }
+ else
+ {
+ _httpClient = new HttpClient { Timeout = timeout };
+ }
+ }
+
+ internal async Task<T> PostAsync<T>(
+ string path,
+ object body,
+ Dictionary<string, string>? extraHeaders = null,
+ CancellationToken cancellationToken = default)
+ {
+ var url = _baseUrl + path;
+ var json = JsonSerializer.Serialize(body, JsonOptions);
+ var content = new StringContent(json, Encoding.UTF8, "application/json");
+
+ var request = new HttpRequestMessage(HttpMethod.Post, url) { Content = content };
+ request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _apiKey);
+ request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+
+ if (extraHeaders != null)
+ {
+ foreach (var header in extraHeaders)
+ {
+ request.Headers.TryAddWithoutValidation(header.Key, header.Value);
+ }
+ }
+
+ return await ExecuteWithRetryAsync<T>(request, cancellationToken);
+ }
+
+ internal async Task<T> GetAsync<T>(string path, CancellationToken cancellationToken = default)
+ {
+ var url = _baseUrl + path;
+ var request = new HttpRequestMessage(HttpMethod.Get, url);
+ request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _apiKey);
+ request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+
+ return await ExecuteWithRetryAsync<T>(request, cancellationToken);
+ }
+
+ internal async Task<T> GetAbsoluteAsync<T>(string absoluteUrl, CancellationToken cancellationToken = default)
+ {
+ var request = new HttpRequestMessage(HttpMethod.Get, absoluteUrl);
+ request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _apiKey);
+ request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+
+ return await ExecuteWithRetryAsync<T>(request, cancellationToken);
+ }
+
+ internal async Task<T> DeleteAsync<T>(string path, CancellationToken cancellationToken = default)
+ {
+ var url = _baseUrl + path;
+ var request = new HttpRequestMessage(HttpMethod.Delete, url);
+ request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _apiKey);
+ request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+
+ return await ExecuteWithRetryAsync<T>(request, cancellationToken);
+ }
+
+ private async Task<T> ExecuteWithRetryAsync<T>(
+ HttpRequestMessage originalRequest,
+ CancellationToken cancellationToken)
+ {
+ var attempt = 0;
+
+ while (true)
+ {
+ // Clone the request for each attempt (HttpRequestMessage can only be sent once)
+ using var request = await CloneRequestAsync(originalRequest);
+
+ HttpResponseMessage? response = null;
+ try
+ {
+ response = await _httpClient.SendAsync(request, cancellationToken);
+ var bodyStr = await response.Content.ReadAsStringAsync(cancellationToken);
+
+ if (response.IsSuccessStatusCode)
+ {
+ return JsonSerializer.Deserialize<T>(bodyStr, JsonOptions)
+ ?? throw new FirecrawlException("Failed to deserialize response");
+ }
+
+ var code = (int)response.StatusCode;
+ var errorMessage = ExtractErrorMessage(bodyStr, code);
+ var errorCode = ExtractErrorCode(bodyStr);
+
+ // Non-retryable client errors
+ if (code == 401)
+ throw new AuthenticationException(errorMessage, errorCode);
+ if (code == 429)
+ throw new RateLimitException(errorMessage, errorCode);
+ if (code >= 400 && code < 500 && code != 408 && code != 409)
+ throw new FirecrawlException(errorMessage, code, errorCode, null);
+
+ // Retryable errors: 408, 409, 502, 5xx
+ if (attempt < _maxRetries)
+ {
+ attempt++;
+ await SleepWithBackoffAsync(attempt, cancellationToken);
+ continue;
+ }
+
+ throw new FirecrawlException(errorMessage, code, errorCode, null);
+ }
+ catch (FirecrawlException)
+ {
+ throw;
+ }
+ catch (OperationCanceledException)
+ {
+ throw;
+ }
+ catch (Exception ex)
+ {
+ if (attempt < _maxRetries)
+ {
+ attempt++;
+ await SleepWithBackoffAsync(attempt, cancellationToken);
+ continue;
+ }
+
+ throw new FirecrawlException($"Request failed: {ex.Message}", ex);
+ }
+ finally
+ {
+ response?.Dispose();
+ }
+ }
+ }
+
+ private static async Task<HttpRequestMessage> CloneRequestAsync(HttpRequestMessage original)
+ {
+ var clone = new HttpRequestMessage(original.Method, original.RequestUri);
+
+ if (original.Content != null)
+ {
+ var content = await original.Content.ReadAsStringAsync();
+ clone.Content = new StringContent(content, Encoding.UTF8, "application/json");
+ }
+
+ foreach (var header in original.Headers)
+ {
+ clone.Headers.TryAddWithoutValidation(header.Key, header.Value);
+ }
+
+ return clone;
+ }
+
+ private static string ExtractErrorMessage(string body, int statusCode)
+ {
+ try
+ {
+ using var doc = JsonDocument.Parse(body);
+ var root = doc.RootElement;
+
+ if (root.TryGetProperty("error", out var errorProp))
+ return errorProp.GetString() ?? $"HTTP {statusCode} error";
+ if (root.TryGetProperty("message", out var messageProp))
+ return messageProp.GetString() ?? $"HTTP {statusCode} error";
+ }
+ catch
+ {
+ // ignored
+ }
+
+ return $"HTTP {statusCode} error";
+ }
+
+ private static string? ExtractErrorCode(string body)
+ {
+ try
+ {
+ using var doc = JsonDocument.Parse(body);
+ if (doc.RootElement.TryGetProperty("code", out var codeProp))
+ return codeProp.GetString();
+ }
+ catch
+ {
+ // ignored
+ }
+
+ return null;
+ }
+
+ private async Task SleepWithBackoffAsync(int attempt, CancellationToken cancellationToken)
+ {
+ var delayMs = (int)(_backoffFactor * 1000 * Math.Pow(2, attempt - 1));
+ await Task.Delay(delayMs, cancellationToken);
+ }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/ApiResponse.cs b/apps/.net-sdk/Firecrawl/Models/ApiResponse.cs
new file mode 100644
index 000000000..0b5b6a055
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/ApiResponse.cs
@@ -0,0 +1,15 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Internal wrapper for API responses that contain a "data" field.
+/// </summary>
+internal class ApiResponse<T>
+{
+ [JsonPropertyName("success")]
+ public bool Success { get; set; }
+
+ [JsonPropertyName("data")]
+ public T? Data { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/BatchScrapeJob.cs b/apps/.net-sdk/Firecrawl/Models/BatchScrapeJob.cs
new file mode 100644
index 000000000..2839c597f
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/BatchScrapeJob.cs
@@ -0,0 +1,39 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Status and results of a batch scrape job.
+/// </summary>
+public class BatchScrapeJob
+{
+ [JsonPropertyName("id")]
+ public string? Id { get; set; }
+
+ [JsonPropertyName("status")]
+ public string? Status { get; set; }
+
+ [JsonPropertyName("completed")]
+ public int? Completed { get; set; }
+
+ [JsonPropertyName("total")]
+ public int? Total { get; set; }
+
+ [JsonPropertyName("creditsUsed")]
+ public int? CreditsUsed { get; set; }
+
+ [JsonPropertyName("expiresAt")]
+ public string? ExpiresAt { get; set; }
+
+ [JsonPropertyName("next")]
+ public string? Next { get; set; }
+
+ [JsonPropertyName("data")]
+ public List<Document>? Data { get; set; }
+
+ /// <summary>
+ /// Returns true if the batch scrape job has reached a terminal state.
+ /// </summary>
+ public bool IsDone =>
+ Status == "completed" || Status == "cancelled" || Status == "failed";
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/BatchScrapeOptions.cs b/apps/.net-sdk/Firecrawl/Models/BatchScrapeOptions.cs
new file mode 100644
index 000000000..38b23716d
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/BatchScrapeOptions.cs
@@ -0,0 +1,43 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Configuration options for batch scraping multiple URLs.
+/// </summary>
+public class BatchScrapeOptions
+{
+ [JsonPropertyName("options")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public ScrapeOptions? Options { get; set; }
+
+ [JsonPropertyName("webhook")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public object? Webhook { get; set; }
+
+ [JsonPropertyName("appendToId")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? AppendToId { get; set; }
+
+ [JsonPropertyName("ignoreInvalidURLs")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? IgnoreInvalidURLs { get; set; }
+
+ [JsonPropertyName("maxConcurrency")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? MaxConcurrency { get; set; }
+
+ [JsonPropertyName("zeroDataRetention")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? ZeroDataRetention { get; set; }
+
+ [JsonPropertyName("integration")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Integration { get; set; }
+
+ /// <summary>
+ /// Idempotency key sent as the x-idempotency-key HTTP header (not in the JSON body).
+ /// </summary>
+ [JsonIgnore]
+ public string? IdempotencyKey { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/BatchScrapeResponse.cs b/apps/.net-sdk/Firecrawl/Models/BatchScrapeResponse.cs
new file mode 100644
index 000000000..667dfe149
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/BatchScrapeResponse.cs
@@ -0,0 +1,18 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Response from starting an async batch scrape job.
+/// </summary>
+public class BatchScrapeResponse
+{
+ [JsonPropertyName("success")]
+ public bool Success { get; set; }
+
+ [JsonPropertyName("id")]
+ public string? Id { get; set; }
+
+ [JsonPropertyName("invalidURLs")]
+ public List<string>? InvalidURLs { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/ConcurrencyCheck.cs b/apps/.net-sdk/Firecrawl/Models/ConcurrencyCheck.cs
new file mode 100644
index 000000000..5e5b1401b
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/ConcurrencyCheck.cs
@@ -0,0 +1,15 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Current concurrency usage information.
+/// </summary>
+public class ConcurrencyCheck
+{
+ [JsonPropertyName("current")]
+ public int Current { get; set; }
+
+ [JsonPropertyName("max")]
+ public int MaxConcurrency { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/CrawlJob.cs b/apps/.net-sdk/Firecrawl/Models/CrawlJob.cs
new file mode 100644
index 000000000..7c8b5592d
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/CrawlJob.cs
@@ -0,0 +1,39 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Status and results of a crawl job.
+/// </summary>
+public class CrawlJob
+{
+ [JsonPropertyName("id")]
+ public string? Id { get; set; }
+
+ [JsonPropertyName("status")]
+ public string? Status { get; set; }
+
+ [JsonPropertyName("completed")]
+ public int? Completed { get; set; }
+
+ [JsonPropertyName("total")]
+ public int? Total { get; set; }
+
+ [JsonPropertyName("creditsUsed")]
+ public int? CreditsUsed { get; set; }
+
+ [JsonPropertyName("expiresAt")]
+ public string? ExpiresAt { get; set; }
+
+ [JsonPropertyName("next")]
+ public string? Next { get; set; }
+
+ [JsonPropertyName("data")]
+ public List<Document>? Data { get; set; }
+
+ /// <summary>
+ /// Returns true if the crawl job has reached a terminal state.
+ /// </summary>
+ public bool IsDone =>
+ Status == "completed" || Status == "cancelled" || Status == "failed";
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/CrawlOptions.cs b/apps/.net-sdk/Firecrawl/Models/CrawlOptions.cs
new file mode 100644
index 000000000..713b85130
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/CrawlOptions.cs
@@ -0,0 +1,81 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Configuration options for crawling a website.
+/// </summary>
+public class CrawlOptions
+{
+ [JsonPropertyName("prompt")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Prompt { get; set; }
+
+ [JsonPropertyName("excludePaths")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<string>? ExcludePaths { get; set; }
+
+ [JsonPropertyName("includePaths")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<string>? IncludePaths { get; set; }
+
+ [JsonPropertyName("maxDiscoveryDepth")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? MaxDiscoveryDepth { get; set; }
+
+ [JsonPropertyName("sitemap")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Sitemap { get; set; }
+
+ [JsonPropertyName("ignoreQueryParameters")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? IgnoreQueryParameters { get; set; }
+
+ [JsonPropertyName("deduplicateSimilarURLs")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? DeduplicateSimilarURLs { get; set; }
+
+ [JsonPropertyName("limit")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? Limit { get; set; }
+
+ [JsonPropertyName("crawlEntireDomain")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? CrawlEntireDomain { get; set; }
+
+ [JsonPropertyName("allowExternalLinks")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? AllowExternalLinks { get; set; }
+
+ [JsonPropertyName("allowSubdomains")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? AllowSubdomains { get; set; }
+
+ [JsonPropertyName("delay")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? Delay { get; set; }
+
+ [JsonPropertyName("maxConcurrency")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? MaxConcurrency { get; set; }
+
+ [JsonPropertyName("webhook")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public object? Webhook { get; set; }
+
+ [JsonPropertyName("scrapeOptions")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public ScrapeOptions? ScrapeOptions { get; set; }
+
+ [JsonPropertyName("regexOnFullURL")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? RegexOnFullURL { get; set; }
+
+ [JsonPropertyName("zeroDataRetention")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? ZeroDataRetention { get; set; }
+
+ [JsonPropertyName("integration")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Integration { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/CrawlResponse.cs b/apps/.net-sdk/Firecrawl/Models/CrawlResponse.cs
new file mode 100644
index 000000000..33329ff21
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/CrawlResponse.cs
@@ -0,0 +1,18 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Response from starting an async crawl job.
+/// </summary>
+public class CrawlResponse
+{
+ [JsonPropertyName("success")]
+ public bool Success { get; set; }
+
+ [JsonPropertyName("id")]
+ public string? Id { get; set; }
+
+ [JsonPropertyName("url")]
+ public string? Url { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/CreditUsage.cs b/apps/.net-sdk/Firecrawl/Models/CreditUsage.cs
new file mode 100644
index 000000000..cbcc83ad6
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/CreditUsage.cs
@@ -0,0 +1,21 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Account credit usage information.
+/// </summary>
+public class CreditUsage
+{
+ [JsonPropertyName("remaining_credits")]
+ public int? RemainingCredits { get; set; }
+
+ [JsonPropertyName("total_credits_used")]
+ public int? TotalCreditsUsed { get; set; }
+
+ [JsonPropertyName("billing_period_start")]
+ public string? BillingPeriodStart { get; set; }
+
+ [JsonPropertyName("billing_period_end")]
+ public string? BillingPeriodEnd { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/Document.cs b/apps/.net-sdk/Firecrawl/Models/Document.cs
new file mode 100644
index 000000000..c16b687f3
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/Document.cs
@@ -0,0 +1,51 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Represents a scraped document returned by the Firecrawl API.
+/// </summary>
+public class Document
+{
+ [JsonPropertyName("markdown")]
+ public string? Markdown { get; set; }
+
+ [JsonPropertyName("html")]
+ public string? Html { get; set; }
+
+ [JsonPropertyName("rawHtml")]
+ public string? RawHtml { get; set; }
+
+ [JsonPropertyName("json")]
+ public object? Json { get; set; }
+
+ [JsonPropertyName("summary")]
+ public string? Summary { get; set; }
+
+ [JsonPropertyName("metadata")]
+ public Dictionary<string, object>? Metadata { get; set; }
+
+ [JsonPropertyName("links")]
+ public List<object>? Links { get; set; }
+
+ [JsonPropertyName("images")]
+ public List<object>? Images { get; set; }
+
+ [JsonPropertyName("screenshot")]
+ public string? Screenshot { get; set; }
+
+ [JsonPropertyName("audio")]
+ public object? Audio { get; set; }
+
+ [JsonPropertyName("actions")]
+ public object? Actions { get; set; }
+
+ [JsonPropertyName("warning")]
+ public string? Warning { get; set; }
+
+ [JsonPropertyName("changeTracking")]
+ public object? ChangeTracking { get; set; }
+
+ [JsonPropertyName("branding")]
+ public object? Branding { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/JsonFormat.cs b/apps/.net-sdk/Firecrawl/Models/JsonFormat.cs
new file mode 100644
index 000000000..a38f26c1b
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/JsonFormat.cs
@@ -0,0 +1,20 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// JSON extraction format specification for use in ScrapeOptions.Formats.
+/// </summary>
+public class JsonFormat
+{
+ [JsonPropertyName("type")]
+ public string Type { get; } = "json";
+
+ [JsonPropertyName("prompt")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Prompt { get; set; }
+
+ [JsonPropertyName("schema")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public Dictionary<string, object>? Schema { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/LocationConfig.cs b/apps/.net-sdk/Firecrawl/Models/LocationConfig.cs
new file mode 100644
index 000000000..edcf956f7
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/LocationConfig.cs
@@ -0,0 +1,17 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Geolocation configuration for requests.
+/// </summary>
+public class LocationConfig
+{
+ [JsonPropertyName("country")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Country { get; set; }
+
+ [JsonPropertyName("languages")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<string>? Languages { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/MapData.cs b/apps/.net-sdk/Firecrawl/Models/MapData.cs
new file mode 100644
index 000000000..033ca88c8
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/MapData.cs
@@ -0,0 +1,12 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// URL discovery (map) results.
+/// </summary>
+public class MapData
+{
+ [JsonPropertyName("links")]
+ public List<string>? Links { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/MapOptions.cs b/apps/.net-sdk/Firecrawl/Models/MapOptions.cs
new file mode 100644
index 000000000..25d232022
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/MapOptions.cs
@@ -0,0 +1,41 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Configuration options for URL discovery (map).
+/// </summary>
+public class MapOptions
+{
+ [JsonPropertyName("search")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Search { get; set; }
+
+ [JsonPropertyName("sitemap")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Sitemap { get; set; }
+
+ [JsonPropertyName("includeSubdomains")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? IncludeSubdomains { get; set; }
+
+ [JsonPropertyName("ignoreQueryParameters")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? IgnoreQueryParameters { get; set; }
+
+ [JsonPropertyName("limit")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? Limit { get; set; }
+
+ [JsonPropertyName("timeout")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? Timeout { get; set; }
+
+ [JsonPropertyName("integration")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Integration { get; set; }
+
+ [JsonPropertyName("location")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public LocationConfig? Location { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/ScrapeOptions.cs b/apps/.net-sdk/Firecrawl/Models/ScrapeOptions.cs
new file mode 100644
index 000000000..4f5ac031d
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/ScrapeOptions.cs
@@ -0,0 +1,81 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Configuration options for scraping a single URL.
+/// </summary>
+public class ScrapeOptions
+{
+ [JsonPropertyName("formats")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<object>? Formats { get; set; }
+
+ [JsonPropertyName("headers")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public Dictionary<string, string>? Headers { get; set; }
+
+ [JsonPropertyName("includeTags")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<string>? IncludeTags { get; set; }
+
+ [JsonPropertyName("excludeTags")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<string>? ExcludeTags { get; set; }
+
+ [JsonPropertyName("onlyMainContent")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? OnlyMainContent { get; set; }
+
+ [JsonPropertyName("timeout")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? Timeout { get; set; }
+
+ [JsonPropertyName("waitFor")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? WaitFor { get; set; }
+
+ [JsonPropertyName("mobile")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? Mobile { get; set; }
+
+ [JsonPropertyName("parsers")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<object>? Parsers { get; set; }
+
+ [JsonPropertyName("actions")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<Dictionary<string, object>>? Actions { get; set; }
+
+ [JsonPropertyName("location")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public LocationConfig? Location { get; set; }
+
+ [JsonPropertyName("skipTlsVerification")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? SkipTlsVerification { get; set; }
+
+ [JsonPropertyName("removeBase64Images")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? RemoveBase64Images { get; set; }
+
+ [JsonPropertyName("blockAds")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? BlockAds { get; set; }
+
+ [JsonPropertyName("proxy")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Proxy { get; set; }
+
+ [JsonPropertyName("maxAge")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public long? MaxAge { get; set; }
+
+ [JsonPropertyName("storeInCache")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? StoreInCache { get; set; }
+
+ [JsonPropertyName("integration")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Integration { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/SearchData.cs b/apps/.net-sdk/Firecrawl/Models/SearchData.cs
new file mode 100644
index 000000000..8675508d1
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/SearchData.cs
@@ -0,0 +1,18 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Web search results.
+/// </summary>
+public class SearchData
+{
+ [JsonPropertyName("web")]
+ public List<Document>? Web { get; set; }
+
+ [JsonPropertyName("news")]
+ public List<Document>? News { get; set; }
+
+ [JsonPropertyName("images")]
+ public List<object>? Images { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/SearchOptions.cs b/apps/.net-sdk/Firecrawl/Models/SearchOptions.cs
new file mode 100644
index 000000000..825528d21
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/SearchOptions.cs
@@ -0,0 +1,45 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Configuration options for web search.
+/// </summary>
+public class SearchOptions
+{
+ [JsonPropertyName("sources")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<object>? Sources { get; set; }
+
+ [JsonPropertyName("categories")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<object>? Categories { get; set; }
+
+ [JsonPropertyName("limit")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? Limit { get; set; }
+
+ [JsonPropertyName("tbs")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Tbs { get; set; }
+
+ [JsonPropertyName("location")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Location { get; set; }
+
+ [JsonPropertyName("ignoreInvalidURLs")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? IgnoreInvalidURLs { get; set; }
+
+ [JsonPropertyName("timeout")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? Timeout { get; set; }
+
+ [JsonPropertyName("scrapeOptions")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public ScrapeOptions? ScrapeOptions { get; set; }
+
+ [JsonPropertyName("integration")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Integration { get; set; }
+}
diff --git a/apps/.net-sdk/Firecrawl/Models/WebhookConfig.cs b/apps/.net-sdk/Firecrawl/Models/WebhookConfig.cs
new file mode 100644
index 000000000..8c9721fb7
--- /dev/null
+++ b/apps/.net-sdk/Firecrawl/Models/WebhookConfig.cs
@@ -0,0 +1,24 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Webhook configuration for async jobs.
+/// </summary>
+public class WebhookConfig
+{
+ [JsonPropertyName("url")]
+ public string Url { get; set; } = string.Empty;
+
+ [JsonPropertyName("headers")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public Dictionary<string, string>? Headers { get; set; }
+
+ [JsonPropertyName("metadata")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public Dictionary<string, string>? Metadata { get; set; }
+
+ [JsonPropertyName("events")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public List<string>? Events { get; set; }
+}
diff --git a/apps/.net-sdk/README.md b/apps/.net-sdk/README.md
new file mode 100644
index 000000000..3bace5d2b
--- /dev/null
+++ b/apps/.net-sdk/README.md
@@ -0,0 +1,222 @@
+# Firecrawl .NET SDK
+
+.NET SDK for the [Firecrawl API](https://firecrawl.dev) — web scraping, crawling, and data extraction.
+
+## Installation
+
+```bash
+dotnet add package firecrawl-dotnet
+```
+
+## Quick Start
+
+```csharp
+using Firecrawl;
+using Firecrawl.Models;
+
+// Create a client
+var client = new FirecrawlClient("fc-your-api-key");
+
+// Scrape a single page
+var doc = await client.ScrapeAsync("https://example.com",
+ new ScrapeOptions { Formats = new List<object> { "markdown" } });
+
+Console.WriteLine(doc.Markdown);
+```
+
+## Configuration
+
+### API Key
+
+The API key can be provided in three ways (in order of precedence):
+
+1. Constructor parameter: `new FirecrawlClient("fc-your-api-key")`
+2. Environment variable: `FIRECRAWL_API_KEY`
+
+```csharp
+// From environment variable
+var client = new FirecrawlClient();
+
+// Explicit API key
+var client = new FirecrawlClient(apiKey: "fc-your-api-key");
+
+// Custom API URL (for self-hosted instances)
+var client = new FirecrawlClient(
+ apiKey: "fc-your-api-key",
+ apiUrl: "https://your-firecrawl-instance.com");
+
+// Custom HttpClient
+var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
+var client = new FirecrawlClient(
+ apiKey: "fc-your-api-key",
+ httpClient: httpClient);
+```
+
+## Usage
+
+### Scrape
+
+```csharp
+// Basic scrape
+var doc = await client.ScrapeAsync("https://example.com");
+
+// Scrape with options
+var doc = await client.ScrapeAsync("https://example.com",
+ new ScrapeOptions
+ {
+ Formats = new List<object> { "markdown", "html" },
+ OnlyMainContent = true,
+ WaitFor = 5000
+ });
+
+Console.WriteLine(doc.Markdown);
+Console.WriteLine(doc.Html);
+```
+
+### Crawl
+
+```csharp
+// Crawl with auto-polling (waits for completion)
+var job = await client.CrawlAsync("https://example.com",
+ new CrawlOptions
+ {
+ Limit = 50,
+ MaxDiscoveryDepth = 3,
+ ExcludePaths = new List<string> { "/admin/*" }
+ });
+
+foreach (var page in job.Data!)
+{
+ Console.WriteLine(page.Markdown);
+}
+
+// Start crawl without waiting
+var response = await client.StartCrawlAsync("https://example.com",
+ new CrawlOptions { Limit = 100 });
+
+// Check status later
+var status = await client.GetCrawlStatusAsync(response.Id!);
+Console.WriteLine($"Status: {status.Status}, Progress: {status.Completed}/{status.Total}");
+
+// Cancel a crawl
+await client.CancelCrawlAsync(response.Id!);
+```
+
+### Batch Scrape
+
+```csharp
+// Batch scrape with auto-polling
+var urls = new List<string>
+{
+ "https://example.com/page1",
+ "https://example.com/page2",
+ "https://example.com/page3"
+};
+
+var job = await client.BatchScrapeAsync(urls,
+ new BatchScrapeOptions
+ {
+ Options = new ScrapeOptions
+ {
+ Formats = new List<object> { "markdown" }
+ }
+ });
+
+foreach (var doc in job.Data!)
+{
+ Console.WriteLine(doc.Markdown);
+}
+```
+
+### Map (URL Discovery)
+
+```csharp
+// Discover URLs on a website
+var data = await client.MapAsync("https://example.com",
+ new MapOptions
+ {
+ Search = "pricing",
+ Limit = 100
+ });
+
+foreach (var url in data.Links!)
+{
+ Console.WriteLine(url);
+}
+```
+
+### Search
+
+```csharp
+// Web search
+var results = await client.SearchAsync("firecrawl web scraping",
+ new SearchOptions
+ {
+ Limit = 5,
+ Location = "US"
+ });
+```
+
+### Usage & Metrics
+
+```csharp
+// Check concurrency
+var concurrency = await client.GetConcurrencyAsync();
+Console.WriteLine($"Current: {concurrency.Current}, Max: {concurrency.MaxConcurrency}");
+
+// Check credit usage
+var usage = await client.GetCreditUsageAsync();
+Console.WriteLine($"Remaining credits: {usage.RemainingCredits}");
+```
+
+## Error Handling
+
+```csharp
+using Firecrawl.Exceptions;
+
+try
+{
+ var doc = await client.ScrapeAsync("https://example.com");
+}
+catch (AuthenticationException ex)
+{
+ // 401 - Invalid API key
+ Console.WriteLine($"Auth error: {ex.Message}");
+}
+catch (RateLimitException ex)
+{
+ // 429 - Too many requests
+ Console.WriteLine($"Rate limited: {ex.Message}");
+}
+catch (JobTimeoutException ex)
+{
+ // Async job timed out
+ Console.WriteLine($"Job {ex.JobId} timed out after {ex.TimeoutSeconds}s");
+}
+catch (FirecrawlException ex)
+{
+ // General API error
+ Console.WriteLine($"Error {ex.StatusCode}: {ex.Message}");
+}
+```
+
+## Requirements
+
+- .NET 8.0 or later
+
+## Development
+
+```bash
+# Restore dependencies
+dotnet restore
+
+# Build
+dotnet build
+
+# Run tests
+dotnet test
+```
+
+## License
+
+MIT