API vs SDK: what's the difference, and do you need one?

An API is the contract a service exposes: its HTTP routes, request fields, responses and errors. An SDK (software development kit) is a library for one programming language that calls that API for you, adding types, authentication and helpers such as polling loops. Anything an SDK does, you can also do with plain HTTP requests against the API.

The worked example is Sume, which publishes both. Its facts come from the TypeScript SDK and Public API docs, read on 2026-09-28.

What does an SDK add on top of an API?

Mostly the code you would otherwise write by hand around each request. Here is how that splits for Sume:

Is an SDK the same as an API?

No. The API is the source of truth, and the SDK is one client of it. Sume's docs call its SDK "a convenience layer, not a second contract": the API docs and the API reference stay the source of truth for fields, and everything the SDK does is also reachable over plain HTTP. When the two seem to disagree, trust the API reference.

The same call, both ways. The SDK lines follow the docs; the fetch lines are the raw request they wrap:

// With the SDK
import { createSumeClient, listFormats } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });
const { data, error } = await listFormats({ client });

// With plain HTTP
const res = await fetch("https://api.sume.com/v1/formats", {
  headers: { "x-api-key": process.env.SUME_API_KEY! },
});
const body = await res.json();

When should I call the API directly instead?

• Your language has no SDK. Sume's official SDK is for TypeScript, and its docs note, for example, that Sume does not publish a Kotlin package. Generate a client from the OpenAPI schema or call REST, as Sume's OpenAPI spec and API clients shows.
• You work in a tool that only makes HTTP requests, such as a workflow builder or a shell script.
• You need one or two calls and would rather not add a dependency.
• Use the SDK when you are in its language and would otherwise write the poll loop, retries and webhook check yourself. The Sume TypeScript SDK quickstart starts there.

What goes wrong when you mix an SDK with raw HTTP?

Headers set in two places. Sume's SDK sends x-api-key, and the API rejects a request that carries both Authorization: Bearer and x-api-key with 401 unauthorized, so a gateway or fetch wrapper that adds its own Authorization header breaks a request whose key was correct. Bearer token vs API key explains the two headers.

Whichever you use, keep the key on your server: Sume's docs say there is no browser-safe variant of an API key.