SDK reference

Every method across every supported language. Pick TypeScript, Python, C#, Go, or Rust at any code block — the operation is identical, only syntax differs. All SDKs are projections of one canonical contract backbone.

⌘ Kor/to search every method, command, and endpoint

OverviewSDK overviewLanguage packages, setup, side-by-side samples, and generated client behavior.SDKSDK reference modelGenerated namespaces, compatibility taxonomy, language parity, retries, pagination, and manifest enforcement.SurfacesProject capability surfacesProject-authored, project-published, project-installed capability surfaces across manifests, grants, exposure bindings, PCG, SDK, CLI, MCP, and usage evidence.RESTREST controller atlasEvery controller-backed endpoint with parameters, request examples, responses, errors, and samples.RESTREST API modelBase URLs, resource conventions, pagination, idempotency, error envelopes, OpenAPI discovery, and examples.ErrorsErrors referenceCanonical error envelopes, HTTP status mapping, machine-readable codes, reason codes, and correlation IDs.LimitsLimits & quotasRate limits, hard and soft quotas, budget enforcement, usage metering, and retry guidance.

Client

Initialize the canonical client. One configuration reaches every surface — entities, workflows, agents, realtime, governed connections.

`client.createClient`

createClient(options): VadylClient

Create a configured Vadyl client bound to a project.

Returns a fully-typed client. Tenant + project headers are auto-attached to every request. Optionally pin a feature branch.

Parameters

Name	Type	Description
`apiUrl`required	string	Base URL — e.g. https://api.vadyl.app/v1
`token`required	string	Bearer token from your identity provider, or API key/secret pair.
`tenant`required	string	Organization slug (sent as X-Vadyl-Tenant).
`project`required	string	Project slug or canonical id (sent as X-Vadyl-Project).
`branch`	string?	Feature branch override — pin to sandbox/preview.
`fetch`	Fetch?	Custom fetch implementation. Defaults to global fetch.
`telemetry`	TelemetryOpts?	Hook into the canonical observability envelope.

Returns

VadylClientTyped client with namespaces: entities, workflows, agents, connections, events, identity, surfaces.

client-createClient.example

import { createClient } from "@vadyl/sdk";
const vadyl = createClient({
  apiUrl:  "https://api.vadyl.app/v1",
  token:   process.env.VADYL_TOKEN!,
  tenant:  "acme",
  project: "billing",
});

Sample output

{
  "namespace": "client",
  "method": "createClient",
  "id": "res_123",
  "state": "active"
}

Entities

Read, create, update, delete, query, expand, and watch any canonical entity. Same surface across every storage substrate.

`entities.list`

entities.<Entity>.list(opts?): Page<T>

List entity rows with typed filters, sorting, pagination, and relation expansion.

Parameters

Name	Type	Description
`filter`	Filter<T>	Typed predicate — eq / ne / gt / lt / in / between / like / isNull / and / or / not.
`sort`	Sort[]	Multi-field ordering.
`pageSize`	number	Items per page (default 50, max 200).
`cursor`	string	Cursor for forward pagination (preferred over page numbers).
`include`	string[]	Eagerly expand relations: e.g. ['customer', 'items.product'].
`fields`	string[]	Sparse projection — only requested fields are returned.
`includeTotal`	boolean	Include totalCount in response (extra round-trip on some substrates).

Returns

Page<T>{ data: T[], page: { number, size, totalCount?, next?, prev? } }

Errors

Code	Description
`ACCESS_DENIED`	The actor lacks read on Entity or doesn't satisfy the row filter.
`VALIDATION_FAILED`	Filter expression references a field that doesn't exist on Entity.
`QUOTA_EXCEEDED`	Project read quota exhausted.

entities-list.example

const recent = await vadyl.orders.list({
  filter: { status: { in: ["paid", "fulfilled"] }, total: { gt: 100 } },
  sort:     [{ field: "createdAt", direction: "desc" }],
  pageSize: 50,
  include:  ["customer"],
});

Sample output

{
  "data": [{ "id": "res_123", "state": "active" }],
  "page": { "size": 50, "next": "cur_1" }
}

`entities.read`

entities.<Entity>.read(id, opts?): T

Read one entity by primary key.

Parameters

Name	Type	Description
`id`required	string	Primary-key value (single or composite).
`include`	string[]	Relations to expand.

Returns

TThe entity row, or throws NOT_FOUND.

Errors

Code	Description
`NOT_FOUND`	No row matches the primary key (or the actor cannot read it under access policy).
`ACCESS_DENIED`	Field-level read denied; partial result is masked or omitted.

entities-read.example

const order = await vadyl.orders.read("ord_abc", { include: ["customer"] });

Sample output

{
  "namespace": "entities",
  "method": "read",
  "id": "res_123",
  "state": "active"
}

`entities.create`

entities.<Entity>.create(input, opts?): T

Create a row. Idempotent when an idempotency key is provided.

Parameters

Name	Type	Description
`input`required	EntityCreateInput	Field values for the new row.
`idempotencyKey`	string	Safe-to-retry idempotency key (recommended for client-driven inserts).
`include`	string[]	Relations to expand on the returned row.

Returns

TThe persisted row with generated fields filled (id, timestamps, etc.).

Errors

Code	Description
`VALIDATION_FAILED`	Required field missing, type mismatch, or invariant violated.
`CONFLICT`	Unique-key violation. Inspect error.field.
`ACCESS_DENIED`	Insert-check policy denied the row's contents.

entities-create.example

const customer = await vadyl.customers.create(
  { email: "ada@example.com", name: "Ada Lovelace" },
  { idempotencyKey: `signup:${session.id}` },
);

Sample output

{
  "namespace": "entities",
  "method": "create",
  "id": "res_123",
  "state": "active"
}

`entities.update`

entities.<Entity>.update(id, patch, opts?): T

Partial update with optimistic concurrency support.

Parameters

Name	Type	Description
`id`required	string	Primary key of the row.
`patch`required	EntityUpdateInput	Fields to update (partial).
`ifMatch`	string	Expected ConcurrencyToken — write fails CONFLICT if changed.

Returns

TThe updated row.

Errors

Code	Description
`NOT_FOUND`	Row missing.
`CONFLICT`	ifMatch mismatch — re-read and retry.
`ACCESS_DENIED`	Update target filter excludes this row, or update result check failed.
`VALIDATION_FAILED`	Patch contents fail validation.

entities-update.example

const updated = await vadyl.customers.update(
  customer.id,
  { name: "Ada L." },
  { ifMatch: customer.concurrencyToken },
);

Sample output

{
  "namespace": "entities",
  "method": "update",
  "id": "res_123",
  "state": "active"
}

`entities.upsert`

entities.<Entity>.upsert(input, opts?): T

Insert if absent, update if present (matched on uniqueKeys).

Parameters

Name	Type	Description
`input`required	EntityUpsertInput	Full row contents.
`matchOn`	string[]	Unique-key field names to match on. Defaults to declared natural key.
`idempotencyKey`	string	Idempotency key.

Returns

TThe resulting row.

entities-upsert.example

const stat = await vadyl.dailyStats.upsert(
  { date: "2026-05-08", visits: 1234 },
  { matchOn: ["date"] },
);

Sample output

{
  "namespace": "entities",
  "method": "upsert",
  "id": "res_123",
  "state": "active"
}

`entities.delete`

entities.<Entity>.delete(id, opts?): void

Delete a row. Soft-delete on entities with that lifecycle, hard otherwise.

Parameters

Name	Type	Description
`id`required	string	Primary key.
`ifMatch`	string	Optimistic concurrency token.
`force`	boolean	Hard-delete a soft-delete entity (admin-gated).

Returns

void

Errors

Code	Description
`NOT_FOUND`	Row missing or already deleted.
`CONFLICT`	Foreign-key restrict; remove dependents first.
`ACCESS_DENIED`	Delete-filter rejected the row.

entities-delete.example

await vadyl.customers.delete(customer.id);

Sample output

undefined

`entities.count`

entities.<Entity>.count(filter?): number

Count rows matching a filter without loading them.

Parameters

Name	Type	Description
`filter`	Filter<T>	Same filter syntax as list().

Returns

number

entities-count.example

const n = await vadyl.orders.count({ status: { eq: "pending" } });

Sample output

`entities.exists`

entities.<Entity>.exists(id): boolean

Check existence without loading the row.

Parameters

Name	Type	Description
`id`required	string	Primary key.

Returns

boolean

entities-exists.example

if (await vadyl.customers.exists("c_abc")) { ... }

Sample output

true

`entities.subscribe`

entities.<Entity>.subscribe(opts?): Subscription<ChangeEvent>

Live subscription to entity change events. Field NAMES only — re-read for values.

Parameters

Name	Type	Description
`filter`	Filter<T>	Same predicate AST as list().
`kinds`	ChangeKind[]	Event kinds: 'created' \| 'updated' \| 'deleted'.

Returns

Subscription<ChangeEvent>An async iterable of change events. Reconnect-safe.

entities-subscribe.example

const sub = vadyl.orders.subscribe({ filter: { status: { eq: "paid" } } });
for await (const evt of sub.events()) { console.log(evt.kind, evt.entityId); }

Sample output

{
  "kind": "updated",
  "entityId": "res_123",
  "changedFields": ["state"]
}

`entities.batchCreate`

entities.<Entity>.batchCreate(rows, opts?): BatchResult<T>

Insert many rows efficiently, with per-row idempotency.

Parameters

Name	Type	Description
`rows`required	EntityCreateInput[]	Up to 1000 rows per batch.
`atomic`	boolean	If true, all-or-nothing transactional batch.

Returns

BatchResult<T>{ inserted: T[], failed: { row, error }[] }

entities-batchCreate.example

await vadyl.products.batchCreate(rows, { atomic: true });

Sample output

{
  "namespace": "entities",
  "method": "batchCreate",
  "id": "res_123",
  "state": "active"
}

Workflows

Start, signal, query, and replay durable workflows. Long-running orchestration that survives process restart.

`workflows.start`

workflows.<Name>.start(input, opts?): Run

Start a new workflow run, pinned to current publication.

Parameters

Name	Type	Description
`input`required	WorkflowInput	Typed input to the workflow.
`idempotencyKey`	string	Idempotency key for safe retries.
`delay`	Duration	Schedule the start in the future.

Returns

WorkflowRun{ id, status, startedAt }

workflows-start.example

const run = await vadyl.workflows.fulfillOrder.start({ orderId: "ord_abc" });

Sample output

{
  "namespace": "workflows",
  "method": "start",
  "id": "res_123",
  "state": "active"
}

`workflows.signal`

workflows.<Name>.signal(runId, signalName, payload?): void

Send a signal to a running workflow (for ctx.waitForSignal).

Parameters

Name	Type	Description
`runId`required	string	Workflow run id.
`signalName`required	string	Name of the signal channel the workflow is awaiting.
`payload`	any	Typed signal payload.

Returns

void

workflows-signal.example

await vadyl.workflows.fulfillOrder.signal(run.id, "shipped", { trackingNumber: "1Z..." });

Sample output

undefined

`workflows.query`

workflows.<Name>.query(runId): RunState

Inspect run state and step history.

Parameters

Name	Type	Description
`runId`required	string	Workflow run id.

Returns

RunState{ status, steps, currentStep, history, signals, compensations, error? }

workflows-query.example

const state = await vadyl.workflows.fulfillOrder.query(run.id);

Sample output

{
  "namespace": "workflows",
  "method": "query",
  "id": "res_123",
  "state": "active"
}

`workflows.cancel`

workflows.<Name>.cancel(runId, reason?): void

Cancel an in-flight run; runs registered compensations.

Parameters

Name	Type	Description
`runId`required	string	Workflow run id.
`reason`	string	Audit reason.

Returns

void

workflows-cancel.example

await vadyl.workflows.fulfillOrder.cancel(run.id, "customer requested");

Sample output

undefined

`workflows.list`

workflows.<Name>.list(opts?): Page<Run>

List runs with filter, sort, pagination.

Parameters

Name	Type	Description
`filter`	RunFilter	Filter by status, startedAt range, etc.
`pageSize`	number	Items per page.
`cursor`	string	Pagination cursor.

Returns

Page<WorkflowRun>

workflows-list.example

const failed = await vadyl.workflows.fulfillOrder.list({ filter: { status: { eq: "failed" } } });

Sample output

{
  "data": [{ "id": "res_123", "state": "active" }],
  "page": { "size": 50, "next": "cur_1" }
}

Agents

Run native agents, recall memory, expose tools through MCP. Capability-aware model routing, typed plan IR, dedup-safe memory.

`agents.run`

agents.<Name>.run(input): AgentRun

Trigger an agent run.

Parameters

Name	Type	Description
`prompt`required	string	Natural-language prompt.
`userId`	string	Acting user (for memory scoping + audit).
`budget`	AgentBudget	{ maxTokens, maxToolCalls } overrides.
`stream`	boolean	Stream step events as they complete.

Returns

AgentRun{ id, status, plan, steps, tokens, cost }

agents-run.example

const run = await vadyl.agents.SupportAgent.run({
  prompt: "Refund order #12345 due to defect",
  userId: session.userId,
  budget: { maxTokens: 50000, maxToolCalls: 30 },
});

Sample output

{
  "namespace": "agents",
  "method": "run",
  "id": "res_123",
  "state": "active"
}

`agents.stream`

agents.<Name>.stream(runId): AsyncIterable<Step>

Stream step-by-step progress of a run.

Parameters

Name	Type	Description
`runId`required	string	Agent run id.

Returns

AsyncIterable<AgentStep>

agents-stream.example

for await (const step of vadyl.agents.SupportAgent.stream(run.id)) { console.log(step.kind); }

Sample output

{
  "kind": "updated",
  "entityId": "res_123",
  "changedFields": ["state"]
}

`agents.memory.recall`

agents.<Name>.memory.recall(opts): Fact[]

Recall facts from agent memory by predicate.

Parameters

Name	Type	Description
`kind`	string	Fact kind.
`subject`	string	Subject id (e.g. user id).
`asOf`	string	ISO time — replay-stable temporal recall.

Returns

Fact[]

agents-memory.recall.example

const facts = await vadyl.agents.SupportAgent.memory.recall({ kind: "preference", subject: userId });

Sample output

{
  "namespace": "agents",
  "method": "memory.recall",
  "id": "res_123",
  "state": "active"
}

`agents.memory.record`

agents.<Name>.memory.record(fact): Fact

Record a new memory fact (immutable; supersedable).

Parameters

Name	Type	Description
`kind`required	string	Fact kind.
`subject`required	string	Subject id.
`body`required	object	Fact body.

Returns

Fact

agents-memory.record.example

await vadyl.agents.SupportAgent.memory.record({
  kind: "preference", subject: userId, body: { theme: "dark" },
});

Sample output

{
  "namespace": "agents",
  "method": "memory.record",
  "id": "res_123",
  "state": "active"
}

`agents.memory.supersede`

agents.<Name>.memory.supersede(factId, body): Fact

Supersede a prior fact (the prior fact is preserved with ValidUntil set).

Parameters

Name	Type	Description
`factId`required	string	Existing fact id.
`body`required	object	New fact body.

Returns

Fact

agents-memory.supersede.example

await vadyl.agents.SupportAgent.memory.supersede(factId, { theme: "system" });

Sample output

{
  "namespace": "agents",
  "method": "memory.supersede",
  "id": "res_123",
  "state": "active"
}

`agents.tokenAccounting.preflight`

agents.<Name>.tokenAccounting.preflight(opts): PreflightResult

Check before invoking a model whether the projected spend fits the run budget.

Returns

PreflightResult{ allowed, reason?, residual }

agents-tokenAccounting.preflight.example

const ok = await vadyl.agents.SupportAgent.tokenAccounting.preflight({ runId, modelId, estimatedInputTokens: 4000, estimatedOutputTokens: 1500 });

Sample output

{
  "namespace": "agents",
  "method": "tokenAccounting.preflight",
  "id": "res_123",
  "state": "active"
}

Connections

Invoke governed connections — the only way authored code reaches external services.

`connections.invoke`

connections.<name>.<operation>(input, opts?): Result

Invoke a typed governed-connection operation.

Parameters

Name	Type	Description
`input`required	OperationInput	Typed payload — schema depends on the connection definition.
`idempotencyKey`	string	Forwarded to upstream as the provider's idempotency header.

Returns

ResultTyped response from the upstream provider.

connections-invoke.example

const charge = await ctx.connections.stripe.createCharge({
  amount: 2999, currency: "usd", customer: "cus_abc",
  idempotencyKey: `charge:${order.id}`,
});

Sample output

{
  "namespace": "connections",
  "method": "invoke",
  "id": "res_123",
  "state": "active"
}

Events

Publish canonical platform events; consumers are wired through the outbox-backed substrate.

`events.emit`

events.emit(kind, payload, opts?): EventReceipt

Emit a canonical event. Goes through transactional outbox.

Parameters

Name	Type	Description
`kind`required	string	Event type, e.g. 'order.paid'.
`payload`required	object	Event body.
`correlationId`	string	Trace/correlation id.

Returns

EventReceipt{ id, kind, occurredAt }

events-emit.example

await ctx.events.emit("order.paid", { orderId: order.id, total: order.total });

Sample output

{
  "namespace": "events",
  "method": "emit",
  "id": "res_123",
  "state": "active"
}

`events.tail`

events.tail(opts?): AsyncIterable<Event>

Stream the canonical event log live.

Parameters

Name	Type	Description
`filter`	EventFilter	Filter by kind, entity, time.

Returns

AsyncIterable<Event>

events-tail.example

for await (const evt of vadyl.events.tail({ filter: { kind: "order.paid" } })) { ... }

Sample output

{
  "kind": "updated",
  "entityId": "res_123",
  "changedFields": ["state"]
}

Identity

Resolve the current actor, sessions, MFA challenges, federation flows.

`identity.me`

identity.me(): Actor

Resolve the current authenticated actor.

Returns

Actor{ subjectId, subjectType, roles, claims, contextSets, authStrength }

identity-me.example

const me = await vadyl.identity.me();

Sample output

{
  "namespace": "identity",
  "method": "me",
  "id": "res_123",
  "state": "active"
}

`identity.sessions.list`

identity.sessions.list(): Session[]

List the actor's active sessions.

Returns

Session[]

identity-sessions.list.example

const sessions = await vadyl.identity.sessions.list();

Sample output

{
  "namespace": "identity",
  "method": "sessions.list",
  "id": "res_123",
  "state": "active"
}

`identity.sessions.revoke`

identity.sessions.revoke(sessionId): void

Revoke a session immediately. Distributed coherence is enforced.

Parameters

Name	Type	Description
`sessionId`required	string	Session id to revoke.

Returns

void

identity-sessions.revoke.example

await vadyl.identity.sessions.revoke(sessionId);

Sample output

undefined

`identity.challenge.start`

identity.challenge.start(opts): Challenge

Begin a step-up MFA challenge.

Parameters

Name	Type	Description
`subjectId`required	string	Actor to challenge.
`requireStrength`required	AuthStrength	'mfa-totp' \| 'mfa-webauthn' \| 'passkey' \| 'mfa-sms' \| ...

Returns

Challenge

identity-challenge.start.example

const challenge = await vadyl.identity.challenge.start({ subjectId: userId, requireStrength: "mfa-totp" });

Sample output

{
  "namespace": "identity",
  "method": "challenge.start",
  "id": "res_123",
  "state": "active"
}

Branching

Manage branches, sandboxes, proposals, deployments — the canonical change-management surface.

`branching.branch.create`

branching.branch.create(name, opts?): Branch

Create a new branch from main (or another base).

Parameters

Name	Type	Description
`name`required	string	Branch name.
`baseBranch`	string	Base branch (default: main).

Returns

Branch

branching-branch.create.example

await vadyl.branching.branch.create("feature/refunds");

Sample output

{
  "namespace": "branching",
  "method": "branch.create",
  "id": "res_123",
  "state": "active"
}

`branching.sandbox.create`

branching.sandbox.create(branch, opts?): Sandbox

Provision an isolated sandbox database for a branch.

Parameters

Name	Type	Description
`branch`required	string	Branch name.
`seedFrom`	string	Snapshot id to seed from.

Returns

Sandbox

branching-sandbox.create.example

await vadyl.branching.sandbox.create("feature/refunds", { seedFrom: "snapshot:latest" });

Sample output

{
  "namespace": "branching",
  "method": "sandbox.create",
  "id": "res_123",
  "state": "active"
}

`branching.deploy.preview`

branching.deploy.preview(target, opts?): DeployPlan

Preview the effect of deploying the current branch to a target.

Parameters

Name	Type	Description
`target`required	string	Environment name.

Returns

DeployPlanSchema diff classification, runtime publication, ramp policy, policy violations.

branching-deploy.preview.example

const plan = await vadyl.branching.deploy.preview("production");

Sample output

{
  "namespace": "branching",
  "method": "deploy.preview",
  "id": "res_123",
  "state": "active"
}

`branching.deploy.apply`

branching.deploy.apply(target, opts?): Deployment

Apply the current branch to an environment with optional ramp.

Parameters

Name	Type	Description
`target`required	string	Environment name.
`ramp`	string[]	Ramp percentages — e.g. ['5%', '25%', '50%', '100%'].
`bake`	Duration	Bake time per ramp step.

Returns

Deployment

branching-deploy.apply.example

await vadyl.branching.deploy.apply("production", { ramp: ["5%","25%","50%","100%"], bake: "10m" });

Sample output

{
  "namespace": "branching",
  "method": "deploy.apply",
  "id": "res_123",
  "state": "active"
}

`branching.deploy.rollback`

branching.deploy.rollback(target, toVersion): Deployment

Roll a target back to a prior publication version.

Parameters

Name	Type	Description
`target`required	string	Environment name.
`toVersion`required	string	Publication version, e.g. v412.

Returns

Deployment

branching-deploy.rollback.example

await vadyl.branching.deploy.rollback("production", "v412");

Sample output

{
  "namespace": "branching",
  "method": "deploy.rollback",
  "id": "res_123",
  "state": "active"
}

Explainability

Project canonical decision-record reasoning. Reads directly from authorities — never log-scraped.

`explainability.access`

explainability.access(req): AccessExplanation

Why was a read or write allowed/denied?

Parameters

Name	Type	Description
`entity`required	string	Entity name.
`operation`required	string	'read' \| 'create' \| 'update' \| 'delete'.
`filter`	Filter	Optional row filter to evaluate against.
`asActor`	string	Actor to evaluate as (defaults to caller).

Returns

AccessExplanation{ decision, reasonCode, evaluatedFilter, fieldMasks }

explainability-access.example

const why = await vadyl.explainability.access({ entity: "Order", operation: "read", asActor: "user:abc" });

Sample output

{
  "namespace": "explainability",
  "method": "access",
  "id": "res_123",
  "state": "active"
}

`explainability.readPlan`

explainability.readPlan(req): ReadPlanExplanation

Show the AST plan, cache decision, chosen provider for a read.

Returns

ReadPlanExplanation

explainability-readPlan.example

const plan = await vadyl.explainability.readPlan({ entity: "Order", filter: { status: { eq: "paid" } } });

Sample output

{
  "namespace": "explainability",
  "method": "readPlan",
  "id": "res_123",
  "state": "active"
}

`explainability.projectRuntime`

explainability.projectRuntime(): ProjectRuntimeExplanation

Show why this publication is serving traffic.

Returns

ProjectRuntimeExplanation

explainability-projectRuntime.example

const exp = await vadyl.explainability.projectRuntime();

Sample output

{
  "namespace": "explainability",
  "method": "projectRuntime",
  "id": "res_123",
  "state": "active"
}

Schema

Metadata, preview, diff, validation, snapshots, migration journals, transitions, and family-aware evolution.

`schema.metadata`

schema.metadata(opts?): SchemaMetadata

Read every entity, field, relation, index, access mask, trigger, transition state, and generated route shape.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SchemaMetadataSchemaMetadata with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

schema-metadata.example

const result = await vadyl.schema.metadata({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "schema",
  "method": "metadata",
  "id": "res_123",
  "state": "active"
}

`schema.preview`

schema.preview(change): SchemaPreview

Classify schema changes before applying them. Returns transition strategy, risk, provider capability notes, and reason codes.

Parameters

Name	Type	Description
`change`required	SchemaChange	Entity/field/relation/index/template/evolution change set.

Returns

SchemaPreviewSchemaPreview with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

schema-preview.example

const result = await vadyl.schema.preview({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "schema",
  "method": "preview",
  "id": "res_123",
  "state": "active"
}

`schema.diff`

schema.diff(target): SchemaDiff

Diff the current branch or publication against another branch, environment, snapshot, or template.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SchemaDiffSchemaDiff with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

schema-diff.example

const result = await vadyl.schema.diff({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "schema",
  "method": "diff",
  "id": "res_123",
  "state": "active"
}

`schema.validate`

schema.validate(opts?): ValidationReport

Validate schema invariants, capability requirements, access references, relation cycles, and projection compatibility.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

ValidationReportValidationReport with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

schema-validate.example

const result = await vadyl.schema.validate({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "schema",
  "method": "validate",
  "id": "res_123",
  "state": "active"
}

`schema.snapshot.create`

schema.snapshot.create(opts?): Snapshot

Create an immutable project schema snapshot.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SnapshotSnapshot with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

schema-snapshot.create.example

const result = await vadyl.schema.snapshot.create({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "schema",
  "method": "snapshot.create",
  "id": "res_123",
  "state": "active"
}

`schema.transition.execute`

schema.transition.execute(id, opts?): TransitionRun

Execute a planned transition with checkpoint, backfill, compatibility window, rollback, and audit evidence.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

TransitionRunTransitionRun with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

schema-transition.execute.example

const result = await vadyl.schema.transition.execute({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "schema",
  "method": "transition.execute",
  "id": "res_123",
  "state": "active"
}

Authored runtime

Validate, build, publish, invoke, inspect runtime units, and operate publication-pinned authored code.

`authored.validate`

authoredRuntime.validate(source): ValidationReport

Validate authored handlers, workflows, jobs, imports, bridge grants, and edge restrictions.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

ValidationReportValidationReport with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

authored-validate.example

const result = await vadyl.authoredRuntime.validate({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "authored",
  "method": "validate",
  "id": "res_123",
  "state": "active"
}

`authored.previewBuild`

authoredRuntime.previewBuild(unit): BuildPreview

Run the deterministic build pipeline without publishing.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

BuildPreviewBuildPreview with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

authored-previewBuild.example

const result = await vadyl.authoredRuntime.previewBuild({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "authored",
  "method": "previewBuild",
  "id": "res_123",
  "state": "active"
}

`authored.publish`

authoredRuntime.publish(opts): AuthoredPublication

Publish signed artifacts and bind them to a project publication candidate.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

AuthoredPublicationAuthoredPublication with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

authored-publish.example

const result = await vadyl.authoredRuntime.publish({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "authored",
  "method": "publish",
  "id": "res_123",
  "state": "active"
}

`authored.invoke`

authoredRuntime.invoke(handler, input, opts?): InvocationResult

Invoke a core or management handler through the same bridge used in production.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

InvocationResultInvocationResult with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

authored-invoke.example

const result = await vadyl.authoredRuntime.invoke({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "authored",
  "method": "invoke",
  "id": "res_123",
  "state": "active"
}

`authored.runtimeUnits.list`

authoredRuntime.runtimeUnits.list(): RuntimeUnit[]

List runtime units, their surfaces, grants, diagnostics, and publication lineage.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeUnit[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

authored-runtimeUnits.list.example

const result = await vadyl.authoredRuntime.runtimeUnits.list({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "authored",
  "method": "runtimeUnits.list",
  "id": "res_123",
  "state": "active"
}

`authored.workflows.start`

authoredRuntime.workflows.start(name, input): WorkflowInstance

Start a durable workflow pinned to the selected authored publication.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

WorkflowInstanceWorkflowInstance with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

authored-workflows.start.example

const result = await vadyl.authoredRuntime.workflows.start({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "authored",
  "method": "workflows.start",
  "id": "res_123",
  "state": "active"
}

Storage

Object and asset storage: upload, download, list, metadata, presign, copy, move, delete, provider bindings.

`storage.upload`

storage.upload(path, body, opts?): StoredObject

Upload an object with content type, checksum, retention, and provider routing.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

StoredObjectStoredObject with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

storage-upload.example

const result = await vadyl.storage.upload({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "storage",
  "method": "upload",
  "id": "res_123",
  "state": "active"
}

`storage.download`

storage.download(path, opts?): Blob

Download an object or stream it through the runtime transport.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

BlobBlob with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

storage-download.example

const result = await vadyl.storage.download({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "storage",
  "method": "download",
  "id": "res_123",
  "state": "active"
}

`storage.presign`

storage.presign(path, opts): SignedUrl

Create a signed upload/download URL with expiry, method, content policy, and audit reason.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SignedUrlSignedUrl with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

storage-presign.example

const result = await vadyl.storage.presign({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "storage",
  "method": "presign",
  "id": "res_123",
  "state": "active"
}

`storage.list`

storage.list(opts?): Page<StoredObject>

List objects under a prefix with cursor pagination.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Page<StoredObject>A cursor-paged result with data and page metadata.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

storage-list.example

const result = await vadyl.storage.list({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "data": [{ "id": "res_123", "state": "active" }],
  "page": { "size": 50, "next": "cur_1" }
}

`storage.copy`

storage.copy(from, to, opts?): StoredObject

Copy an object without exposing provider clients.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

StoredObjectStoredObject with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

storage-copy.example

const result = await vadyl.storage.copy({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "storage",
  "method": "copy",
  "id": "res_123",
  "state": "active"
}

`storage.delete`

storage.delete(path): void

Delete an object or fail closed when retention or access policy blocks it.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

voidNo content on success.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

storage-delete.example

const result = await vadyl.storage.delete({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

undefined

Webhooks

Outbound endpoints, inbound receivers, signatures, delivery attempts, replay, diagnostics, and secret rotation.

`webhooks.endpoints.list`

webhooks.endpoints.list(): WebhookEndpoint[]

List outbound endpoints and their typed subscription filters.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

WebhookEndpoint[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

webhooks-endpoints.list.example

const result = await vadyl.webhooks.endpoints.list({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "webhooks",
  "method": "endpoints.list",
  "id": "res_123",
  "state": "active"
}

`webhooks.endpoints.create`

webhooks.endpoints.create(input): WebhookEndpoint

Create a signed outbound endpoint with typed SubscriptionFilterAst.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

WebhookEndpointWebhookEndpoint with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

webhooks-endpoints.create.example

const result = await vadyl.webhooks.endpoints.create({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "webhooks",
  "method": "endpoints.create",
  "id": "res_123",
  "state": "active"
}

`webhooks.deliveries.list`

webhooks.deliveries.list(endpointId): WebhookDelivery[]

Inspect delivery attempts, status machine state, retry schedule, and response snapshots.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

WebhookDelivery[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

webhooks-deliveries.list.example

const result = await vadyl.webhooks.deliveries.list({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "webhooks",
  "method": "deliveries.list",
  "id": "res_123",
  "state": "active"
}

`webhooks.deliveries.replay`

webhooks.deliveries.replay(deliveryId): ReplayReceipt

Replay a delivery with the same canonical payload and a new attempt id.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

ReplayReceiptReplayReceipt with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

webhooks-deliveries.replay.example

const result = await vadyl.webhooks.deliveries.replay({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "webhooks",
  "method": "deliveries.replay",
  "id": "res_123",
  "state": "active"
}

`webhooks.receivers.create`

webhooks.receivers.create(input): WebhookReceiver

Create an inbound receiver key, signature policy, replay window, and event mapping.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

WebhookReceiverWebhookReceiver with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

webhooks-receivers.create.example

const result = await vadyl.webhooks.receivers.create({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "webhooks",
  "method": "receivers.create",
  "id": "res_123",
  "state": "active"
}

`webhooks.verify`

webhooks.verify(rawBody, headers, secret): VerificationResult

Verify inbound webhook bytes exactly as Vadyl does before dispatch.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

VerificationResultVerificationResult with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

webhooks-verify.example

const result = await vadyl.webhooks.verify({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "webhooks",
  "method": "verify",
  "id": "res_123",
  "state": "active"
}

Realtime

WebSocket, SSE, entity subscriptions, channel subscriptions, field-name-only change events, reconnect, and cursor resume.

`realtime.subscribeEntity`

realtime.subscribeEntity(entity, opts): Subscription<ChangeEvent>

Subscribe to entity changes with the same typed filter AST as reads.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Subscription<ChangeEvent>Subscription<ChangeEvent> with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

realtime-subscribeEntity.example

const result = await vadyl.realtime.subscribeEntity({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "kind": "updated",
  "entityId": "res_123",
  "changedFields": ["state"]
}

`realtime.subscribeChannel`

realtime.subscribeChannel(channel, opts): Subscription<Message>

Subscribe to a project channel or broadcast topic.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Subscription<Message>Subscription<Message> with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

realtime-subscribeChannel.example

const result = await vadyl.realtime.subscribeChannel({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "kind": "updated",
  "entityId": "res_123",
  "changedFields": ["state"]
}

`realtime.publish`

realtime.publish(channel, message): PublishReceipt

Publish a message through governed realtime fanout.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

PublishReceiptPublishReceipt with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

realtime-publish.example

const result = await vadyl.realtime.publish({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "realtime",
  "method": "publish",
  "id": "res_123",
  "state": "active"
}

`realtime.resume`

realtime.resume(cursor): Subscription<Event>

Resume a dropped subscription from a server-issued cursor.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Subscription<Event>Subscription<Event> with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

realtime-resume.example

const result = await vadyl.realtime.resume({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "realtime",
  "method": "resume",
  "id": "res_123",
  "state": "active"
}

Analytics

Catalog, query validation/explain/execute, models, metrics, perspectives, reports, dashboards, materializations, lineage.

`analytics.catalog`

analytics.catalog(): AnalyticsCatalog

Read subjects, dimensions, measures, metrics, comparisons, and privacy annotations.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

AnalyticsCatalogAnalyticsCatalog with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

analytics-catalog.example

const result = await vadyl.analytics.catalog({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "analytics",
  "method": "catalog",
  "id": "res_123",
  "state": "active"
}

`analytics.query.validate`

analytics.query.validate(query): QueryValidation

Validate units, dimensions, measures, privacy thresholds, export class, and access grants.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

QueryValidationQueryValidation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

analytics-query.validate.example

const result = await vadyl.analytics.query.validate({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "analytics",
  "method": "query.validate",
  "id": "res_123",
  "state": "active"
}

`analytics.query.explain`

analytics.query.explain(query): QueryExplanation

Explain planner choices, UMG nodes, materialization use, lineage, and suppression.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

QueryExplanationQueryExplanation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

analytics-query.explain.example

const result = await vadyl.analytics.query.explain({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "analytics",
  "method": "query.explain",
  "id": "res_123",
  "state": "active"
}

`analytics.query.execute`

analytics.query.execute(query): QueryResult

Execute a canonical analytics query.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

QueryResultQueryResult with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

analytics-query.execute.example

const result = await vadyl.analytics.query.execute({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "analytics",
  "method": "query.execute",
  "id": "res_123",
  "state": "active"
}

`analytics.reports.run`

analytics.reports.run(reportId): ReportRun

Run a report and return lineage plus materialization evidence.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

ReportRunReportRun with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

analytics-reports.run.example

const result = await vadyl.analytics.reports.run({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "analytics",
  "method": "reports.run",
  "id": "res_123",
  "state": "active"
}

`analytics.materializations.refresh`

analytics.materializations.refresh(id): MaterializationRun

Refresh a materialization through scheduler-aware runtime dispatch.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

MaterializationRunMaterializationRun with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

analytics-materializations.refresh.example

const result = await vadyl.analytics.materializations.refresh({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "analytics",
  "method": "materializations.refresh",
  "id": "res_123",
  "state": "active"
}

Automation

Compile definitions, manage runs, approvals, attempts, signals, compensation, and synthesized durable workflows.

`automation.compile`

automation.compile(definition): AutomationCompileResult

Compile and type-check a definition against the Plane Capability Graph.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

AutomationCompileResultAutomationCompileResult with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

automation-compile.example

const result = await vadyl.automation.compile({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "automation",
  "method": "compile",
  "id": "res_123",
  "state": "active"
}

`automation.definitions.create`

automation.definitions.create(input): AutomationDefinition

Create a versioned automation definition.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

AutomationDefinitionAutomationDefinition with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

automation-definitions.create.example

const result = await vadyl.automation.definitions.create({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "automation",
  "method": "definitions.create",
  "id": "res_123",
  "state": "active"
}

`automation.runs.start`

automation.runs.start(definitionId, input): AutomationRun

Start an automation run with durable state.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

AutomationRunAutomationRun with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

automation-runs.start.example

const result = await vadyl.automation.runs.start({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "automation",
  "method": "runs.start",
  "id": "res_123",
  "state": "active"
}

`automation.runs.signal`

automation.runs.signal(runId, signal): AutomationRun

Resume a waiting run with a typed signal.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

AutomationRunAutomationRun with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

automation-runs.signal.example

const result = await vadyl.automation.runs.signal({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "automation",
  "method": "runs.signal",
  "id": "res_123",
  "state": "active"
}

`automation.approvals.approve`

automation.approvals.approve(taskId, input): ApprovalReceipt

Approve a human-in-the-loop task.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

ApprovalReceiptApprovalReceipt with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

automation-approvals.approve.example

const result = await vadyl.automation.approvals.approve({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "automation",
  "method": "approvals.approve",
  "id": "res_123",
  "state": "active"
}

`automation.attempts.retry`

automation.attempts.retry(attemptId): AutomationAttempt

Retry a failed attempt while preserving run state.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

AutomationAttemptAutomationAttempt with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

automation-attempts.retry.example

const result = await vadyl.automation.attempts.retry({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "automation",
  "method": "attempts.retry",
  "id": "res_123",
  "state": "active"
}

MCP

Token issuance, protected-resource metadata, tool/resource/prompt descriptors, invocation, and agent-safe projection.

`mcp.metadata`

mcp.metadata(): McpProtectedResourceMetadata

Read OAuth protected resource metadata and supported scopes.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

McpProtectedResourceMetadataMcpProtectedResourceMetadata with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

mcp-metadata.example

const result = await vadyl.mcp.metadata({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "mcp",
  "method": "metadata",
  "id": "res_123",
  "state": "active"
}

`mcp.tools.list`

mcp.tools.list(opts?): McpTool[]

List only the tools allowed by token grants, project publication, and exposure bindings.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

McpTool[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

mcp-tools.list.example

const result = await vadyl.mcp.tools.list({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "mcp",
  "method": "tools.list",
  "id": "res_123",
  "state": "active"
}

`mcp.tools.call`

mcp.tools.call(name, args): McpCallResult

Call an MCP tool through the canonical operation dispatcher.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

McpCallResultMcpCallResult with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

mcp-tools.call.example

const result = await vadyl.mcp.tools.call({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "mcp",
  "method": "tools.call",
  "id": "res_123",
  "state": "active"
}

`mcp.resources.list`

mcp.resources.list(opts?): McpResource[]

List MCP resources such as schema, PCG nodes, logs, memory, and knowledge documents.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

McpResource[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

mcp-resources.list.example

const result = await vadyl.mcp.resources.list({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "mcp",
  "method": "resources.list",
  "id": "res_123",
  "state": "active"
}

`mcp.resources.read`

mcp.resources.read(uri): McpResourceContent

Read an MCP resource with access checks and redaction.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

McpResourceContentMcpResourceContent with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

mcp-resources.read.example

const result = await vadyl.mcp.resources.read({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "mcp",
  "method": "resources.read",
  "id": "res_123",
  "state": "active"
}

`mcp.prompts.get`

mcp.prompts.get(name, args?): McpPrompt

Resolve a prompt template derived from project state or an installed surface.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

McpPromptMcpPrompt with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

mcp-prompts.get.example

const result = await vadyl.mcp.prompts.get({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "mcp",
  "method": "prompts.get",
  "id": "res_123",
  "state": "active"
}

Project capability surfaces

Publish, validate, describe, install, upgrade, grant, consume, invoke, explain, suspend, resume, and revoke project capability surfaces.

`surfaces.publish`

surfaces.publish(manifest): PublishedSurface

Publish a signed ProjectCapabilitySurfaceManifest from the provider project.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

PublishedSurfacePublishedSurface with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-publish.example

const result = await vadyl.surfaces.publish({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "publish",
  "id": "res_123",
  "state": "active"
}

`surfaces.validateManifest`

surfaces.validateManifest(manifest): SurfaceValidationReport

Validate slices, exposure bindings, grants, PCG contribution, SDK/CLI/MCP projection, and lifecycle policy.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceValidationReportSurfaceValidationReport with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-validateManifest.example

const result = await vadyl.surfaces.validateManifest({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "validateManifest",
  "id": "res_123",
  "state": "active"
}

`surfaces.describe`

surfaces.describe(surface): SurfaceDescriptor

Read the canonical descriptor for a published or installed project capability surface.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceDescriptorSurfaceDescriptor with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-describe.example

const result = await vadyl.surfaces.describe({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "describe",
  "id": "res_123",
  "state": "active"
}

`surfaces.listPublished`

surfaces.listPublished(filter?): Page<PublishedSurface>

List published surfaces visible to the current project.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Page<PublishedSurface>A cursor-paged result with data and page metadata.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-listPublished.example

const result = await vadyl.surfaces.listPublished({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "data": [{ "id": "res_123", "state": "active" }],
  "page": { "size": 50, "next": "cur_1" }
}

`surfaces.install`

surfaces.install(request): SurfaceInstallation

Install a provider surface into the current consumer project with grant narrowing and billing attribution.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceInstallationSurfaceInstallation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-install.example

const result = await vadyl.surfaces.install({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "install",
  "id": "res_123",
  "state": "active"
}

`surfaces.upgrade`

surfaces.upgrade(installationId, request): SurfaceInstallation

Upgrade an installation to another provider version after compatibility checks.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceInstallationSurfaceInstallation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-upgrade.example

const result = await vadyl.surfaces.upgrade({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "upgrade",
  "id": "res_123",
  "state": "active"
}

`surfaces.grants.update`

surfaces.grants.update(installationId, grants): SurfaceInstallationGrant[]

Replace or narrow grants for an installed surface.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceInstallationGrant[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-grants.update.example

const result = await vadyl.surfaces.grants.update({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "grants.update",
  "id": "res_123",
  "state": "active"
}

`surfaces.consumption.query`

surfaces.consumption.query(filter): Page<ProjectCapabilityConsumptionDescriptor>

Query append-only usage evidence by provider, consumer, surface, operation, protocol, actor, or billing scope.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Page<ProjectCapabilityConsumptionDescriptor>A cursor-paged result with data and page metadata.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-consumption.query.example

const result = await vadyl.surfaces.consumption.query({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "data": [{ "id": "res_123", "state": "active" }],
  "page": { "size": 50, "next": "cur_1" }
}

`surfaces.invoke`

surfaces.invoke(surface, operation, input): SurfaceInvocationResult

Invoke an installed operation through the same dispatcher used by REST, SDK, CLI, and MCP.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceInvocationResultSurfaceInvocationResult with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-invoke.example

const result = await vadyl.surfaces.invoke({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "invoke",
  "id": "res_123",
  "state": "active"
}

`surfaces.explain`

surfaces.explain(subject): SurfaceExplanation

Explain publish, install, grant, projection, invocation, or consumption decisions from canonical descriptors.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceExplanationSurfaceExplanation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

surfaces-explain.example

const result = await vadyl.surfaces.explain({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "surfaces",
  "method": "explain",
  "id": "res_123",
  "state": "active"
}

Observability

Audit entries, operational trails, debug traces, metrics, spans, diagnostics, and correlation search.

`observability.audit.search`

observability.audit.search(filter): Page<AuditEntry>

Search tamper-resistant audit entries.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Page<AuditEntry>A cursor-paged result with data and page metadata.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

observability-audit.search.example

const result = await vadyl.observability.audit.search({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "data": [{ "id": "res_123", "state": "active" }],
  "page": { "size": 50, "next": "cur_1" }
}

`observability.operational.search`

observability.operational.search(filter): Page<OperationalEntry>

Search operational events, retries, route choices, provider calls, and dispatch state.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

Page<OperationalEntry>A cursor-paged result with data and page metadata.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

observability-operational.search.example

const result = await vadyl.observability.operational.search({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "data": [{ "id": "res_123", "state": "active" }],
  "page": { "size": 50, "next": "cur_1" }
}

`observability.traces.get`

observability.traces.get(traceId): Trace

Read a trace with spans, redaction markers, and correlated reason codes.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

TraceTrace with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

observability-traces.get.example

const result = await vadyl.observability.traces.get({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "observability",
  "method": "traces.get",
  "id": "res_123",
  "state": "active"
}

`observability.diagnostics`

observability.diagnostics(scope): DiagnosticsReport

Run health and coherence diagnostics for a project surface.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

DiagnosticsReportDiagnosticsReport with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

observability-diagnostics.example

const result = await vadyl.observability.diagnostics({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "observability",
  "method": "diagnostics",
  "id": "res_123",
  "state": "active"
}

Platform

Provider capabilities, runtime fabric scaling, distribution, version governance, data portability, surface descriptors, and health.

`platform.providers.list`

platform.providers.list(): ProviderDescriptor[]

List registered providers, capability declarations, and conformance state.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

ProviderDescriptor[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-providers.list.example

const result = await vadyl.platform.providers.list({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "providers.list",
  "id": "res_123",
  "state": "active"
}

`platform.runtimeFabric.plan`

platform.runtimeFabric.plan(input): RuntimeFabricPlan

Plan runtime topology realization before applying.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeFabricPlanRuntimeFabricPlan with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-runtimeFabric.plan.example

const result = await vadyl.platform.runtimeFabric.plan({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "runtimeFabric.plan",
  "id": "res_123",
  "state": "active"
}

`platform.runtimeFabric.targets`

platform.runtimeFabric.targets(input): RuntimeScaleTarget[]

List scale targets by project, environment, surface, and scale group.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeScaleTarget[]A typed array plus correlation metadata when returned over wire protocols.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-runtimeFabric.targets.example

const result = await vadyl.platform.runtimeFabric.targets({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "runtimeFabric.targets",
  "id": "res_123",
  "state": "active"
}

`platform.runtimeFabric.setDesiredCount`

platform.runtimeFabric.setDesiredCount(input): RuntimeScaleMutation

Set desired count for a manual runtime scale target.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeScaleMutationRuntimeScaleMutation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-runtimeFabric.setDesiredCount.example

const result = await vadyl.platform.runtimeFabric.setDesiredCount({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "runtimeFabric.setDesiredCount",
  "id": "res_123",
  "state": "active"
}

`platform.runtimeFabric.setScalingPolicy`

platform.runtimeFabric.setScalingPolicy(input): RuntimeScaleMutation

Update a surface scaling policy with capability and governance checks.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeScaleMutationRuntimeScaleMutation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-runtimeFabric.setScalingPolicy.example

const result = await vadyl.platform.runtimeFabric.setScalingPolicy({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "runtimeFabric.setScalingPolicy",
  "id": "res_123",
  "state": "active"
}

`platform.runtimeFabric.setResources`

platform.runtimeFabric.setResources(input): RuntimeScaleMutation

Update vendor-neutral vertical resource policy for a runtime surface.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeScaleMutationRuntimeScaleMutation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-runtimeFabric.setResources.example

const result = await vadyl.platform.runtimeFabric.setResources({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "runtimeFabric.setResources",
  "id": "res_123",
  "state": "active"
}

`platform.runtimeFabric.setIngress`

platform.runtimeFabric.setIngress(input): RuntimeScaleMutation

Update canonical ingress and load-balancing policy for a runtime surface.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeScaleMutationRuntimeScaleMutation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-runtimeFabric.setIngress.example

const result = await vadyl.platform.runtimeFabric.setIngress({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "runtimeFabric.setIngress",
  "id": "res_123",
  "state": "active"
}

`platform.runtimeFabric.explainAutoscale`

platform.runtimeFabric.explainAutoscale(input): RuntimeAutoscaleExplanation

Explain the latest autoscale decision, skipped decision, or capability rejection.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

RuntimeAutoscaleExplanationRuntimeAutoscaleExplanation with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-runtimeFabric.explainAutoscale.example

const result = await vadyl.platform.runtimeFabric.explainAutoscale({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "runtimeFabric.explainAutoscale",
  "id": "res_123",
  "state": "active"
}

`platform.distribution.delivery`

platform.distribution.delivery(input): DeliveryDescriptor

Resolve distribution-backed asset delivery and cache policy.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

DeliveryDescriptorDeliveryDescriptor with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-distribution.delivery.example

const result = await vadyl.platform.distribution.delivery({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "distribution.delivery",
  "id": "res_123",
  "state": "active"
}

`platform.version.upgradePlan`

platform.version.upgradePlan(input): UpgradePlan

Plan platform, foundation, contract, SDK, and publication upgrades.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

UpgradePlanUpgradePlan with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-version.upgradePlan.example

const result = await vadyl.platform.version.upgradePlan({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "version.upgradePlan",
  "id": "res_123",
  "state": "active"
}

`platform.surface.describe`

platform.surface(name): SurfaceDescriptor

Read the canonical descriptor for any published or installed surface.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

SurfaceDescriptorSurfaceDescriptor with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-surface.describe.example

const result = await vadyl.platform.surface.describe({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "surface.describe",
  "id": "res_123",
  "state": "active"
}

`platform.health`

platform.health(scope?): HealthReport

Read liveness, readiness, dependency health, and coherence status.

Parameters

Name	Type	Description
`opts`	object	Operation-specific input. See the request example for the canonical JSON shape.

Returns

HealthReportHealthReport with descriptor hash, correlation id, and reason-code metadata when applicable.

Errors

Code	Description
`ACCESS_DENIED`	Required project grant, auth strength, row policy, or field mask denied the operation.
`VALIDATION_FAILED`	Input does not match the compiled contract or references an unknown descriptor.
`QUOTA_EXCEEDED`	A hard quota, reservation, or token budget refused the call.
`SURFACE_UNAVAILABLE`	The bound provider, runtime unit, publication, or installation is unhealthy.

platform-health.example

const result = await vadyl.platform.health({
  project: "billing",
  input: { id: "res_123" },
  explain: true,
});

Sample output

{
  "namespace": "platform",
  "method": "health",
  "id": "res_123",
  "state": "active"
}