TvdbClient

A C# HttpClient-based API client for TheTVDB v4 API.

• TheTVDB API · v4-api GitHub · API docs

This is a thin client AS IS — it does not implement the caching/proxying that TheTVDB recommends. Add your own caching layer if you call the API at volume.

Packages

The client is split into three packages so the API-versioned models can be regenerated independently of the generic client code:

Package	What	Versioning
TvdbClient	Client core: generated clients, auth, DI wiring.	Generic SemVer
TvdbClient.Models	The generated DTOs (Tvdb.Models).	Tracks the TheTVDB API version (Major.Minor)
TvdbClient.Abstractions	Generic contracts, configuration, response envelope.	Generic SemVer

Installing TvdbClient pulls in the other two.

dotnet add package TvdbClient

Usage

Configuration

Provide your TheTVDB API key (and optional subscriber PIN) via configuration — either appsettings.json or a standalone TvdbClientConfig.json:

{
  "TvdbConfiguration": {
    "BaseUrl": "https://api4.thetvdb.com/v4",
    "ApiKey": "<your-api-key>",
    "Pin": "<optional-subscriber-pin>"
  }
}

Get an API key from TheTVDB's API Key dashboard.

DI registration

using Microsoft.Extensions.DependencyInjection;

builder.Configuration.AddTvdbClient();
builder.Services.AddTvdbClient(builder.Configuration);

Using the clients

Resolve the per-resource client you need. Login/token acquisition and the Authorization header are handled automatically by the registered handler.

using Tvdb.Clients;

var series = serviceProvider.GetRequiredService<ISeriesClient>();
var response = await series.SeriesGetAsync(121361);   // ids are long
var record = response.Data;                            // { data, status } envelope

Building

This project builds with Fallout (a NUKE fork) — the build lives in build/Build.cs and runs through the ./build.ps1 bootstrapper (no global tool required). CI (build.yml) invokes the same targets.

./build.ps1 Test       # run the *.Specs test suite
./build.ps1 Pack       # produce the three NuGet packages in artifacts/packages
./build.ps1 Generate   # regenerate the client + models from TheTVDB's OpenAPI spec

Regenerating the models

Models + clients are generated from TheTVDB's OpenAPI spec via the Fallout Generate target (NSwag under the hood):

./build.ps1 Generate

This downloads the live v4 spec, applies a small overlay (integer-id coercion, inline-enum hoisting), and regenerates TvdbClient.Models + the clients.

Versioning

Major.Minor track the TheTVDB API version; the patch is this library's own release counter. Managed with GitVersion (dotnet-gitversion).

License

MIT