Your generated SDK has Job().create() and no cancel(). The cancel endpoint is in there,
reached by passing $action: 'cancel' to create, so nobody finds it. A caller who drops the
$action posts to /jobs instead. The API answers 400 about a missing template, and the job they
meant to stop keeps running.
What you get
You will end up with a recorded decision per operation, a typed wrapper for the actions, and a check that fails when a regeneration drops or moves one. This is for you if you generate an SDK from a document that is not all CRUD.
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 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 | 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 | 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 | 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() | 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 | 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:
node placement.mjs
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:
node pitfall.mjs
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:
{
"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
documents active: false at entity and path level.
# 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.
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() measures.
prepare() builds the same request without sending it.
node demo.mjs
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.
node coverage.mjs generated/guided
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:
node --test coverage.test.mjs
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:
node coverage.mjs points/guide-v1-4.45.0.json
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 at generation, which
records the pattern in the lock file that Kiota reads on later generations:
"excludePatterns": [
"/health",
"/oauth/token"
],
openapi-typescript 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:
node typecheck.mjs
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 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
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; its
extensions here are quoted from its documentation.
Footnotes
-
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 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 withactive: true. ↩︎ Back to text -
RFC 6749 asks for the client credentials request in
application/x-www-form-urlencoded, the encoding that RFC 1866 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. ↩︎ Back to text