API document

Invocation types for product generation

CodexDock creates owner-scoped AI work through one invocation API. Choose the generation type by the result shape your product needs: text, structured object, file, or image.

Main usage

Pick the result envelope first.

The host sends a prompt plus product context in parameters. The worker returns a validated envelope that matches the requested type.

generate_texttext result

Plain text the product can display immediately.

Use this for captions, summaries, prompts, labels, messages, and other copy where the result is one text field.

Good for
Captions, summaries, prompts, copy
Result shape
kind: "text", text: "..."
generate_objectobject result

Structured data for UI or domain workflows.

Use this when the host needs JSON-shaped output it can validate, render, or pass into product logic.

Good for
Structured UI data or domain objects
Result shape
kind: "object", object: { ... }
generate_filefile result

A generated artifact with a filename and content.

Use this for markdown, source files, docs, config snippets, or any text file the host wants to save or preview.

Good for
Markdown, source files, generated artifacts
Result shape
kind: "file", filename, content
generate_imageimage result

An inline image artifact for product media.

Use this for thumbnails, avatars, previews, and visual assets that should come back as an image result envelope.

Good for
Thumbnails, avatars, visual assets
Result shape
kind: "image", mediaType, base64

Create work

The same invoke shape works for every type.

Change type to select the worker capability and result contract. Use parameters for business context such as usage, count, locale, filename, scene ID, or target path.

Server-side invocation
const invocation = await codexdock.invoke({
  type: "generate_object",
  prompt: "Create four product cards.",
  parameters: { count: 4, usage: "product-preview" },
});

// {
//   invocationId: "inv_123",
//   status: "pending",
//   statusUrl: "/api/codexdock/invocations/inv_123",
//   progress: {
//     phase: "queued",
//     steps: [
//       { key: "received", status: "complete" },
//       { key: "processing", status: "pending" },
//       { key: "result", status: "pending" }
//     ]
//   }
// }

Examples

Use the type that matches the job.

These examples use the same lifecycle: the host creates a pending invocation, a local worker claims it, and the completed result is read from the status URL.

Common invocation types
await codexdock.invoke({
  type: "generate_text",
  prompt: "Write a friendly caption for this scene.",
  parameters: { usage: "scene_caption", tone: "friendly" },
});

await codexdock.invoke({
  type: "generate_object",
  prompt: "Create four product cards.",
  parameters: { usage: "product-preview", count: 4 },
});

await codexdock.invoke({
  type: "generate_file",
  prompt: "Draft concise release notes.",
  parameters: { usage: "release-doc", targetPath: "CHANGELOG.md" },
});

await codexdock.invoke({
  type: "generate_image",
  prompt: "Create a square avatar image.",
  parameters: { usage: "avatar", filename: "avatar.png" },
});

Route reference

Default host endpoints

These paths are defaults, not the security boundary. A host can mount them elsewhere as long as discovery points the CLI to the right URLs.

MethodRoutePurpose
GET/api/codexdock/discoveryReturns the host endpoint manifest used by the CLI.
POST/api/codexdock/pairing/codeCreates a short-lived browser-scoped pairing code.
POST/api/codexdock/pairing/exchangeExchanges a pairing code for an owner-scoped worker token.
POST/api/codexdock/invokeCreates a pending owner-scoped invocation.
GET/api/codexdock/invocations/[invocationId]Reads invocation status and completed results for the owner.
POST/api/codexdock/worker/connectRegisters or refreshes a local worker connection.
GET/api/codexdock/worker/statusReports worker and queue status for operations.
POST/api/codexdock/worker/nextClaims the next matching pending invocation.
POST/api/codexdock/worker/resultSubmits a validated worker result.