An API is the network contract. An SDK is a language-specific library that wraps it. Below is the same Tuteliq call in raw REST, Python, and TypeScript, plus guidance on when to pick which.
TL;DR
- API = HTTPS endpoints you call directly. Any language, any runtime, no dependency.
- SDK = a library that wraps the API in typed methods for a specific language. Faster to integrate, less boilerplate.
- Tuteliq ships both. Same API key, same endpoints, same billing. Pick whichever your team ships fastest with.
The same call, three ways
Below is the same grooming detection call, a real Tuteliq endpoint, expressed in the raw REST API, the Python SDK, and the TypeScript SDK. The request body and response are identical.
Works in any language, any runtime. You manage auth, retries, timeouts, and JSON parsing yourself.
ALL THREE RETURN THE SAME JSON
When to use each
Pick per component, not per project. Most Tuteliq customers use the SDK in their main app and the raw API in scripts, webhooks, or edge runtimes.
Situation
Raw API
SDK
Your language is Python or TypeScript
Your language is Go, Rust, Ruby, PHP, Swift
You want typed responses and IDE autocomplete
You're writing a one-off backfill script
You want built-in retries and connection pooling
You're in a size-constrained edge runtime
You need full control over HTTP behavior
You're integrating in production and want it done today
Your app receives Tuteliq webhooks
You're prototyping and want minimum boilerplate
What the SDK does that the API doesn't
Typed request and response
Autocomplete for every field, compile-time errors when a payload is wrong. The raw API returns JSON; you type it yourself.
Authentication
The SDK reads TUTELIQ_API_KEY, attaches the Authorization header, and rotates on 401. With the raw API you handle all three.
Retries and backoff
Idempotent calls retry with exponential backoff on 429 and 5xx. curl gives up on the first failure.
Connection pooling
Reuses HTTPS connections across calls: measurably faster in hot loops. Each curl invocation opens a fresh TLS session.
Pagination helpers
List endpoints expose async iterators (`for await ... of tuteliq.incidents.list()`) instead of manual cursor management.
Error types
Distinguishes RateLimitError, AuthError, ValidationError, and ServerError. Raw responses require status-code parsing.
Frequently asked questions
The most common questions developers ask when picking between an API and an SDK.
Ready to integrate?
Whichever path you pick, start with the getting started guide: same API key works for both.