Operation Manifest Reference

What the operation manifest is#

operationManifest is a generated TypeScript array with one entry per OpenAPI operation in openapi/primitive-api.yaml, exported from @primitivedotdev/api-core and re-exported by @primitivedotdev/sdk/api. Each entry (PrimitiveOperationManifest) carries what a caller needs to invoke and describe that operation: command name, HTTP method, path, path/query parameters, and inlined request/response JSON Schemas.

The CLI's generic api-command shortcut and its describe/list-operations helpers are built on this manifest; see Direct API Access and Generic Commands. This page documents the manifest's shape.

Import it directly when you need the raw metadata:

import { operationManifest } from "@primitivedotdev/sdk/api";

for (const operation of operationManifest) {
  console.log(operation.command, operation.method, operation.path);
}

const entry = operationManifest.find((op) => op.operationId === "getAccount");
console.log(entry?.method, entry?.path, entry?.hasJsonBody);

Where it comes from#

generate-openapi-artifacts.ts writes operationManifest to packages/api-core/src/openapi/operations.generated.ts, building it from the raw (pre-normalization) OpenAPI document rather than the codegen JSON. Entries are sorted by tagCommand, then by command. It regenerates whenever you run the codegen pipeline; see Regenerating SDK Code from the OpenAPI Spec. Never edit operations.generated.ts by hand.

PrimitiveOperationManifest fields#

PrimitiveParameterManifest fields#

Each entry in pathParams / queryParams describes one parameter: its name, schema type, whether it's required, and any enum, default, or numeric bounds the spec declares.

Path and query parameters are merged from both the path-item level and the operation level before being split into pathParams / queryParams, so an operation inherits any parameters declared once for the whole path.

requestSchema and responseSchema: fully inlined#

Both schema fields have every $ref into components/schemas and components/parameters recursively resolved and inlined, so a consumer never needs to re-parse the OpenAPI document to understand a shape. Cyclic references are broken by leaving the cyclic occurrence as a bare { $ref: "..." } rather than recursing forever.

primitive list-operations | jq '.[] | select(.command == "send-email") | .requestSchema'

responseSchema targets the useful part of the response: the spec writes success responses as allOf: [SuccessEnvelope, { properties: { data: <real schema> } }] (or the ListEnvelope equivalent). The generator walks that allOf and returns the inlined <real schema> directly, stripping the uniform { success, data, meta } envelope. If an operation stops following that idiom, responseSchema falls back to the full inlined response schema rather than null, since a partial schema is more useful to a caller than none.

Binary responses#

binaryResponse is true for any operation whose responses declare a byte-stream media type or a format: binary schema:

• application/octet-stream
• application/gzip
• message/rfc822
• any response media type schema with format: binary

Use this to decide whether to parse a response as JSON or handle it as a byte stream (for example raw email downloads or payload pulls).

Inspecting a live entry#

To see the real values for any operation, dump its entry from the CLI rather than transcribing it by hand:

primitive list-operations | jq '.[] | select(.tagCommand == "sending")'

Related exports from api-core#

@primitivedotdev/api-core (bundled inline into @primitivedotdev/sdk and primitive; see What is API Core?) also exports:

• openapiDocument, the full raw OpenAPI document as a Record<string, unknown> constant, generated alongside the manifest.
• operations, a namespace object of every generated SDK operation function, keyed by operationId (mirrors the historical shape the CLI's generic command path relies on).
• PrimitiveApiClient, PrimitiveApiError, the host-aware request client and its typed error; see PrimitiveApiClient.
• isMemoryJsonValue, a validator for Primitive Memories values; see Memory Value Validation Helper.

Next steps#