APIs, CLIs & SDKs

An API stops being yours the moment someone integrates against it. Resource names, response shapes, and what a field means under load are decided once and then lived with, so they are worth arguing about before the first endpoint ships rather than in a deprecation notice afterwards.

Vector exposes just over a hundred versioned endpoints across nine groups. Every response shares one envelope, so a client parses one shape, and the errors are predictable enough to program against.

Authentication is the easy half. The question that decides whether an integration is safe is what a credential can do once it is authenticated — and whether a partner can hand one to a cron job without also handing it the ability to delete production.

Vector issues tokens with abilities scoped per resource and per action, so a partner can mint a key that lists sites but cannot delete them. Rate limits are set by category rather than one global bucket: the calls that cost real infrastructure are throttled hard while read-heavy workflows stay fast. Every query is scoped to the authenticated account, because an unscoped one should be difficult to write by accident.

Provisioning a server, running a migration, building an image — none of it fits inside a request. The design question is not how to make it faster. It is how the caller finds out it finished, and what they are meant to do with a job that has been running for four minutes.

Vector's provisioning API dispatches a job on every endpoint and POSTs a signed callback when it terminates. Helix used four dispatch mechanisms depending on what the caller needed to know: synchronous REST for flat resources, a queue with an HTTP callback for slow lifecycle work, fire-and-forget for anything with nobody waiting, and a pull-based configuration API for the server fleet. More on platforms & hosting and automation & AI workflows.

The API calling the customer back is still the API, and it is the half that gets built last and tested least. It needs a signature the receiver can verify, a retry schedule that gives up eventually, and a delivery log for the afternoon somebody insists the event never arrived.

Vector publishes more than fifty event types, signed HMAC-SHA256 over a timestamped payload and compared in constant time, with a five-minute replay window, exponential backoff to a delivery cap, rotatable secrets, and a queryable delivery history. Inbound callbacks from the build pipeline and the container scheduler are verified the same way.

Hand-written API docs are wrong within a quarter. Not through carelessness — the code simply has somewhere else to be. The only reference that stays true is the one generated from the thing it describes.

Vector's reference is generated from the codebase, exported as OpenAPI and Postman, and synced across repositories on every change. It is published on this site at /docs/api/, and the data behind it carries a never-hand-edit contract so nobody can helpfully correct a generated file.

SDKs and CLIs get treated as documentation with a build step. They are the API's first real users, and the place its design flaws surface before a customer has to find them.

Vector ships a Go CLI covering the full surface — readable tables in a terminal, clean JSON when piped, credentials in the OS keychain, structured exit codes for scripting — alongside typed Node and PHP SDKs. If the SDK is awkward to use, the API is wrong, and we find out before a partner does.