Marketplace APIs

The marketplace API is the hosted catalog and operational history surface used by SDKs and embedded product UIs. It exposes integration metadata, version compatibility, auth requirements, docs, generated CodeMode API snapshots, CodeMode ABI environments, extern type snapshots, signed integration descriptors, integration download history, usage signals, and execution run history.

Browse

integrations.search accepts query, category, tags, limit, and cursor. Results intentionally hide version internals so catalog UIs can render quickly.

Inspect

Use these procedures for detail pages and agent context:

• integrations.get: module docs, examples, auth metadata, permissions, and versions.
• integrations.version: one version or the latest version.
• integrations.authMetadata: provider auth strategy, scopes, OAuth URLs, and callback needs.
• integrations.codeModeApi: generated MiniGo CodeMode API snapshot.
• integrations.codeModeEnvironment: debug-readable CodeMode ABI mirror.
• integrations.codeModeEnvironmentBinary: base64-encoded codemode-env.bin ABI table.
• integrations.externTypes: Rust-backed foreign type metadata.
• integrations.artifact: signed integration descriptor and download tracking for authenticated SDK hosts.
• integrations.artifactDownloads: organization-scoped integration download history for console or embedded catalog audit views.

Version records advertise public schemas for manifests, execution envelopes, and module install envelopes so SDKs can pin the exact contracts they validate. Each version also includes artifact_envelope_url; SDKs use it to fetch the JSON envelope that combines the manifest, generated CodeMode API, CodeMode ABI mirror and binary table, extern type snapshot, and base64-encoded WASM bytes for runtime registration.

Install And Pin

Authenticated SDK hosts call:

• integrations.install with organization_id, module_id, and optional version.
• integrations.installed with organization_id.
• integrations.updates with organization_id to list installed modules whose pinned version is behind the current marketplace latest_version.
• integrations.update with organization_id and module_id to move a pin to the current marketplace latest version.
• integrations.uninstall with organization_id and module_id.

Pins are stored per organization. Updating a pin replaces only the pinned version; provider credentials remain in the embedding application's local store. Better Auth browser sessions can call these routes for their console workspace. API-key callers must present module:read for installed-module and download history reads, and module:install for install or uninstall mutations. Private organization-scoped routes also verify that browser sessions belong to the requested Better Auth organization, or that the API key metadata includes the same organization_id.

Integration Metadata

Integration descriptors include URL, SHA-256 checksum, manifest checksum, signature, signing key ID, and size. SDKs must verify the checksum and signature before loading any module into the runtime. The TypeScript SDK's installModuleArtifact helper downloads the descriptor's WASM, verifies it, downloads artifact_envelope_url, checks the envelope's WASM checksum and signature metadata against the verified descriptor, and registers the envelope. The Rust core validates install envelopes again by hashing wasm_bytes and checking the signature before a verified module install is registered.

The install envelope schema is published at https://schemas.invoketool.com/artifact.schema.json. Its wasm_bytes field is base64 encoded on the wire; SDKs verify checksum and signature metadata before registering a module artifact. Hosted publishing should precompute module ABI metadata from the integration WASM so SDKs do not need to parse raw module WASM on each install.

Bundle core validates manifests, install metadata, generated CodeMode snapshots, and MiniGo CodeMode source. SDK hosts instantiate the shared core WASM behind CodeModeCore; the core routes generated MiniGo extern calls to host-owned action handlers without exposing provider credentials to hosted APIs.

Release operators validate key custody and catalog references with node infra/scripts/validate-signing-policy.mjs. Production deploys must pass the stricter --production mode so public marketplace descriptors are signed by the active production key from infra/artifact-signing-policy.json.

Billable Usage

InvokeTool bills only for hosted integration downloads. Marketplace/API tool calls are metered for usage visibility but priced at zero by default. SDK runtime activity such as CodeMode checks, WASM executions, runtime failures, and host-call failures is local to the embedding application and is not sent to InvokeTool for billing.

analytics.usage accepts organization_id and module_id filters. Console usage panels pass the active organization ID. If an API key omits organization_id, the API scopes the query to the key's Better Auth organization_id metadata; unscoped API keys are rejected instead of receiving cross-organization usage. Usage responses include the resolved organization_id beside the metrics and time series so console exports and embedded catalog UIs can prove the counters belong to the active organization. Metrics currently include marketplace_api_calls, artifact_downloads (integration downloads), and total_calls.

The API client exposes getAuthContext for API-key metadata, getUsageSummary for analytics.usage, getBillingAccount for billing.account, and listArtifactDownloads for integrations.artifactDownloads so embedded catalog UIs can render scoped account context, billing state, usage counters, and install-history audit views without private RPC helpers.

Execution History

Hosted execution records are organization-scoped and read through the executions router. These records are separate from provider credentials: module provider tokens stay in the SDK host's local auth store, while the hosted API stores run metadata, step status, redacted logs, timing, and structured results.

• executions.runs accepts organization_id, status, and limit and returns { runs } with recent run summaries ordered by start time.
• executions.get accepts organization_id and run_id and returns the run result plus ordered step records and redacted log records.
• executions.record accepts a run status, optional workflow IDs, execution input/output/error payloads, step records, and log records so SDK hosts can persist the execution result they just returned to the embedding application.

These routes require the authenticated caller to have project:read for the resolved organization. Browser sessions are checked against their active Better Auth organization, and API-key callers are scoped through key metadata when organization_id is omitted. The API client exposes recordExecutionRun, listExecutionRuns, and getExecutionRun for embedded consoles that need to write and show recent runs, failures, logs, and result metadata next to marketplace installs and usage counters.

The hosted API redacts secret-looking metadata before writing D1 usage records or Cloudflare Analytics Engine events. SDK hosts should still keep provider tokens in local auth stores and only send operational metadata such as SDK version, module version, action name, log count, or metric count. API-generated events include a trace_id from x-request-id, Cloudflare cf-ray, or a generated UUID so operators can correlate API logs, D1 usage rows, and Analytics Engine datapoints.