Guides & concepts

Endpoints and services

How a declaration becomes a callable object.

An endpoint config is a plain object. defineEndpoint and defineService are identity functions whose only job is preserving literal types — they do no work at runtime.

const detail = {
  endpoint: 'detail',
  method: 'GET',
  path: '/:id',
  pathParamsSchema: z.object({ id: z.string() }),
  responseSchema: userSchema,
};

Paths are relative

The path is relative to the origin. A service basePath folds into it because that is routing; baseUrl does not, because that is transport. Folding the origin into the path would put your environment inside every cache key and would double up against a fetcher that carries its own baseUrl.

Path parameters

Use :name for required segments and :name? for optional ones. A required segment that is never bound throws before the request is sent. An optional one that is missing disappears from the URL along with its slash.

Cascade order

createApi merges headers, hooks, and default options in the order API → service → endpoint. Later wins for scalar options; for headers and hooks, all of them apply in that order.