# How to handle endpoints that do not map to an entity

> Give each operation that is not a read or write of one resource a decision of its own, and check after each regeneration that the SDK reaches every operation once.

Source: https://voxgig.com/howto/endpoints-that-map-to-no-entity

- Audience: api-producer
- Level: intermediate
- Languages: typescript, go
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Give every operation in the OpenAPI document one of three decisions. It is an entity operation, a function in a hand-written wrapper module over the sdkgen client's direct(), or left out with a reason. Record the decisions in a file and switch the other paths off in the sdkgen guide. After every regeneration, run a check that lists each operation against the generated client and fails on one that is missing, moved, or reached twice.

---
## You will need

Node 22.18 or later, which runs the `.ts` files here directly, an OpenAPI 3 document, and an
sdkgen project generated from it, as
[generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen) sets up. The document here,
`api.json`, describes a Render API with ten operations. Four read and write a job. The other six
are a cancel, a replay, a batch submission, an upload callback, a health check, and a token
exchange. A stand-in for the API runs on 127.0.0.1. The code is TypeScript and JavaScript only: the
Go target was not generated or run for this page. Verified 2026-11-22 against Node 22.23.5.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hand-written wrapper module](https://www.typescriptlang.org/docs/handbook/2/modules.html) | A few actions deserve real names and types beside a client you regenerate | Every function and type is kept by hand, and nothing updates it when the document changes | The actions change every release, faster than anyone edits the module |
| [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/using) | You want every path reachable as a typed chain, with exclusions recorded | Names follow the path, so cancel is `jobs.byJobId(id).cancel.post()`, plus runtime packages | Callers want domain-named methods rather than path chains |
| [openapi-typescript and openapi-fetch](https://openapi-ts.dev/openapi-fetch/) | A TypeScript client where every path stays typed and nothing is classified | Callers spell each path and method themselves, and get no entity objects or retries | You ship more than TypeScript, or want entity-shaped calls |
| [sdkgen direct() and prepare()](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/operation-pipeline.md) | The SDK is generated by sdkgen and an operation fits no entity | No type checks the path, parameters, or body, and features that hook entity operations do not run | The action needs a name and types, which the wrapper gives it |
| [Speakeasy custom methods](https://www.speakeasy.com/docs/sdks/customize/methods) | Speakeasy generates the SDK and you can add extensions to the document | An account, and one extension written into the document per operation you rename or hide | You cannot edit the document, or want generation with no vendor account |

Voxgig maintains sdkgen, the worked path on this page and one of five options in the table.

Kiota and openapi-fetch never classify, so nothing they generate can land on the wrong entity, and
their price is that callers address every operation by its path. sdkgen's entity model reads
better for the four job operations, and its price is the decision this page records for the
other six. Speakeasy names each operation through an extension, which costs edits to the document
and a vendor account.

## Read where apidef put each operation

apidef is the model step inside sdkgen. With the scaffold's guide it placed every operation of
`api.json` somewhere, and `placement.mjs` prints where, on the release a scaffold installs and on
the newest:

```bash
node placement.mjs
```

```text output
operation                          sdkgen 4.44.3, apidef 8.32.4    sdkgen 4.45.0, apidef 8.33.1
GET /jobs                          job.list                        job.list
POST /jobs                         job.create                      job.create
GET /jobs/{jobId}                  job.load                        job.load
DELETE /jobs/{jobId}               job.remove                      job.remove
POST /jobs/{jobId}/cancel          job.create $action=cancel       job.create $action=cancel
POST /jobs/{jobId}/replay          job.create $action=replay       job.create $action=replay
POST /jobs/batch                   batch.create                    job.create $action=batch   <- moved
POST /uploads/{uploadId}/complete  upload.create $action=complete  upload.create $action=complete
GET /health                        health.load                     health.load
POST /oauth/token                  no entity                       no entity
sdkgen 4.44.3, apidef 8.32.4: 4 entities (batch, health, job, upload)
sdkgen 4.45.0, apidef 8.33.1: 3 entities (health, job, upload)
```

On this document the heuristic placed nine of the ten operations on an entity. A trailing literal
after a job id became an action on `create`. The health check became an entity of its own. The upload
callback became an `upload` entity whose create has only an action, which both releases report
as a `PARTIAL BUILD` warning. The token exchange is the one operation with no entity: the base
guide switches it off under the comment `Deactivated by the heuristic (auth-exchange)`.[^1]

The batch is the one that moved. A regeneration on 4.45.0 removes `Batch()` from the client and
puts the same call on `Job().create({ $action: 'batch' })`.

## See the method name nobody guesses

The unguided client exposes seven entity methods, and `pitfall.mjs` runs three calls a reader
might try:

```bash
node pitfall.mjs
```

```text output
entity methods: Batch().create, Health().load, Job().create, Job().list, Job().load, Job().remove, Upload().create
a method named cancel, replay, complete or batch: none
Job().create({ id: 'j1', $action: 'cancel' })
  -> {"id":"j1","template":"invoice","status":"cancelled"}
  sent: POST /v1/jobs/j1/cancel
Job().create({ id: 'j2' }), the $action left out
  -> rejected: RenderSDK: create: request: 400: Bad Request
  sent: POST /v1/jobs
Upload().create({ id: 'u1', etag: 'e1' }), the $action left out
  -> rejected: RenderSDK: create: Operation "create" has only action endpoints; pass $action to choose one.
  sent: nothing
afterwards: j1 cancelled, j2 queued, 2 jobs on the server
```

A cancel is not a create, and the client says so only when the caller already knows the selector.
Without it, the call reaches the create route, the 400 talks about templates, and `j2` stays
queued. The upload entity fails earlier and more helpfully, because it has no plain create to fall
back on. `runtime-probe.mjs`, which `generate.sh` runs on the unguided client of each release,
recorded the same two failures on 4.45.0.

## Record a decision for every operation

Write the decision down per operation, keyed by `operationId`, in a file the check reads. Three
kinds cover this document:

```json title="decisions.json"
{
  "listJobs": { "use": "entity", "at": "job.list" },
  "createJob": { "use": "entity", "at": "job.create" },
  "getJob": { "use": "entity", "at": "job.load" },
  "deleteJob": { "use": "entity", "at": "job.remove" },
  "cancelJob": { "use": "wrapper", "at": "cancelJob" },
  "replayJob": { "use": "wrapper", "at": "replayJob" },
  "submitJobBatch": { "use": "wrapper", "at": "submitJobBatch" },
  "completeUpload": { "use": "wrapper", "at": "completeUpload" },
  "getHealth": { "use": "excluded", "why": "probed by the load balancer, not by SDK callers" },
  "exchangeToken": { "use": "excluded", "why": "callers bring a token from their OAuth library" }
}
```

Force an operation onto an entity only when it reads or writes that one record, as the four job
operations do. Give an action a function of its own when a caller will look for it by its verb.
Leave an operation out when an SDK user never calls it. A health check belongs to the load
balancer, and the token request wants a form body that an OAuth library already sends.[^2]

## Take the actions out of the model and wrap them

The guide entry file, `.sdk/model/guide/guide.aontu` in the project, switches the non-entity paths
off. The [guide reference](https://github.com/voxgig/apidef/blob/main/docs/reference/guide.md)
documents `active: false` at entity and path level.

```aontu title="render-guide.aontu"
# Keep only the reads and writes of one job in the entity model.
# decisions.json says where every other operation goes instead.
guide: entity: health: active: false
guide: entity: batch: active: false
guide: entity: upload: active: false
guide: entity: job: path: "/jobs/{jobId}/cancel": active: false
guide: entity: job: path: "/jobs/{jobId}/replay": active: false
guide: entity: job: path: "/jobs/batch": active: false
```

The last line names the path where 4.45.0 puts the batch. The guide on 4.44.3 needs only the
`batch` line, and a guide written that way stops holding on the next release.

`render-actions.ts` gives each of the four a typed function over `direct()`, which sends with the
client's base URL and token. It throws on an error status, because `direct()` resolves instead.

```ts title="render-actions.ts"
async function send<T>(client: DirectClient, route: RouteName, params?: Record<string, string>, body?: unknown): Promise<T> {
  const { method, path } = ROUTES[route]
  const req: DirectRequest = { path, method }
  if (params) req.params = params
  if (body !== undefined) req.body = body
  // direct() resolves on an error status instead of throwing, so the check is ours.
  const res = await client.direct(req)
  if (!res.ok) throw new RenderActionError(route, res.status, res.data)
  return res.data as T
}

export function cancelJob(client: DirectClient, jobId: string): Promise<Job> {
  return send<Job>(client, 'cancelJob', { jobId: segment('jobId', jobId) })
}
```

`segment` refuses an empty id, because `direct()` on 4.44.3 and on 4.45.0 sends one as
`/jobs//cancel`. `direct()` also
skips the features that hook entity operations, such as the idempotency key, as
[calling an endpoint with direct()](/howto/call-an-unmodelled-endpoint-with-direct) measures.
`prepare()` builds the same request without sending it.

```bash
node demo.mjs
```

```text output
client.Job().create({ template: 'receipt' })  j2 queued
client.Job().list()                           2 jobs
cancelJob(client, 'j1')                       cancelled
replayJob(client, 'j1')                       j3 queued
submitJobBatch(client, [two inputs])          b1, 2 accepted
completeUpload(client, 'u1', 'etag-9')        recorded
cancelJob(client, 'j1') a second time         RenderActionError, status 409
client.prepare({ ...cancel, jobId: 'j2' })    POST /v1/jobs/j2/cancel, requests sent: 0
requests the stand-in received:
  POST /v1/jobs
  GET /v1/jobs
  POST /v1/jobs/j1/cancel
  POST /v1/jobs/j1/replay
  POST /v1/jobs/batch
  POST /v1/uploads/u1/complete
  POST /v1/jobs/j1/cancel
```

## Check it worked

`coverage.mjs` reads `api.json`, `decisions.json`, the wrapper's route table, and the operation
points of the compiled client. It fails on an operation with no decision and on an entity method
that does not reach its route. It also fails on a wrapper route that differs from the document,
and on an operation the model places somewhere the decisions do not expect.

```bash
node coverage.mjs generated/guided
```

```text output
api.json: 10 operations, against generated/guided
  GET    /jobs                         listJobs        entity    job.list
  POST   /jobs                         createJob       entity    job.create
  GET    /jobs/{jobId}                 getJob          entity    job.load
  DELETE /jobs/{jobId}                 deleteJob       entity    job.remove
  POST   /jobs/{jobId}/cancel          cancelJob       wrapper   cancelJob
  POST   /jobs/{jobId}/replay          replayJob       wrapper   replayJob
  POST   /jobs/batch                   submitJobBatch  wrapper   submitJobBatch
  POST   /uploads/{uploadId}/complete  completeUpload  wrapper   completeUpload
  GET    /health                       getHealth       left out  probed by the load balancer, not by SDK callers
  POST   /oauth/token                  exchangeToken   left out  callers bring a token from their OAuth library
ok: 4 on an entity, 4 in render-actions.ts, 2 left out
```

The tests run the checker on all six recorded builds and feed it one removal and one change of
each kind. Among them are a dropped point, an operation moved or reached twice, a second method on
a path, and a document with no operations. They also send every wrapper call to the stand-in:

```bash
node --test coverage.test.mjs
```

```text output
1..18
# tests 18
# suites 0
# pass 18
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

## When it goes wrong

The batch is reached twice after an upgrade. The guide said `batch: active: false`, which holds on
4.44.3, but 4.45.0 files the batch under `job` instead. Run the check on every regeneration:

```bash
node coverage.mjs points/guide-v1-4.45.0.json
```

```text output
api.json: 10 operations, against points/guide-v1-4.45.0.json
  GET    /jobs                         listJobs        entity    job.list
  POST   /jobs                         createJob       entity    job.create
  GET    /jobs/{jobId}                 getJob          entity    job.load
  DELETE /jobs/{jobId}                 deleteJob       entity    job.remove
  POST   /jobs/{jobId}/cancel          cancelJob       wrapper   cancelJob
  POST   /jobs/{jobId}/replay          replayJob       wrapper   replayJob
  POST   /jobs/batch                   submitJobBatch  wrapper   submitJobBatch
  POST   /uploads/{uploadId}/complete  completeUpload  wrapper   completeUpload
  GET    /health                       getHealth       left out  probed by the load balancer, not by SDK callers
  POST   /oauth/token                  exchangeToken   left out  callers bring a token from their OAuth library
FAIL: 1 problem
  submitJobBatch: the model also places POST /jobs/batch on job.create ($action batch)
```

A new endpoint ships with no decision. The checker names it as `has no decision` and exits 1. Add
the line to `decisions.json` before the release, not after a caller asks.

A wrapper function keeps a path the API has renamed. The checker compares each route in
`render-actions.ts` with the document and prints both paths. `direct()` itself would send the
former path and return the 404 as a result.

## Reach the same operations with Kiota and openapi-fetch

Kiota maps paths rather than entities. Every path becomes a request builder, so the cancel is
`client.jobs.byJobId('j1').cancel.post()`, and the batch is `client.jobs.batch.post(inputs)`.
To leave an operation out, pass
[`--exclude-path`](https://learn.microsoft.com/en-us/openapi/kiota/using) at generation, which
records the pattern in the lock file that Kiota reads on later generations:

```json title="kiota-trimmed/kiota-lock.json"
  "excludePatterns": [
    "/health",
    "/oauth/token"
  ],
```

[`openapi-typescript`](https://openapi-ts.dev/introduction) writes one `paths` type, and
openapi-fetch calls `client.POST('/jobs/{jobId}/cancel', ...)` against it. A path that is not in
the document does not compile, which `direct()` cannot offer. `typecheck.mjs` compiles a caller
for each tool that makes all ten calls, and a mistyped cancel:

```bash
node typecheck.mjs
```

```text output
kiota-calls.ts: ok
openapi-fetch/calls.ts: ok
render-actions.ts: ok
openapi-fetch/typo.ts: tsc exit 2
  openapi-fetch/typo.ts(6,19): error TS2345: Argument of type '"/jobs/{jobId}/cancle"' is not assignable to parameter of type 'PathsWithMethod<paths, "post">'.
```

Neither tool needs a decision file to keep an operation reachable. Either still needs one to say
which operations a caller should use: the health check and the token exchange are as typed as
the cancel. Speakeasy puts that decision in the document, with
[`x-speakeasy-group`](https://www.speakeasy.com/docs/sdks/customize/structure/namespaces) and
`x-speakeasy-name-override` to name a method and `x-speakeasy-ignore: true` to drop one.

## When not to do this

Do not force an action onto the nearest entity to save a wrapper. `Job().create({ $action })` has
the shape of a write and the behavior of a command, and a reader looks for the command.

Do not keep a wrapper module for an API whose actions outnumber its resources. The module is
updated by hand on every change, and sdkgen's entity model buys little when four of ten operations
fit it. Kiota or openapi-fetch reach every path with types and nothing to maintain, which suits
that API better.

Do not trust a guide across an upgrade of `@voxgig/apidef`. The batch moved between two releases,
and the guide that kept it out on one let it back in on the next.

Do not skip the check because the generate step printed no warning. The moved batch produced
none.

## Related how-tos

- [Classify OpenAPI operations into CRUD kinds by path shape](/howto/classify-openapi-operations-by-path-shape)

- [Decide if an endpoint is an entity operation or an action](/howto/entity-operation-or-standalone-action)

- [Call an endpoint your SDK does not model with direct()](/howto/call-an-unmodelled-endpoint-with-direct)

- [Expose an escape hatch for endpoints an SDK does not model](/howto/escape-hatch-for-unmodelled-endpoints)

- [Diff two semantic models from successive spec versions](/howto/diff-two-semantic-models-across-versions)

- [Call a non-entity endpoint from a generated tool layer](/howto/call-a-non-entity-endpoint-from-a-tool)

- [Reconcile an extracted entity model with a domain model](/howto/reconcile-an-extracted-model-with-a-domain-model)

## Last verified

Verified 2026-11-22 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3
with `@voxgig/apidef` 8.32.4, and the same project upgraded to 4.45.0 with 8.33.1, Kiota 1.39.0,
`openapi-typescript` 7.13.0, `openapi-fetch` 0.17.0, and TypeScript 5.9.3. Every output block is
what the command preceding it printed. The Kiota caller was type-checked and never sent a request,
while the openapi-fetch caller also ran against the stand-in in a test. No Go was run. Generation ran once, in `generate.sh`, and its output is
committed. Speakeasy was not run, because its CLI
[needs an account](https://www.speakeasy.com/docs/speakeasy-reference/cli/getting-started); its
extensions here are quoted from its documentation.

[^1]: An OAuth token endpoint is a sensible thing for a heuristic to recognize and decline. Its
request body is defined elsewhere, by
[RFC 6749 section 4.4.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4.2) for the
client credentials grant, and its answer is a credential rather than a record. The base guide
says so in a comment and sets `active: *false`, a default the guide entry file can override with
`active: true`.

[^2]: RFC 6749 asks for the client credentials request in `application/x-www-form-urlencoded`,
the encoding that
[RFC 1866 section 8.2.1](https://www.rfc-editor.org/rfc/rfc1866.html#section-8.2.1), the HTML 2.0
specification of November 1995, made the default for every form. A token endpoint therefore reads
the encoding a browser used to submit a form in 1995. The openapi-fetch caller here posts it
through a form serializer, where every other operation takes JSON.