API ID Conventions

Workspace Job IDs

A job ID is an opaque string key for the workspace-local job projection. APIs, MCP tools, and browser code accept and return it as jobId / job_id strings. It identifies an entry in the workspace jobs subdoc:

workspace.jobs[job_id] = { url, attributes }

The public/user/API term is job. The hidden shared aggregate is role, and a source listing is an ad. Server-only link/outbox/shared-corpus storage attaches workspace jobs to shared ad and role records; ad_id and role_id stay out of workspace-facing APIs, MCP tools, browser workers, and UI. Those surfaces expose resolved job projections, never direct role/ad access.

Workspace job writes use job.create, job.update, and job.delete.

Validation Rule

Validate job_id as a non-empty string. Do not coerce it to a number or tie API acceptance to a relational table key.

Validation pattern:

const jobIdStr = String(job_id).trim();
if (!jobIdStr) return jsonError('Invalid job_id');
// use jobIdStr in all subsequent SQL binds

Tables and Logs

D1 tables are read models and operational ledgers, not the public workspace job identity contract. Routes that need process state, locks, usage attribution, or file references should first resolve the workspace job projection. Server code that needs shared listing context can then resolve workspace_job_links for the matching (workspace_id, job_id).

If an endpoint receives a valid-looking job_id that is absent from the workspace projection, return a clear job_not_found / skipped response instead of leaking table-specific assumptions to the API caller.