Physical Capability Cloud

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Discover, hire, and verify real-world physical capability through MCP.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "Physical Capability Cloud": {
      "url": "https://capability.network/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (256)

• provision_api_key

  CALL THIS FIRST. Provisions an API key for the operator. Returns a pcc_live_* key that must be included as 'Authorization: Bearer <key>' on all subsequent requests. Accepts either email OR walletAddress. The key is shown once — save it. Without it, all other endpoints return 401.

  Parameters:

  • name — string — Operator display name (optional)
  • email — string — Operator email address (use this OR walletAddress)
  • capability — string — What the operator does — e.g. 'FDM 3D printing', 'CNC milling', 'HPLC analysis'
  • walletAddress — string — EVM wallet address (use this OR email)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_api_keys read-only

  List all active API keys for the authenticated operator. Returns key IDs, prefixes, scopes, rate limits, usage counts, and creation/expiry timestamps. Requires a valid API key or SIWE session.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• revoke_api_key destructive

  Revoke an API key permanently. The key will immediately stop working. You must own the key. Use list_api_keys to find the key ID.

  Parameters:

  • keyId (required) — string — Key ID to revoke (from list_api_keys)

  Hints: read-only no · destructive yes · idempotent not declared · open-world not declared

• setup_detect read-only

  Auto-detect current setup state: env vars, database, adapters, chain connectivity, storage, identity. Use this to see what's configured and what's missing before onboarding.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• setup_generate_config

  Generate a KERNEL_CONFIG JSON from device descriptions. Tell it what machines you have and it produces the config ready to paste into your environment.

  Parameters:

  • devices (required) — array — Array of device descriptions with type, model, and connection info

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• setup_validate

  Validate a kernel config (20+ checks: JSON structure, device connectivity, adapter compatibility). Returns validation errors and warnings.

  Parameters:

  • config (required) — object — Kernel config JSON to validate

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• setup_register_device

  Register a device in the database with adapter config and capabilities. Part of Step 3 in the onboarding flow. Required: kernelId, deviceId, type and adapterType (400 missing_required_fields otherwise).

  Parameters:

  • kernelId (required) — string — Kernel ID to register the device under
  • deviceId (required) — string — Your ID for this device, unique within the kernel
  • type (required) — string — Device role: machine, sensor or camera (the values setup_generate_config and setup_validate accept)
  • adapterType (required) — string — One of octoprint, modbus, opcua, sila, ipp, generic-http or mock; the route refuses anything else (including opentrons)
  • model — string — Device model identifier (optional; stored as "unknown" if absent)
  • capabilities — array — Capability types this device serves
  • adapterConfig — object — Adapter-specific configuration (host, port, auth, etc.)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• setup_test_job

  Submit a test job to verify the full pipeline works end-to-end (Step 4 of onboarding). Returns job ID and result.

  Parameters:

  • kernelId (required) — string — Kernel ID to test
  • deviceId — string — Specific device ID to test (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• setup_status read-only

  Comprehensive setup status across 6 categories: gateway, database, adapters, chain, storage, identity. Use to confirm everything is green before going live.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• list_capability_types read-only

  List all capability types registered on the network (FDM, SLA, CNC, HPLC, etc.) with metadata.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• search_capabilities read-only

  Search capability templates by type or keyword. Returns templates with pricing, assurance tiers, and availability.

  Parameters:

  • query (required) — string — Search query (type name, material, process, etc.)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_build_options

  Get configuration options for a capability type (materials, dimensions, tolerances, assurance tiers). Use before calling calculate_price.

  Parameters:

  • type (required) — string — Capability type (e.g. fdm, cnc-3axis, hplc)
  • profileId — string — Optional capability profile ID
  • selections — object — Current selections to refine available options

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• calculate_price

  Calculate price for a capability configuration. Returns base price, tier premiums, and estimated total cost.

  Parameters:

  • type (required) — string — Capability type
  • selections (required) — object — Configuration selections (material, dimensions, quantity, etc.)
  • profileId — string — Optional capability profile ID

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• build_contract

  Build and submit a capability contract with on-chain milestone escrow. Returns job ID and escrow address.

  Parameters:

  • type (required) — string — Capability type
  • selections (required) — object — Configuration selections
  • assuranceTier (required) — number — Assurance tier 0-3 (0=self-reported, 3=ZK-proven+bonds)
  • profileId — string — Optional capability profile ID

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_kernels read-only

  List all Shop Kernels on the network with status and capability types. Optionally filter by status.

  Parameters:

  • status — string — Filter by kernel status (online, offline, maintenance)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_kernel read-only

  Get kernel details including full capability objects, devices, and queue.

  Parameters:

  • kernelId (required) — string — Kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_kernel_devices read-only

  List all devices registered under a specific kernel, including adapter configs and device types.

  Parameters:

  • kernelId (required) — string — Kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_kernel_jobs read-only

  List all jobs submitted to a specific kernel, including job status and progress.

  Parameters:

  • kernelId (required) — string — Kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• create_kernel

  Register a new Shop Kernel (physical site) on the PCC network. Part of Step 2 in the onboarding flow.

  Parameters:

  • name (required) — string — Kernel/site name (e.g. 'BioPunk Lab - Bay A')
  • config — object — Kernel configuration JSON
  • location — object — Location object with address and geo coordinates
  • description — string — Description of the site and its capabilities

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_jobs read-only

  List all jobs with status. Optionally filter by kernelId or status.

  Parameters:

  • status — string — Filter by status (pending, queued, in_progress, paused, completed, failed, cancelled)
  • kernelId — string — Filter by kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_job read-only

  Get job details including progress, evidence bundles, and milestones.

  Parameters:

  • jobId (required) — string — Job ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• update_job_status

  Update a job's status and optional progress percentage. Used by kernels to report job progress.

  Parameters:

  • jobId (required) — string — Job ID
  • status (required) — string — New status (pending, queued, in_progress, paused, completed, failed, cancelled). 'running' is accepted as a legacy alias for in_progress.
  • progress — number — Progress percentage 0-100 (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_escrows read-only

  List escrow contracts with milestones and bonds. Optionally filter by status.

  Parameters:

  • status — string — Filter by escrow status

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_escrow read-only

  Get escrow details. Pass a DB ID for database record (with milestones and disputes), or an EVM address (0x...) to read directly from the blockchain.

  Parameters:

  • escrowId (required) — string — DB escrow ID or on-chain contract address (0x...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_escrow_chain_state read-only

  Read full on-chain escrow state with all milestone details from the blockchain. More detailed than get_escrow for on-chain contracts.

  Parameters:

  • address (required) — string — On-chain escrow contract address (0x...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_escrow_events read-only

  Get on-chain event history for an escrow contract. Returns funding, release, dispute, and bond events.

  Parameters:

  • address (required) — string — On-chain escrow contract address (0x...)
  • fromBlock — string — Starting block number (optional)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_token_balance read-only

  Read an ERC-20 token balance for an account address from the blockchain.

  Parameters:

  • tokenAddress (required) — string — ERC-20 token contract address (0x...)
  • account (required) — string — Account address to check balance for (0x...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_token_allowance read-only

  Read the ERC-20 token allowance granted by an owner to a spender from the blockchain.

  Parameters:

  • tokenAddress (required) — string — ERC-20 token contract address (0x...)
  • owner (required) — string — Token owner address (0x...)
  • spender (required) — string — Spender address (0x...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_escrow_dispute read-only

  Read dispute state for a specific milestone from the blockchain.

  Parameters:

  • address (required) — string — Escrow contract address (0x...)
  • milestoneIndex (required) — number — Milestone index (0-based)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_write_status read-only

  Check if on-chain write operations are enabled (requires PCC_GATEWAY_PRIVATE_KEY to be configured). Returns write status and signer address.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• fund_escrow

  Fund a protocol-created escrow on-chain. Approval is handled INTERNALLY by the gateway for protocol-created escrows (audit C-03 removed the public approve step) — do NOT call a separate approve first; fund directly. Returns transaction hash.

  Parameters:

  • address (required) — string — Escrow contract address (0x...)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• release_milestone

  Release a milestone payment on-chain after the challenge window has expired. Returns transaction hash.

  Parameters:

  • address (required) — string — Escrow contract address (0x...)
  • milestoneIndex (required) — number — Milestone index to release (0-based)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• file_escrow_dispute

  File a dispute against a milestone on-chain. Challenger must post a bond and provide evidence hash. Returns transaction hash.

  Parameters:

  • address (required) — string — Escrow contract address (0x...)
  • milestoneIndex (required) — number — Milestone index to dispute (0-based)
  • challengerBond (required) — string — Bond amount in wei (as string)
  • challengerEvidenceHash (required) — string — Evidence hash as 0x-prefixed hex bytes32
  • reason (required) — string — Human-readable dispute reason

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• deposit_bond

  Deposit an operator bond for a milestone on-chain. Required for Assurance Tier 3 jobs. Returns transaction hash.

  Parameters:

  • address (required) — string — Escrow contract address (0x...)
  • milestoneIndex (required) — number — Milestone index to post bond for (0-based)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• submit_evidence_hash

  Submit an evidence bundle hash for a milestone on-chain. Links the physical evidence to the on-chain settlement record. Returns transaction hash.

  Parameters:

  • address (required) — string — Escrow contract address (0x...)
  • milestoneIndex (required) — number — Milestone index (0-based)
  • evidenceBundleHash (required) — string — Evidence bundle hash as 0x-prefixed hex bytes32

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• submit_attestation

  Submit a verifier attestation for a milestone on-chain. Used by third-party verifiers (Bittensor subnet) to confirm evidence quality. Returns transaction hash.

  Parameters:

  • address (required) — string — Escrow contract address (0x...)
  • milestoneIndex (required) — number — Milestone index (0-based)
  • attestationHash (required) — string — Attestation hash as 0x-prefixed hex bytes32

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• archive_evidence

  Archive an evidence bundle to IPFS/Storacha for permanent decentralized storage. Returns the content-addressed CID.

  Parameters:

  • bundle (required) — object — Evidence bundle object to archive

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_evidence_bundle read-only

  Get an encrypted evidence bundle by its bundle ID. Returns the encrypted payload and key capsules.

  Parameters:

  • bundleId (required) — string — Evidence bundle ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• grant_evidence_access

  Grant a new recipient access to an encrypted evidence bundle. Creates a re-encrypted key capsule for the recipient.

  Parameters:

  • bundleId (required) — string — Evidence bundle ID
  • recipientAddress (required) — string — Recipient EVM address (0x...)
  • accessLevel — string — Level of access to grant (default: full)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_evidence_grants read-only

  List all evidence access grants for an address. Returns bundles the address has been granted access to.

  Parameters:

  • address (required) — string — EVM address to look up grants for (0x...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• archive_encrypted_bundle

  Archive an encrypted evidence bundle to IPFS and store the resulting CID in the database. Idempotent — returns existing CID if already archived.

  Parameters:

  • bundleId (required) — string — Encrypted evidence bundle ID

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_bundle_ipfs read-only

  Get IPFS CIDs for a bundle — returns the primary CID, metadata CID, and Filecoin deal ID if available.

  Parameters:

  • bundleId (required) — string — Evidence bundle ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• retrieve_ipfs read-only

  Retrieve raw data from IPFS by CID. Used to fetch archived evidence bundles from decentralized storage.

  Parameters:

  • cid (required) — string — IPFS content identifier (CID)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_lit_conditions read-only

  Get Lit Protocol access conditions for a Lit-encrypted evidence bundle. Returns the conditions that gate decryption.

  Parameters:

  • bundleId (required) — string — Evidence bundle ID (must be Lit-encrypted)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• lit_decrypt

  Decrypt a Lit Protocol-encrypted evidence bundle using a Lit auth signature. Returns the decrypted bundle payload.

  Parameters:

  • bundleId (required) — string — Evidence bundle ID (must be Lit-encrypted)
  • authSig (required) — object — Lit auth signature object with sig, derivedVia, signedMessage, and address fields

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• verify_evidence_zk

  Verify a ZK proof by its proof ID. Checks the proof against its verification key and public inputs.

  Parameters:

  • proofId (required) — string — ID of the ZK proof to verify

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• commit_evidence

  Create a Merkle commitment for an evidence bundle hash. Used as the first step in ZK proof generation for Tier 3 assurance.

  Parameters:

  • bundleHash (required) — string — SHA-256 hash of the evidence bundle

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_telemetry_stats read-only

  Get aggregate pipeline telemetry statistics including phase timings, success rates, and throughput metrics across all jobs.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_active_telemetry read-only

  List currently active jobs with their current pipeline phase and telemetry status.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_job_telemetry read-only

  Get full event timeline for a specific job — all pipeline phase transitions with timings and metadata.

  Parameters:

  • jobId (required) — string — Job ID to get pipeline timeline for

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_telemetry_logs read-only

  Query structured logs with filters for level, source, jobId, kernelId, time range, and full-text search.

  Parameters:

  • after — string — Return logs after this ISO timestamp
  • jobId — string — Filter by job ID
  • level — string — Filter by log level
  • limit — number — Max entries to return (default 200)
  • before — string — Return logs before this ISO timestamp
  • search — string — Full-text search query
  • source — string — Filter by source module
  • kernelId — string — Filter by kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• emit_telemetry

  Manually emit a telemetry event for a job pipeline phase. Used by kernels and agents to report execution progress.

  Parameters:

  • jobId (required) — string — Job ID
  • phase (required) — string — Pipeline phase name (e.g. intake, binding, execution, evidence, settlement)
  • status (required) — string — Phase status
  • level — string — Log level for this event
  • source — string — Source module or component
  • metadata — object — Additional event metadata
  • duration_ms — number — Phase duration in milliseconds

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• submit_for_human_verification

  Submit an evidence bundle for human verification. Selects a panel of verifiers from the network and returns assigned verifier IDs.

  Parameters:

  • bundleHash (required) — string — SHA-256 hash of the evidence bundle
  • photoRef (required) — string — Reference to the photo evidence (CID or URL)
  • referenceRef (required) — string — Reference to the reference/spec document
  • verifierCount — number — Number of verifiers to assign (default 5)
  • comparisonScore — number — Pre-computed comparison score 0-1 (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_verification_assignments read-only

  Get pending verification assignments for a verifier node. Returns requests this verifier has been assigned but not yet responded to.

  Parameters:

  • verifierId (required) — string — Verifier node ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_verification_status read-only

  Get verification status for a request. Returns vote tally, consensus state, dispute list, and pending response count.

  Parameters:

  • requestId (required) — string — Verification request ID (hvreq_...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• respond_to_verification

  Submit a verifier's verdict for a verification request. Returns consensus state after this vote.

  Parameters:

  • requestId (required) — string — Verification request ID (hvreq_...)
  • verifierId (required) — string — Verifier node ID
  • verdict (required) — string — Verifier's verdict
  • signature (required) — string — Cryptographic signature of the verdict
  • notes — string — Optional notes explaining the verdict

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• dispute_verification

  File a dispute against the consensus verdict. Only verifiers who submitted a response can dispute. Requires additional evidence CID.

  Parameters:

  • requestId (required) — string — Verification request ID (hvreq_...)
  • disputerId (required) — string — Verifier node ID filing the dispute
  • reason (required) — string — Reason for disputing the consensus
  • evidenceCid (required) — string — IPFS CID of the counter-evidence

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• register_capability_ip

  Register a capability as a Story Protocol IP Asset. Returns an ipId and NFT token. The designer earns royalties whenever this capability is used.

  Parameters:

  • capability (required) — object — Capability object
  • designerAddress (required) — string — EVM address of the capability designer
  • designerName (required) — string — Display name of the designer
  • ipfsCid — string — IPFS CID of the capability spec document (optional)
  • commercialRevShare — number — Revenue share percentage for commercial use (0-100)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• register_job_evidence_ip

  Register job evidence as a derivative IP asset on Story Protocol, linking it to the parent capability's IP. Operators earn royalties from derivative use.

  Parameters:

  • parentIpId (required) — string — IP ID of the parent capability
  • jobId (required) — string — Job ID whose evidence is being registered
  • evidenceBundleHash (required) — string — Hash of the evidence bundle
  • operatorAddress (required) — string — EVM address of the operator
  • operatorName (required) — string — Display name of the operator
  • ipfsCid — string — IPFS CID of the evidence bundle (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• distribute_royalties

  Set revenue splits for an IP asset among stakeholders (designer, operator, verifier, assembler, curator). Splits must sum to 100.

  Parameters:

  • ipId (required) — string — IP asset ID
  • splits (required) — array — Revenue splits — must sum to 100

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pay_ip_royalty

  Pay royalties to an IP asset vault. The payer sends tokens that flow to stakeholders via the royalty splits.

  Parameters:

  • ipId (required) — string — IP asset ID
  • amount (required) — string — Amount to pay in wei (as string)
  • payerAddress (required) — string — EVM address of the payer

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• claim_ip_revenue

  Claim earned revenue from an IP asset vault. Returns the claimed amount and transaction hash.

  Parameters:

  • ipId (required) — string — IP asset ID
  • tokenIds — array — Specific royalty token IDs to claim (optional — claims all if omitted)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_ip_revenue read-only

  Get a revenue snapshot for an IP asset — total earned, pending claims, and recent payments.

  Parameters:

  • ipId (required) — string — IP asset ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_ip_lineage read-only

  Get the full IP lineage chain for an asset — parent capabilities and all derivative job registrations.

  Parameters:

  • ipId (required) — string — IP asset ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_capability_ip read-only

  Get the Story Protocol IP registration for a capability by its capability ID.

  Parameters:

  • capabilityId (required) — string — Capability ID to look up IP registration for

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• raise_ip_dispute

  Raise a Story Protocol IP dispute against an asset. Provide evidence hash and reason.

  Parameters:

  • ipId (required) — string — IP asset ID to dispute
  • evidenceHash (required) — string — Hash of the dispute evidence
  • reason (required) — string — Reason for the dispute

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_protocols read-only

  List protocol templates in the library. Filter by tags, required capabilities, search query, or status.

  Parameters:

  • tags — string — Comma-separated tag filter (e.g. 'biotech,protein')
  • search — string — Full-text search query
  • status — string — Filter by template status
  • capabilities — string — Comma-separated required capability filter (e.g. 'hplc,centrifuge')

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_protocol read-only

  Get protocol template details by ID. Returns steps, transfers, parameters, and metadata.

  Parameters:

  • id (required) — string — Protocol template ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• create_protocol

  Create a new protocol template draft. Returns the new template ID.

  Parameters:

  • name (required) — string — Protocol name
  • tags — array — Tags for discovery
  • steps — array — Array of protocol step objects
  • transfers — array — Array of transfer objects between steps
  • parameters — array — Array of parameter definitions
  • description — string — Protocol description
  • requiredCapabilities — array — Required capability types

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• update_protocol

  Update an existing protocol template (must be in draft status). Returns updated name and version.

  Parameters:

  • id (required) — string — Protocol template ID
  • name — string — Updated name
  • steps — array — Updated steps array
  • version — string — New version string (semver)
  • parameters — array — Updated parameters array
  • description — string — Updated description

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• publish_protocol

  Publish a draft protocol template, making it visible in the protocol library for others to discover and use.

  Parameters:

  • id (required) — string — Protocol template ID to publish

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• fork_protocol

  Fork a protocol template to create your own version with parameter overrides. Returns the new fork ID.

  Parameters:

  • id (required) — string — Protocol template ID to fork
  • name — string — Name for the forked protocol
  • parameterOverrides — object — Parameter values to override from the source template

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_protocol_forks read-only

  List all forks of a protocol template. Shows who forked it and what parameters they changed.

  Parameters:

  • id (required) — string — Protocol template ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• validate_protocol

  Validate a protocol template against a specific kernel — checks capability availability, transfer compatibility, and automation level feasibility.

  Parameters:

  • id (required) — string — Protocol template ID
  • kernelId — string — Kernel ID to validate against (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_protocol_runs read-only

  List protocol runs. Filter by status or kernelId.

  Parameters:

  • status — string — Filter by run status
  • kernelId — string — Filter by kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_protocol_run read-only

  Get protocol run status including step progress, transfer status, current phase, and evidence hashes.

  Parameters:

  • runId (required) — string — Protocol run ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• create_protocol_run

  Instantiate a protocol template as a run on a specific kernel with given parameter values.

  Parameters:

  • id (required) — string — Protocol template ID
  • kernelId — string — Kernel ID to run the protocol on
  • sampleIds — array — Sample IDs being processed in this run
  • parameterValues — object — Runtime parameter values (overrides template defaults)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• start_protocol_run

  Start execution of a protocol run that is in 'ready' or 'binding' state.

  Parameters:

  • runId (required) — string — Protocol run ID to start

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pause_protocol_run

  Pause a running protocol run. Use resume_protocol_run to continue.

  Parameters:

  • runId (required) — string — Protocol run ID to pause

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• resume_protocol_run

  Resume a paused protocol run from where it stopped.

  Parameters:

  • runId (required) — string — Protocol run ID to resume

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• cancel_protocol_run

  Cancel a protocol run. Cannot be cancelled once completed or already cancelled.

  Parameters:

  • runId (required) — string — Protocol run ID to cancel

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_workflows read-only

  List active instrument workflows in the orchestrator. Optionally filter by status.

  Parameters:

  • status — string — Filter by workflow status (e.g. running, completed)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_workflow read-only

  Get detailed workflow information including steps, node assignments, and progress.

  Parameters:

  • workflowId (required) — string — Workflow ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_transfer_graphs read-only

  Get resource transfer graphs showing instrument topology, transfer edges, and mechanisms for all kernels.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• list_automation_status read-only

  List automation status for all instrument transfer pairs. Shows current automation level, episode count, and training readiness. Filter by kernelId.

  Parameters:

  • kernelId — string — Filter by kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_automation_status read-only

  Get automation status for a specific instrument-to-instrument transfer pair.

  Parameters:

  • fromNodeId (required) — string — Source instrument node ID
  • toNodeId (required) — string — Destination instrument node ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• record_episode

  Record a transfer episode for a node pair. Increments episode count toward VLA training threshold.

  Parameters:

  • fromNodeId (required) — string — Source instrument node ID
  • toNodeId (required) — string — Destination instrument node ID
  • success — boolean — Whether the episode succeeded
  • episodeId — string — Episode ID (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• advance_automation

  Advance the automation level for a transfer pair (manual → teleoperated → pilot_operated → vla_assisted → fully_autonomous). Requires sufficient training episodes.

  Parameters:

  • fromNodeId (required) — string — Source instrument node ID
  • toNodeId (required) — string — Destination instrument node ID

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_transfer_agents read-only

  List all transfer agents (robots and human operators) available for instrument-to-instrument transfers.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_logistics_overview read-only

  Logistics hub overview: active shipments, pending installations, and upcoming bookings.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_shipments read-only

  List equipment shipments with tracking status. Optionally filter by status.

  Parameters:

  • status — string — Filter by shipment status (in_transit, delivered, pickup_scheduled, etc.)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• create_shipment

  Create a new equipment shipment with origin, destination, package details, and provider.

  Parameters:

  • equipmentDescription (required) — string — Description of equipment being shipped
  • origin — object — Origin location with label, address, geo coordinates
  • package — object — Package details (weightKg, dimensions, fragile, etc.)
  • providerId — string — Logistics provider ID
  • destination — object — Destination location with label, address, geo coordinates

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_shipment_quote

  Get shipping quotes from logistics providers based on origin, destination, weight, and priority.

  Parameters:

  • priority — string — Shipping priority level
  • weightKg — number — Package weight in kg
  • originZip — string — Origin ZIP code
  • destinationZip — string — Destination ZIP code

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_installations read-only

  List equipment installation orders with step progress and status.

  Parameters:

  • status — string — Filter by installation status (draft, scheduled, in_progress, completed)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_space_bookings read-only

  List space bookings for hosting equipment. Optionally filter by status or space.

  Parameters:

  • status — string — Filter by booking status
  • spaceId — string — Filter by space ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• search_spaces read-only

  Search for lab/workshop hosting spaces. Filter by size, access schedule, and other requirements.

  Parameters:

  • access — string — Access schedule (24/7, business-hours, all)
  • maxSqft — number — Maximum square footage

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_space read-only

  Get detailed information about a hosting space including power, amenities, safety features, and pricing.

  Parameters:

  • id (required) — string — Space ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• match_spaces

  Find hosting spaces that match specific machine requirements (voltage, area, etc.). Returns scored matches.

  Parameters:

  • minArea — number — Minimum floor area in square feet
  • voltage — number — Required voltage (e.g. 208, 480)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_marketplace_overview read-only

  Equipment marketplace overview with demand/supply metrics across all capability types.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_equipment_classes read-only

  List equipment classes (FDM printers, CNC mills, etc.) with market snapshot data including utilization, demand, and pricing.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_demand_supply read-only

  Get network-wide demand vs supply timeline data for capacity planning and market analysis.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• calculate_roi

  Calculate ROI projection for onboarding equipment. Returns month-by-month revenue, cost, and break-even analysis.

  Parameters:

  • avgJobValue — number — Average revenue per job in USD
  • monthlyCost — number — Monthly operating cost in USD
  • utilization — number — Expected utilization percentage (0-100)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_operator_dashboard read-only

  Not available: no route answers GET /api/operator on this gateway. The operator's real kernels, devices and in-flight jobs are at GET /api/agent/me.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_operator_machines read-only

  Answers 501 not_available: operator machines with utilization and uptime are not recorded on this gateway. The operator's real kernels, devices and in-flight jobs are at GET /api/agent/me.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_operator_earnings read-only

  Answers 501 not_available: operator earnings history is not recorded on this gateway. Per-job payment state is at GET /api/jobs/:jobId/execution.

  Parameters:

  • period — string — Time period for earnings data

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_operator_certs read-only

  Answers 501 not_available: operator certifications are not recorded on this gateway (there is no certification store; certifications typed at registration are the operator's own claim and are not checked).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_sensor_channels read-only

  List all registered sensor channels across kernels. Returns channel descriptors with units and ranges.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_kernel_sensors read-only

  Get sensor channels for a specific kernel. Returns live channel descriptors.

  Parameters:

  • kernelId (required) — string — Kernel ID to get sensors for

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_settlement_status read-only

  Get settlement pipeline status including pending operations count, total value queued, and smart account address.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_settlement_epochs read-only

  Get settlement epoch history showing past batch settlements with timing and operation counts.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_depin_stats read-only

  DePIN treasury, soulbound capability certificates, and current reward epoch stats.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• mint_certificate

  Mint a soulbound capability certificate (cNFT via Metaplex Core) for a kernel. Proves a verified capability on-chain as an immutable credential. Step 5 of onboarding.

  Parameters:

  • kernelDid (required) — string — DID of the kernel (e.g. did:pcc:kernel:biolab-01)
  • capabilityType (required) — string — Capability type (e.g. fdm, cnc-3axis, hplc)
  • metadata — object — Additional metadata (tolerances, materials, calibration proof CID)
  • assuranceTier — number — Assurance tier (0-3)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• onboard_machine

  Register a new machine on the PCC network. Provide machine details to create a registration record. Include `operator` ({walletAddress, displayName, email}): without it the registration is recorded as operator 0x0000000000000000000000000000000000000000 / "Unknown", and prove cannot match it to you.

  Parameters:

  • name (required) — string — Machine name
  • category (required) — string — Machine category (e.g. fdm, cnc, laser-cut, hplc)
  • model — string — Model identifier
  • operator — object — Who owns this machine. prove and activate match the caller against operator.walletAddress (or operator.email).
  • description — string — Machine description
  • capabilities — array — Array of capability objects
  • manufacturer — string — Manufacturer name

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• analyze_machine_docs

  AI analysis of machine documentation. Upload docs to get suggested capabilities, extracted specs, materials, and tolerances.

  Parameters:

  • document — string — Document content or reference to analyze

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• redeem_invite

  One-click agent onboarding with an invite code. Provisions wallet, identity, LLM access, and PCC tools in a single call.

  Parameters:

  • inviteCode (required) — string — Invite code to redeem
  • email (required) — string — Email address for the account
  • password (required) — string — Password for the account
  • name — string — Display name (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• check_invite read-only

  Validate an invite code before redeeming it. Returns whether the code is valid and what it includes.

  Parameters:

  • code (required) — string — Invite code to check

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• list_batches read-only

  List active and completed settlement batches.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• list_evidence read-only

  List encrypted evidence bundles stored in the gateway.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• submit_demand

  Signal that you want a capability that doesn't exist on the network yet. Creates a demand signal and may auto-create a bounty if enough demand accumulates.

  Parameters:

  • requesterId (required) — string — ID of the requester
  • capabilityType (required) — string — Type of capability wanted (e.g. electron-beam-welding, cryo-em)
  • description (required) — string — Description of what you need
  • assuranceTier — number — Required assurance tier (0-3)
  • estimatedJobValue — number — Estimated payment per job in USD
  • estimatedFrequency — string — How often you would use this capability

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_bounties read-only

  List open bounties for capabilities the network needs. Operators can claim these to earn rewards by onboarding new capabilities.

  Parameters:

  • status — string — Filter by bounty status
  • capabilityType — string — Filter by capability type

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• claim_bounty

  Claim a bounty to onboard a new capability. The operator commits to registering the capability and completing verification.

  Parameters:

  • bountyId (required) — string — ID of the bounty to claim
  • operatorId (required) — string — ID of the operator claiming the bounty

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• verify_bounty

  Verify bounty completion by scoring the delivered capability against requirements.

  Parameters:

  • bountyId (required) — string — Bounty ID to verify
  • jobId (required) — string — Job ID that fulfilled the bounty
  • score (required) — number — Verification score (0-1)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_top_demand read-only

  Get top demand signals aggregated by capability type. Shows which capabilities are most wanted on the network.

  Parameters:

  • limit — number — Number of top demand entries to return (default 10)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_bounty_leaderboard read-only

  Get the bounty hunter leaderboard showing top operators by bounties claimed and verified.

  Parameters:

  • limit — number — Number of entries to return (default 10)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• create_investment_pool

  Create an investment pool for a capability bounty. Stakers earn future protocol fees when the capability goes live.

  Parameters:

  • capabilityType (required) — string — Type of capability to invest in (e.g. cnc-milling, sla-printing)
  • description (required) — string — Description of the capability pool
  • currency — string — Currency for the pool
  • targetAmount — number — Funding target amount

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• stake_in_pool

  Stake USDC or credits into a capability investment pool.

  Parameters:

  • poolId (required) — string — Investment pool ID
  • staker (required) — string — Address or DID of the staker
  • amount (required) — number — Amount to stake

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_pool_earnings read-only

  Check earnings from capability investment pools for a staker address.

  Parameters:

  • staker (required) — string — Address or DID of the staker

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_pool read-only

  Get details of a specific investment pool including stakes, status, and revenue share terms.

  Parameters:

  • poolId (required) — string — Investment pool ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• list_pools read-only

  List all investment pools. Optionally filter by status or capability type.

  Parameters:

  • status — string — Filter by pool status
  • capabilityType — string — Filter by capability type

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• close_pool

  Close an investment pool to new stakes. Pool enters sunset phase.

  Parameters:

  • poolId (required) — string — Pool ID to close

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• claim_pool

  Operator claims an investment pool reward after capability verification.

  Parameters:

  • poolId (required) — string — Pool ID to claim
  • operatorId (required) — string — Operator ID making the claim

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• convert_bounty_to_pool

  Convert an existing bounty into an investment pool. Allows community staking toward the bounty's capability.

  Parameters:

  • bountyId (required) — string — Bounty ID to convert to a pool

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_subnet_status read-only

  Get Bittensor verification subnet health, agent bridge status, and network connectivity.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_subnet_miners read-only

  List verification subnet miners on the Bittensor network. Returns miner addresses, scores, and leaderboard positions.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• list_conversations read-only

  List agent-to-agent conversations showing topic, participants, message count, and status.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• submit_feedback

  Submit a bug report, suggestion, or general feedback about the PCC network.

  Parameters:

  • message (required) — string — Feedback message (max 5000 chars)
  • page — string — Page or feature the feedback relates to
  • type — string — Feedback type

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• report_anomaly

  Report a detected anomaly — protocol failure, evidence mismatch, stuck job, or suspicious behavior. All agents on the network are notified.

  Parameters:

  • severity (required) — string — Anomaly severity
  • category (required) — string — Anomaly category
  • description (required) — string — Human-readable description of what went wrong
  • jobId — string — Related job ID (optional)
  • targetAgentId — string — Agent or kernel ID being reported (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_unresolved_anomalies read-only

  List all unresolved anomalies on the network. Filter by severity, category, or target agent.

  Parameters:

  • category — string — Filter by category
  • severity — string — Filter by severity: info, warning, critical
  • targetId — string — Filter by target agent/kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_agent_anomalies read-only

  Get anomalies involving a specific agent, plus their trust impact score.

  Parameters:

  • agentId (required) — string — Agent or kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• resolve_anomaly

  Mark an anomaly as resolved with a resolution note.

  Parameters:

  • anomalyId (required) — string — Anomaly ID to resolve
  • resolution (required) — string — How the anomaly was resolved

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_anomaly_stats read-only

  Get aggregate anomaly statistics — total, unresolved, by severity, by category.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• report_protocol_failure

  Report a protocol failure — when a step in the evidence/escrow/verification pipeline breaks. System may auto-recover.

  Parameters:

  • protocol (required) — string — Which protocol failed: evidence_submission, escrow_release, verification_consensus, settlement
  • errorCode (required) — string — Error code
  • errorMessage (required) — string — Error description
  • involvedAgents (required) — array — Agent IDs involved
  • jobId — string — Related job ID
  • recoveryAction — string — Suggested recovery

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_dht_query

  Query the DHT for capabilities matching your requirements. Returns announcements from operators whose equipment matches the type, materials, and price range you specify.

  Parameters:

  • type — string — Capability type to search for (e.g. 'fdm_print', 'liquid-handler', 'cnc-3axis')
  • limit — number — Maximum results to return (default 10)
  • maxPrice — number — Maximum price per job — matches operators whose min price is at or below this
  • materials — array — Materials you need (matches if operator supports ANY of these)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_dht_announce

  Announce capabilities to the DHT network. Signs the announcement with your node's Ed25519 key and broadcasts to connected peers.

  Parameters:

  • kernelId (required) — string — Kernel ID announcing capabilities
  • capabilities (required) — array — Array of capability summaries to announce
  • ttlSeconds — number — How long the announcement is valid (default 300)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_dht_peers read-only

  List known DHT peers and their connection status. Shows which nodes are currently connected to the gossip network.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_create_scope

  Create an execution scope for a job. Scopes define exactly which tool calls are allowed on a kernel during a job, with command budgets, retry limits, and time-to-live. Required before issuing SCOPED WRITE operations (protocol upload, run create, run action).

  Parameters:

  • kernelId (required) — string — Kernel ID to create the scope for
  • allowedTools (required) — array — List of tool names allowed in this scope (e.g. ['ot2_protocol_upload', 'ot2_run_create', 'ot2_run_action'])
  • jobId — string — Job ID this scope is bound to (optional)
  • maxRetries — number — Maximum retries allowed (default 3)
  • ttlMinutes — number — Scope duration in minutes (default 30)
  • maxCommands — number — Maximum tool calls allowed in this scope (default 100)
  • allowedSlots — array — Which deck slots may be accessed (e.g. [1, 2, 3, 9])
  • protocolHash — string — SHA-256 hash of the approved protocol content. If set, protocol uploads are hash-verified.
  • allowedPipettes — array — Which pipettes may be used (e.g. ['left'])

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_revoke_scope

  Revoke an execution scope immediately (emergency stop). All pending tool calls under this scope are rejected. The kernel enters a stopped state. A new scope must be created to resume.

  Parameters:

  • scopeId (required) — string — Scope ID to revoke

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_scope_audit read-only

  Get the audit trail for an execution scope — every tool call made under this scope, with validation results, timestamps, and outcomes.

  Parameters:

  • scopeId (required) — string — Scope ID to audit

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_relay_tool_call

  Relay a tool call to a device executor. The brain (LLM) posts tool calls here; the executor (on the device) polls for them and executes locally. Used for the brain/executor split architecture.

  Parameters:

  • kernelId (required) — string — Kernel ID of the target device
  • toolName (required) — string — Tool to execute (e.g. 'ot2_health', 'ot2_run_create')
  • toolArgs (required) — object — Arguments for the tool call
  • scopeId — string — Execution scope ID (required for SCOPED WRITE tools)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_get_tool_result read-only

  Get the result of a previously relayed tool call. Poll this endpoint until the executor has processed the call and posted results.

  Parameters:

  • callId (required) — string — Tool call ID returned from pcc_relay_tool_call

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_camera_latest read-only

  Get the latest camera frame from a kernel as a JSON snapshot (base64 JPEG + metadata). For raw JPEG image, use GET /api/ot2/camera/latest directly.

  Parameters:

  • kernelId (required) — string — Kernel ID to get camera frame from

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_chat_send

  Send a chat message to a kernel's operator or agent. Used for human-in-the-loop communication during job execution, troubleshooting, and escalation.

  Parameters:

  • kernelId (required) — string — Kernel ID to send the message to
  • message (required) — string — Message content
  • role — string — Sender role (default: user)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_chat_history read-only

  Get chat history with a kernel. Returns messages between agents, operators, and users for a specific kernel.

  Parameters:

  • kernelId (required) — string — Kernel ID to get chat history for
  • limit — number — Maximum messages to return (default 50)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• approve_registration

  Approve a submitted machine registration. Moves it from 'submitted' to 'approved' status, enabling the operator to activate and start accepting jobs.

  Parameters:

  • registrationId (required) — string — Registration ID (e.g. 'reg-1234567890')

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• reject_registration

  Reject a machine registration with a reason. The operator can see the rejection reason and resubmit.

  Parameters:

  • registrationId (required) — string — Registration ID
  • reason — string — Reason for rejection

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• activate_registration

  Activate an approved registration, making the operator's equipment live on the network and ready to accept jobs.

  Parameters:

  • registrationId (required) — string — Registration ID

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• prove_registration

  Fast-track: submit evidence that your device works and get auto-approved + activated immediately. No manual review needed. Submit a photo of test output, device health snapshot, or a full evidence bundle with completion events. If evidence meets requirements, registration jumps straight to 'active'.

  Parameters:

  • registrationId (required) — string — Registration ID to prove
  • evidence (required) — object — Evidence proving the device works. Include at least one of: bundleHash+events, photoBase64, or deviceHealth.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_registrations read-only

  List all machine registrations on the network. See pending, approved, active, and rejected registrations. Public endpoint — no auth required.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_registration read-only

  Get details of a specific machine registration by ID, including capabilities, pricing, operator info, and current status.

  Parameters:

  • registrationId (required) — string — Registration ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• near_status read-only

  Get NEAR Protocol chain-abstraction integration status. Returns supported chains (near, eth, base, arbitrum, optimism, polygon), supported assets (USDC, USDT, NEAR, ETH, WBTC), and capability flags. Use this to confirm cross-chain settlement is available before requesting quotes.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• near_quote

  Get a cross-chain payment quote from the NEAR 1Click solver network (chaindefuser.com). Provides optimal routing and fee estimates for funding PCC escrow contracts using any source asset on any supported chain. Call near_status first to confirm available chains/assets.

  Parameters:

  • fromChain (required) — string — Source chain (e.g. 'eth', 'base', 'near', 'arbitrum')
  • fromAsset (required) — string — Source asset symbol (e.g. 'USDC', 'ETH', 'NEAR')
  • toChain (required) — string — Destination chain (e.g. 'base', 'eth')
  • toAsset (required) — string — Destination asset symbol (e.g. 'USDC')
  • amount (required) — string — Amount as an integer string in the smallest denomination (e.g. '1000000' for 1 USDC with 6 decimals)
  • recipient — string — Recipient address on the destination chain (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• near_intent

  Submit a cross-chain payment intent to the NEAR 1Click solver network. Creates a signed intent that routes the payment atomically across chains. Call near_quote first to obtain a quoteId. Intents typically settle within 30-60 seconds — poll near_intent_status to track progress.

  Parameters:

  • quoteId (required) — string — Quote ID returned from near_quote
  • workflowId (required) — string — PCC workflow or job ID this payment is for
  • recipient — string — Recipient address on the destination chain (optional)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• near_intent_status read-only

  Check the settlement status of a submitted NEAR 1Click cross-chain payment intent. Statuses progress: pending → submitted → settled | failed. Returns txHash and explorerUrl when settled.

  Parameters:

  • intentId (required) — string — Intent ID returned from near_intent

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• protocol_state read-only

  Read the PCCProtocol root contract state: current fee rate, total protocol fees collected, total escrow count, and registry addresses. Requires PCC_PROTOCOL_ADDRESS to be configured on the gateway.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• protocol_fee read-only

  Calculate the protocol fee for a given USDC amount (6-decimal units). Returns the fee, the net amount after fee, and formatted versions of both. Use this before building escrow contracts to understand the true cost.

  Parameters:

  • amount (required) — string — Amount as a BigInt string in USDC 6-decimal units (e.g. '1000000000' = 1000 USDC)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• protocol_token_fees read-only

  Get total protocol fees collected for a specific ERC-20 token address across all escrows. Returns raw wei amount and human-readable formatted value.

  Parameters:

  • tokenAddress (required) — string — ERC-20 token contract address (0x...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• protocol_escrow_fees read-only

  Get protocol fees collected from a specific escrow contract. Also returns whether the escrow was deployed via the protocol factory. Useful for auditing fee flows.

  Parameters:

  • escrowAddress (required) — string — Escrow contract address (0x...)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• protocol_create_escrow

  Create a new MilestoneEscrow contract via the PCCProtocol factory on-chain. Protocol-deployed escrows have fee collection and registry tracking built in. Requires PCC_GATEWAY_PRIVATE_KEY write access.

  Parameters:

  • payer (required) — string — Payer EVM address (0x...)
  • arbiter (required) — string — Arbiter EVM address (0x...) — resolves disputes
  • token (required) — string — ERC-20 token address for payment (0x...)
  • cwmId (required) — string — Capability Work Module ID as a 32-byte hex string (0x + 64 chars)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_dht_metrics read-only

  Get a snapshot of DHT telemetry counters and recent events. Returns message counts, peer connection stats, query/announce rates, and a list of the last 50 metric events. Use for monitoring network health.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• marketplace_categories read-only

  List all supplies and materials marketplace categories with the count of active listings in each. Categories cover the full spectrum of physical production inputs: raw metals, plastics, lab reagents, consumables, electronics, tooling, and more.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• marketplace_list_listings read-only

  Search and filter supplies/materials marketplace listings. Operators buy raw materials here to fulfill capability contracts. Filter by category, in-stock status, location, or free-text query.

  Parameters:

  • query — string — Full-text search across name, description, and tags
  • inStock — string — Filter to only in-stock listings
  • category — string — Filter by category: raw-metals, plastics-polymers, lab-reagents, lab-consumables, electronics, chemicals, biologicals, tooling, packaging, calibration, safety, other
  • location — string — Filter by region (e.g. 'US-Midwest', 'EU-West', 'Asia-Pacific')

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• marketplace_get_listing read-only

  Get full details of a specific supplies/materials marketplace listing by ID. Returns pricing, availability, lead time, location, and tags.

  Parameters:

  • id (required) — string — Listing ID (e.g. 'lst-al6061-bar')

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• marketplace_create_listing

  Create a new supplies/materials listing in the marketplace. Suppliers post available raw materials, lab reagents, tooling, or consumables for other operators to purchase.

  Parameters:

  • category (required) — string — Category: raw-metals, plastics-polymers, lab-reagents, lab-consumables, electronics, chemicals, biologicals, tooling, packaging, calibration, safety, other
  • name (required) — string — Product name
  • pricePerUnit (required) — number — Price per unit in USDC
  • unit (required) — string — Unit of sale: kg, L, each, box, plate, etc.
  • tags — array — Search tags
  • inStock — boolean — Whether the item is currently available
  • location — string — Supplier region or country
  • maxOrder — number — Maximum order quantity
  • minOrder — number — Minimum order quantity
  • sellerId — string — Supplier entity ID
  • description — string — Detailed product description
  • leadTimeDays — number — Estimated lead time in business days

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• marketplace_update_listing

  Update an existing supplies/materials listing (price, stock status, description, etc.). Pass only the fields you want to change.

  Parameters:

  • id (required) — string — Listing ID to update
  • tags — array — Updated search tags
  • inStock — boolean — Stock availability
  • description — string — Updated description
  • leadTimeDays — number — Updated lead time in days
  • pricePerUnit — number — New price per unit in USDC

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• marketplace_delete_listing destructive

  Remove a supplies/materials listing from the marketplace. The listing is immediately hidden from search results.

  Parameters:

  • id (required) — string — Listing ID to remove

  Hints: read-only no · destructive yes · idempotent not declared · open-world not declared

• marketplace_place_order

  Place a purchase order for supplies or materials. Calculates total price automatically (quantity × pricePerUnit). Returns an order with 'pending' status. Optionally links to an on-chain escrow for trustless settlement.

  Parameters:

  • listingId (required) — string — Listing ID to order from
  • quantity (required) — number — Quantity to order (must meet listing minOrder/maxOrder)
  • buyerId — string — Buyer entity ID (operator kernel ID, etc.)
  • escrowAddress — string — Optional on-chain escrow address for trustless settlement

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• marketplace_list_orders read-only

  List marketplace supply orders. Filter by buyerId, sellerId, or status. Returns order history with pricing and status.

  Parameters:

  • status — string — Filter by order status
  • buyerId — string — Filter to orders placed by this buyer
  • sellerId — string — Filter to orders received by this seller

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• marketplace_get_order read-only

  Get details of a specific supply order including the associated listing details, quantity, total price, status, and optional escrow address.

  Parameters:

  • id (required) — string — Order ID (e.g. 'ord-demo-001')

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• system_telemetry read-only

  Raw system state dump — actual DB rows for kernels, devices, jobs, evidence, registrations, capabilities, agent conversations, audit log. No fake numbers, no summaries.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• operator_poll_jobs read-only

  Operator polls jobs assigned to their kernel; status defaults to queued, and the route can filter any status. Requires operate authority for this kernel: its recorded operator identity (the caller that registered it), its proven operator wallet, or the gateway admin authority. Another identity gets 403; no credentials gets 401; an unregistered kernel gets 404 for a non-admin. Operator identity proof for operate is completed by WP-A (DECISIONS items 136 and 138). The pcc-node 0.1.1 daemon does not call it: it takes no jobs.

  Parameters:

  • kernelId (required) — string — Kernel ID to poll jobs for

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• operator_push_evidence

  Operator pushes evidence bundle from a completed job execution. Requires decide authority for the stored job's kernel: its proven operator wallet or the gateway admin authority. A matching claimed operator key gets 403 operator_proof_required. Evidence takes decide, per DECISIONS 2026-10-04 01:25 (N31c). Evidence is posted with the kernel's proven operator wallet authority (decide). The body's kernelId cannot choose the authorization target. No credentials gets 401 before the job read; a job without a kernel gets 403 for a non-admin. Contains device ID, execution timestamp, result payload, and event timeline. Success is a receipt with stored: true naming this jobId. HTTP 200 with stored: false means nothing was stored: never follow it with status completed.

  Parameters:

  • jobId (required) — string
  • kernelId (required) — string
  • evidence (required) — object

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• operator_heartbeat

  Operator sends heartbeat with capability re-announcement. Keeps the kernel alive on the network and updates its own capability rows. Requires operate authority for this kernel: its recorded operator identity (the caller that registered it), its proven operator wallet, or the gateway admin authority. Another identity gets 403; no credentials gets 401; an unregistered kernel gets 404 for a non-admin. Operator identity proof for operate is completed by WP-A (DECISIONS items 136 and 138).

  Parameters:

  • kernelId (required) — string
  • capabilities — array

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• operator_update_job_status

  Operator reports a job's status (in_progress, completed, failed). Requires operate authority for the stored job's kernel: its recorded operator identity (the caller that registered it), its proven operator wallet, or the gateway admin authority. The body's kernelId cannot choose the authorization target. Another identity gets 403; no credentials gets 401 before the job read; a job without a kernel gets 403 for a non-admin. Operator identity proof for operate is completed by WP-A (DECISIONS items 136 and 138). The node path finishes a job in two calls: submit its evidence (POST /api/operator/evidence, posted with the kernel's proven operator wallet authority, decide), and only if that receipt says stored: true for this jobId, set status completed here. HTTP 200 alone is not enough: the relay answers 200 with stored: false when it could not store the evidence (an unknown job, a storage failure); then set failed with the reason evidence_not_stored. On the current gateway, completed marks the job done and its timeline then says settled, but the escrow is not released yet (board G1). Do not call pcc_job_complete after this: it answers 409.

  Parameters:

  • jobId (required) — string
  • kernelId (required) — string
  • status (required) — string
  • metadata — object

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_submit_paid_job

  Fast-track paid job: one call from DHT discovery to funded escrow + active scope. Auto-negotiates, quotes, creates escrow with milestones, creates execution scope. Returns jobId, scopeId, escrowId, quote with pricing adjustments, contract terms. For testnet, escrow is mock-funded automatically.

  Parameters:

  • kernelId (required) — string — Target kernel ID (from DHT query)
  • capabilityType (required) — string — e.g. 'liquid-handler', 'fdm', 'cnc-3axis'
  • userAgentId (required) — string — Your agent/user ID
  • parameters — object — Job parameters (protocolType, volume, materials, etc.)
  • paymentMethod — string — Payment method (testnet-mock for demo)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_job_complete

  Complete a job: gathers tool call audit trail from execution scopes, builds evidence bundle with SHA-256 hash, stores evidence, revokes scopes, and settles escrow (mock or real). This is how a job run through execution scopes is finished. A node that submitted its evidence and set status completed (operator_update_job_status) must not call it: it then answers 409 ("Job already completed or completion in progress").

  Parameters:

  • jobId (required) — string — Job ID to complete
  • message — string — Completion message or notes

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_job_settlement read-only

  Get a job's settlement status from its own escrow records: status (settled only when a settlement read confirms the release; reported_released when the milestone record says released but nothing confirms it; simulated for a mock escrow; awaiting_settlement, no_settlement_record, unknown or unavailable otherwise), settled, payout, paidAmount (confirmed releases only), reportedReleasedAmount, quotedAmount, currency (recorded or null), escrow, milestones, the negotiation session, notices and asOf.

  Parameters:

  • jobId (required) — string — Job ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_get_tool_manifest read-only

  Get the tool manifest for a kernel's device type. Lists all available tools with their safety classification (read, safe_control, scoped_write, privileged) and input schemas. Use to understand what tools are available before making tool calls.

  Parameters:

  • kernelId (required) — string — Kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_relay_generic_tool_call

  Relay a tool call to any kernel's device executor via the generic relay (not OT-2 specific). Works with any device type. Safe tools (read/safe_control) don't need a scope. Scoped write tools require an active execution scope. Returns a call ID — poll pcc_get_tool_result for the response.

  Parameters:

  • kernelId (required) — string — Target kernel ID
  • toolName (required) — string — Tool name from the device manifest
  • args — object — Tool arguments
  • scopeId — string — Execution scope ID (required for write operations)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_submit_request

  Submit a high-level capability request in natural language. The system automatically decomposes it into a capability DAG with dependencies, timelines, and budget allocation across fabrication, design, assembly, electronics, software, logistics, and verification nodes. Returns the request with full decomposed DAG. Example: 'Build a cute animatronic plush desk robot with servo-driven animations'.

  Parameters:

  • title (required) — string — Short title for the request
  • description (required) — string — Full natural language description of what needs to be built or done
  • budget — number — Total budget in USDC (default: 1000)
  • urgency — string — Urgency level — affects cost multipliers (emergency: 2x cost, 0.5x time)
  • currency — string — Currency (default: USDC)
  • deadline — string — ISO 8601 deadline (default: 7 days from now)
  • requesterEmail — string — Requester email for notifications
  • requesterWallet — string — Requester wallet address for payments

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_list_requests read-only

  List all capability requests with optional filtering. Shows status, decomposed DAG summary, estimated costs, and timelines.

  Parameters:

  • status — string — Filter by status
  • urgency — string — Filter by urgency
  • requesterEmail — string — Filter by requester email

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_get_request read-only

  Get a capability request by ID with the full decomposed DAG — all capability nodes, their dependencies, estimated costs/hours, assigned operators, and linked bounty IDs.

  Parameters:

  • requestId (required) — string — Request ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_decompose_request

  Re-trigger decomposition of an existing capability request. Overwrites the existing capability DAG with a fresh decomposition. Useful after updating the description or budget.

  Parameters:

  • requestId (required) — string — Request ID to decompose

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_publish_request

  Publish all pending capability nodes in a request as bounties. Each node becomes a bidding opportunity for operators. Returns the list of created bounty IDs linked to each capability node.

  Parameters:

  • requestId (required) — string — Request ID to publish

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_get_request_dag read-only

  Get the capability DAG (directed acyclic graph) for a request as adjacency data — nodes with all fields plus explicit edges showing dependency relationships. Useful for visualization or workflow planning.

  Parameters:

  • requestId (required) — string — Request ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_get_request_critical_path read-only

  Get the critical path (longest dependency chain) for a capability request. The critical path determines the minimum calendar time to complete the request. Returns node IDs in order, the full node details, and total hours on the critical path.

  Parameters:

  • requestId (required) — string — Request ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_assign_node_operator

  Assign an operator to a specific capability node within a request. The node status changes to 'assigned'. Operators claim nodes to indicate they will execute that capability.

  Parameters:

  • requestId (required) — string — Request ID
  • nodeId (required) — string — Capability node ID
  • operatorId (required) — string — Operator kernel ID or wallet address

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_update_node_status

  Update the status of a capability node within a request. Valid transitions: pending → bidding → assigned → in_progress → completed (or failed). When all nodes complete, the request automatically moves to completed.

  Parameters:

  • requestId (required) — string — Request ID
  • nodeId (required) — string — Capability node ID
  • status (required) — string — New status for the node

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_update_request

  Update a capability request's title, description, budget, deadline, urgency, or contact info. Does not re-decompose — call pcc_decompose_request afterwards if you want a fresh DAG.

  Parameters:

  • requestId (required) — string — Request ID
  • title — string
  • budget — number
  • urgency — string
  • deadline — string
  • description — string
  • requesterEmail — string
  • requesterWallet — string

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_cancel_request destructive

  Cancel a capability request. Cancelled requests cannot be updated, decomposed, or published. This is a soft delete — the request remains visible with status 'cancelled'.

  Parameters:

  • requestId (required) — string — Request ID to cancel

  Hints: read-only no · destructive yes · idempotent not declared · open-world not declared

• pcc_oracle_status read-only

  Not served by the PCC gateway: GET /api/oracle/health returns 404 there. PCC's verification oracle runs as a separate service, and this route answers only where a deployment fronts it. Agents never call the oracle to settle a job: settlement is the gateway's step after pcc_job_complete. Where it is served, it returns the oracle's EIP-712 signing address and chain ID.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_oracle_verify

  Not served by the PCC gateway: POST /api/oracle/verify returns 404 there. PCC's verification oracle runs as a separate service, and this route answers only where a deployment fronts it. Agents never call it to settle a job: settlement is the gateway's step after pcc_job_complete. Where it is served, it checks that the evidence exists, its hash matches, tier requirements are met, there is no replay and the operator identity is valid, and it returns a signed EIP-712 attestation.

  Parameters:

  • escrowAddress (required) — string — Escrow contract address
  • jobId (required) — string — PCC job ID
  • kernelId (required) — string — Operator kernel ID
  • evidenceHash (required) — string — SHA-256 hash of evidence bundle
  • assuranceTier — integer — Evidence tier (0=none, 1=basic, 2=full, 3=ZK)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_protocol_fee read-only

  Get the current protocol fee rate (2.35%, immutable) and fee recipient address. The fee is hardcoded in the PCCProtocol smart contract — no admin, no governance, no upgrade can change it.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• create_capability

  Register a capability instance for a kernel. Required before submitting jobs — the gateway needs at least one capability per kernel. Creates a liquid-handler, fdm, cnc-3axis, or other capability type.

  Parameters:

  • kernelId (required) — string — Kernel ID to register capability for
  • type (required) — string — Capability type (e.g. liquid-handler, fdm, cnc-3axis, laser-cut, document-printing)
  • name — string — Human-readable name for the capability
  • description — string — Description of what this capability does

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• kernel_heartbeat

  Send a per-kernel heartbeat to keep the kernel marked online. Used by pcc-node daemons as an alternative to the operator relay heartbeat.

  Parameters:

  • kernelId (required) — string — Kernel ID
  • status — string — Kernel status (online/offline)
  • capabilities — array — Optional capability announcements

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• kernel_announce_capabilities

  Announce capabilities for a kernel. NOTE: the gateway currently acknowledges this call but stores nothing, so it does not put any capability on the network. To publish a capability, use create_capability (POST /api/capabilities).

  Parameters:

  • kernelId (required) — string — Kernel ID
  • capabilities (required) — array — Capability objects to announce
  • devices — array — Device IDs that back these capabilities
  • signature — string — Ed25519 signature of the announcement

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• send_diagnostics

  Upload an encrypted diagnostic bundle when the operator's node has problems. The bundle is encrypted client-side with a retrieval code the operator must share with support before logs can be read. Use this when the operator reports errors, crashes, or misbehavior. The pcc-node CLI runs `pcc-node logs --send` locally to collect+encrypt; prefer that path when available. This tool is for agent-driven uploads when the bundle is already prepared.

  Parameters:

  • kernelId (required) — string — Kernel ID the diagnostics came from
  • encrypted (required) — object — Encrypted bundle payload
  • bundleHash — string — sha256 of plaintext bundle
  • bundleSize — number — Size of encrypted payload in bytes
  • collectedAt — string — ISO timestamp when bundle was collected
  • logLineCount — number — How many log lines are in the bundle
  • systemPlatform — string — e.g. Linux-5.15, Darwin-23, Windows-10

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• send_support_message

  Send an operator support message to the PCC team. Creates a new support thread or appends to the operator's existing open thread. Can optionally attach a diagnostic retrieval code (from send_diagnostics) so support staff can decrypt logs. Discord webhook fires on every new message, so expect fast response. Use this whenever the operator says something is broken, confusing, or not behaving as expected.

  Parameters:

  • kernelId (required) — string — Operator's kernel ID
  • message (required) — string — The support message text — describe the problem concretely
  • subject — string — Optional thread subject (auto-generated from message if omitted)
  • kernelName — string — Human-readable kernel name
  • systemInfo — object — Optional system context (platform, nodeVersion, daemonRunning, gatewayReachable)
  • retrievalCode — string — Optional diagnostic retrieval code to attach (from send_diagnostics)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• check_support_replies read-only

  Check for admin replies on the operator's support threads. Call this periodically or when the operator asks 'did they respond yet?'. Returns all threads for this kernel and a hasUnreadReplies boolean indicating new admin messages.

  Parameters:

  • kernelId (required) — string — Operator's kernel ID

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• reply_to_support_thread

  Reply to an existing support thread. Use when the operator wants to add information to a thread started earlier. Needs the threadId from check_support_replies or the original send_support_message response.

  Parameters:

  • threadId (required) — string — Thread ID to reply to
  • message (required) — string — Reply message
  • retrievalCode — string — Optional diagnostic retrieval code to attach

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_capture_challenge

  Issue a fresh block-anchored CaptureNonceChallenge for a job. The operator's device must render this nonce into the captured media (QR code, audio tone, etc.) before calling pcc_capture_upload. The nonce is derived from (challengeId, latest blockHash, workOutputRoot) so captures cannot be pre-computed. Returns challengeId, 64-char hex nonce, blockNumber, maxAgeSeconds (clamped to 120).

  Parameters:

  • jobId (required) — string — PCC job ID the capture belongs to
  • declaredClass (required) — string — Capture class the operator plans to claim. Determines which gates the verifier will run.
  • requestedTtlSeconds — integer — Requested challenge lifetime in seconds. Clamped to 120 server-side.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_capture_upload

  Upload a capture (photo / video / audio / sensor clip) with its CaptureManifest for G1..G6 verification. Bytes are base64-encoded inline; optional base64 C2PA manifest bytes can be supplied for CC3+ claims. The server runs the 6-gate CaptureVerifier and persists a PASS/PARTIAL/FAIL verdict. Returns {verdictId, verdict, verifiedClass, gatesPassed, gatesFailed, warnings, anchorCandidate, captureHash, manifestHash}.

  Parameters:

  • manifest (required) — object — CaptureManifest — ALCOA+-ready metadata: class, declaredAt (ISO-8601), deviceFingerprint, mediaHash (sha256:<hex>), optional challengeId. See CaptureManifestSchema in @pcc/spec.
  • captureBytesBase64 (required) — string — Base64-encoded capture bytes (image / video / audio / sensor clip). Hash must match manifest.mediaHash.
  • jobId — string — Job ID for telemetry binding. Falls back to manifest.jobId if omitted.
  • operatorId — string — Explicit operator ID. Falls back to the authenticated session userId.
  • challengeId — string — Challenge UUID to re-bind to the in-memory challenge cache (G3 freshness gate).
  • submittedAt — integer — Client-submitted timestamp (epoch ms). Used in drift detection.
  • visualNonceEcho — string — The visual nonce value the operator rendered in-scene (QR payload, audio tone id, etc.).
  • c2paManifestBase64 — string — Optional base64-encoded C2PA manifest JUMBF bytes. Required when manifest.class >= CC3.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_capture_anchor

  Anchor a PASS + anchor-candidate capture verdict to CaptureClassRegistry on-chain (Base Sepolia by default). Rejects FAIL/PARTIAL verdicts. Idempotent — re-submitting the same verdictId returns the existing anchor row. Returns 202 {status:'deferred'} if CaptureClassRegistry is not yet deployed (CAPTURE_REGISTRY_ADDRESS unset).

  Parameters:

  • verdictId (required) — string — The verdictId returned by pcc_capture_upload. Must be a PASS verdict with anchorCandidate=true.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_capture_status read-only

  Fetch the combined verdict + on-chain anchor view for a single capture. Mirrors the verifier's DB shape plus the anchor tx metadata (txHash, blockNumber, gasUsed, explorerUrl). Anchor is null if the verdict was never anchored.

  Parameters:

  • verdictId (required) — string — Capture verdict UUID (from pcc_capture_upload).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_list_verdicts read-only

  List recent capture verdicts, newest first. Optionally filter by jobId. Default limit is 50, capped at 200 server-side. Returns {verdicts, count, limit, jobId}.

  Parameters:

  • jobId — string — Filter by job ID. Omit for all verdicts across jobs.
  • limit — integer — Maximum rows returned (default 50, hard cap 200).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_capture_class_registry read-only

  Look up a capture's on-chain anchor record in CaptureClassRegistry by its 32-byte captureHash. Returns the registry address, captureHash, and decoded anchor tuple (declaredClass, verifiedClass, manifestHash, submittedBy, jobId, challengeId, blockAnchor, capturedAt, attestationsRoot, attesterCount). onchain is null if the capture was never anchored. Returns 202 deferred when CaptureClassRegistry is not yet deployed.

  Parameters:

  • captureHash (required) — string — Capture hash (32-byte). Accepts 0x-prefixed or unprefixed hex, or sha256:<hex> format. Padded server-side to bytes32.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_verifier_health read-only

  Report CaptureVerifier health: which adapters are loaded (c2pa, webauthn, appattest, playintegrity), their staleness status, in-memory challenge cache size, whether CaptureClassRegistry is deployed, and the active PCC_NETWORK. Use this to diagnose why a capture class is being rejected or degraded.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_orchestrator_list_templates read-only

  List the orchestrator templates the dashboard's chat console can drive. Each entry includes slug, display_name, description, produces_kind, capability_class (physical | digital), greeting, and api_base (the route prefix that serves the six session-driver routes for that template). Public — no auth required.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_orchestrator_match_capabilities

  Heuristic template matcher. Pass a free-text description of what you want to onboard (e.g. 'I run a CNC milling shop' or 'I have a Postgres database with a GraphQL endpoint') and the matcher returns all templates ranked by keyword score with a 'reason' string per match. Public — no auth required.

  Parameters:

  • input (required) — string — Free-text description of what you want to onboard.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_onboard_session_start

  Start a new physical-operator onboarding session. Returns a session_id used by every subsequent /api/onboard/* call. Auth-required.

  Parameters:

  • name (required) — string — Operator / company name (e.g. 'Oakland Titanium Mills').
  • url — string — Optional company website. If supplied, the orchestrator scrapes it on the next /scrape call.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_onboard_session_scrape

  Scrape a URL into the running physical-operator onboarding session. Triggers a stealth fetch + structured extraction (machines, hours, services, certifications). Returns a small JSON summary; full extraction is appended to the session's running profile and visible via /live-data. Auth-required.

  Parameters:

  • id (required) — string — Session id returned by pcc_onboard_session_start.
  • url (required) — string — URL to scrape (e.g. company About page).

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_onboard_session_ingest_docs

  Queue documents (datasheets, SOPs, MOPs, certifications) for ingestion into a physical-operator onboarding session. Document URLs may be local:// for files dropped in the chat console or full https:// URLs. Auth-required.

  Parameters:

  • id (required) — string — Session id returned by pcc_onboard_session_start.
  • doc_urls (required) — array — URLs of documents to ingest. Mix of local:// and https:// is fine.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_onboard_session_build_agent

  Finalise a physical-operator onboarding session: registers the operator on PCC, mints a wallet, writes the SEO mirror, returns the publication payload (capabilities, operator_id, discovery_url). Idempotent — safe to retry inside the same session_id. Auth-required.

  Parameters:

  • id (required) — string — Session id returned by pcc_onboard_session_start.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_onboard_session_status read-only

  Coarse status snapshot for a physical-operator onboarding session: current state, 0-100 progress, scraped_count, ingested_count, last_event, publication payload (if built). Cheap — designed for polling from the chat header. Auth-required.

  Parameters:

  • id (required) — string — Session id returned by pcc_onboard_session_start.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_onboard_session_live_data read-only

  Full event log for a physical-operator onboarding session — feeds the chat console's activity sidebar. Supports incremental polling via ?since=<unix-millis>. Returns the next cursor on every response. Auth-required.

  Parameters:

  • id (required) — string — Session id returned by pcc_onboard_session_start.
  • since — number — Unix milliseconds cursor — returns only events with t > since. Use the 'cursor' field of the previous response for incremental polling.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_contributor_register

  Register a contributor profile binding a wallet address to a role and a published RateSchedule. Body: address (0x40hex), role (10 ContributorRole values from ADR-12 §2.1 + legacy 'designer'), scheduleHash (0x64hex of a previously published schedule), optional ipId, metadataUri, contributorNftTokenId. Returns the persisted profile (composite id is address:role:tail). Idempotent on the composite id — re-posting the same (address, role, contributorNftTokenId) replaces the prior profile.

  Parameters:

  • address (required) — string — Wallet address (0x + 40 hex chars)
  • role (required) — string — ContributorRole — 10 ADR-12 roles + deprecated 'designer'
  • scheduleHash (required) — string — 0x + 64 hex sha256 of a published RateSchedule
  • ipId — string — Optional Story Protocol IP Asset ID
  • metadataUri — string — Optional ipfs:// or https:// URI
  • contributorNftTokenId — string — Optional ContributorNFT tokenId once minted on-chain

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_contributor_list read-only

  List all contributor profiles for an address across roles. Returns an array of {id, address, role, scheduleHash, ipId, contributorNftTokenId, metadataUri, registeredAt}. Returns empty array when no profiles exist for the address.

  Parameters:

  • address (required) — string — Wallet address (0x + 40 hex chars)

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_schedule_publish

  Publish a sealed off-chain RateSchedule. Computes scheduleHash server-side via the canonical sha256-over-canonical-JSON algorithm (matching the on-chain RateScheduleRegistry.publish() invariant). Idempotent: re-publishing the same content returns alreadyPublished:true. Returns {scheduleHash, alreadyPublished}.

  Parameters:

  • publishedBy (required) — string — Address that publishes (0x + 40 hex chars)
  • schedule (required) — object — RateSchedule body — version, segments (constant/step/linear-decay/exponential-decay/adoption-indexed/piecewise-value), and optional notes

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_schedule_get read-only

  Fetch a published RateSchedule by its content hash. Returns {schedule, publishedBy} with segments re-validated via Zod, or 404 if not found.

  Parameters:

  • scheduleHash (required) — string — 0x + 64 hex sha256 of the schedule

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_schedule_evaluate

  Evaluate a published RateSchedule at a moment, returning the effective bps. Inputs: scheduleHash + now (unix seconds) + optional jobValueCents (piecewise-value) + optional jobsPerDay (adoption-indexed). Returns {scheduleHash, bps, segmentKind, segmentIndex}. segmentIndex=-1 + bps=0 when no segment covers the moment (silent gap).

  Parameters:

  • scheduleHash (required) — string — 0x + 64 hex schedule hash
  • now (required) — integer — Unix seconds at evaluation moment
  • jobsPerDay — number — Rolling 24h job count (adoption-indexed segments)
  • jobValueCents — integer — Job value in cents (piecewise-value segments)

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_training_manifest_set

  Set (insert-or-replace) the TrainingManifest for a model IP — the dataset weight map the LicensingEngine walks when distributing payouts to a 'model-author' entry in a CompositionManifest. Dataset weightBps must sum to ≤ 10000 (gateway accepts partial mixes; on-chain enforces exact 10000). Returns {modelIpId, manifestHash}.

  Parameters:

  • modelIpId (required) — string — Story IP Asset ID for the model
  • datasetWeights (required) — array — DatasetIP entries with weightBps (sum ≤ 10000)
  • baseModelIpId — string — Optional parent ModelNFT IP if this was fine-tuned
  • methodologyHash — string — Optional 0x + 64 hex reproducibility hash

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_training_manifest_get read-only

  Fetch the TrainingManifest for a model IP. Returns the parsed datasets array + manifestHash + createdAt, or 404 if no manifest has been set.

  Parameters:

  • modelIpId (required) — string — Story IP Asset ID for the model

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• pcc_trilobio_build_config

  Generate a complete KERNEL_CONFIG JSON for a Trilobio (tcode-api) fleet controller. Wraps `buildTrilobioConfig()` from the @pcc/trilobio npm package. Returns a TrilobioKernelConfig with sensible defaults (pollIntervalMs=3000, maxScriptTimeoutSec=3600, allowArbitraryScripts=false). The result can be passed to `pcc-node start` via the KERNEL_CONFIG env var, or handed to setup_generate_config / setup_register_device for direct API-driven registration. Note: this is a TypeScript package helper (no HTTP call). For programmatic use, `import { buildTrilobioConfig } from "@pcc/trilobio"`.

  Parameters:

  • url (required) — string — Fleet-controller URL on the LAN (host[:port], no trailing slash, no path) — e.g. http://192.168.1.50
  • apiKey — string — Trilobio fleet-controller API key (from the trilobot admin UI). Either apiKey OR username+password is required unless mockMode=true.
  • deviceId — string — Logical device ID within the kernel (default: trilobio-fleet-01)
  • kernelId — string — Kernel ID this device belongs to (auto-generated as kernel_trilobio_<timestamp> if omitted)
  • mockMode — boolean — Bypass real HTTP and simulate runs. Use for CI / floor demos. Default: false.
  • password — string — Fleet-controller account password (basic-auth mode only)
  • username — string — Fleet-controller account username (basic-auth mode only)
  • pollIntervalMs — number — Poll interval in ms for run status (range 500-60000). Default: 3000.
  • tcodeApiVersion — string — Pinned tcode-api version on the fleet controller. Format: 'latest' or semver (e.g. 1.25.1). Default: latest. Surfaces in evidence bundles for reproducibility.
  • mockRunDurationMs — number — Mock-mode simulated run duration in ms. Default: 2000.
  • maxScriptTimeoutSec — number — Maximum allowed wall-clock seconds for a single tcode script (range 30-86400). Default: 3600.
  • allowArbitraryScripts — boolean — Permit customer-supplied tcode-api Python scripts (true) or only curated protocol IDs (false). Default: false. Set true only for trusted-counterparty deployments.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_trilobio_validate_options

  Sanity-check operator-supplied Trilobio options before generating a KERNEL_CONFIG. Wraps `validateTrilobioOptions()` from @pcc/trilobio. Catches the common mistakes (malformed URL, missing creds, out-of-range timeouts, invalid tcodeApiVersion semver) before they hit the gateway or the device. Returns { valid: boolean, errors: string[], warnings?: string[] }. Note: this is a TypeScript package helper (no HTTP call); for programmatic use, `import { validateTrilobioOptions } from "@pcc/trilobio"`.

  Parameters:

  • url — string — Fleet-controller URL
  • apiKey — string — Fleet-controller API key
  • deviceId — string
  • kernelId — string
  • mockMode — boolean
  • password — string — Basic-auth password
  • username — string — Basic-auth username
  • pollIntervalMs — number
  • tcodeApiVersion — string — 'latest' or semver string
  • mockRunDurationMs — number
  • maxScriptTimeoutSec — number
  • allowArbitraryScripts — boolean

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_trilobio_validate_script

  Quick lint of a tcode-api Python script before submission to a Trilobio fleet controller. Wraps `validateTcodeScript()` from @pcc/trilobio. Surface check only — NOT a sandbox or sanitizer. Looks for: imports of `tcode_api` (presence required), obviously dangerous statements (subprocess, os.system, eval, exec, __import__, socket, urllib, requests, file writes), empty scripts, and missing top-level tcode commands. Returns { valid: boolean, errors: string[], warnings?: string[] }. Operators with `allowArbitraryScripts=true` should treat results as a hint — the fleet controller is the source of truth on safety. Note: TypeScript package helper (no HTTP call); for programmatic use, `import { validateTcodeScript } from "@pcc/trilobio"`.

  Parameters:

  • source (required) — string — Full Python source of the tcode-api script to lint

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_trilobio_capability_template read-only

  Return the `TRILOBIO_CAPABILITY` constant from @pcc/trilobio — a default capability template for a Trilobio fleet controller. Pass to POST /api/capabilities to publish a baseline liquid-handling capability for a kernel hosting a trilobot. Operators can extend the `materials` and `capabilities` arrays to advertise instrument-specific features (custom labware libraries, sample types). Notable: includes `tcode-script-execution` as an advertised capability, which is unique to Trilobio — operators who set `allowArbitraryScripts: true` can accept jobs that ship a full tcode-api Python script as the protocol payload. Note: TypeScript package helper (no HTTP call); for programmatic use, `import { TRILOBIO_CAPABILITY } from "@pcc/trilobio"`.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• attach_operator_channel

  Attach a notification/dispatch channel to an operator so PCC knows how to ping them when a job lands. The operator's onboarding agent calls this AFTER the conversation that produced the channel record. Transport is a small stable enum (webhook|email|sms|voice|push|mqtt|file|manual) — vendor specifics live in the free-form `describe` field, written by the operator's agent. PCC the substrate stays neutral. Returns the channel record with a generated id.

  Parameters:

  • slug (required) — string — Operator slug (typically the operator's address or unique identifier).
  • label (required) — string — Short human label shown to the operator and in admin UIs: 'Front counter printer', 'Owner's phone'.
  • transport (required) — string — Which wire does the message go over. `manual` = no machine endpoint (dashboard-only).
  • describe (required) — string — Plain-English instructions for how PCC should talk to whatever is on the other end. Written by the operator's onboarding agent. Required, ≥4 chars. Example: 'POST JSON with keys order_id, line_items[], deadline_iso. I will POST back {order_id, status} to your reply URL.'
  • enabled — boolean — Whether the channel is live (defaults to true).
  • endpoint — object — Transport-specific routing payload. webhook→{url}, email→{address}, sms/voice→{phoneE164}, push→{token,platform}, mqtt→{brokerUrl,topic}, file→{scheme,path}, manual→{}.
  • direction — string — out=PCC pushes only; in-out=operator's system also replies; in=operator pushes unsolicited.
  • credentialRef — string — Reference to a secret in the credential vault (not the secret itself). PCC resolves it at dispatch time.
  • replyContract — string — Optional operator-authored contract describing how the operator's system will respond to evidence requests, status pings, etc.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• list_operator_channels read-only

  List every channel attached to an operator. Returns the full channel records (id, transport, direction, endpoint, describe, enabled flags). Useful for an operator's onboarding agent to confirm what is wired up, and for status dashboards.

  Parameters:

  • slug (required) — string — Operator slug.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• update_operator_channel

  Update an existing channel — toggle enabled, rewrite the describe contract, change the endpoint payload, etc. Merges into the existing record. The operator slug, id, and createdAt are immutable.

  Parameters:

  • id (required) — string — Channel id (returned from attach_operator_channel).
  • label — string
  • enabled — boolean
  • describe — string
  • endpoint — object
  • direction — string
  • credentialRef — string
  • replyContract — string

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• delete_operator_channel destructive

  Remove a channel from an operator. Future jobs will not dispatch to it. Use update_operator_channel with enabled=false to silence temporarily without losing the recipe in `describe`.

  Parameters:

  • id (required) — string — Channel id.

  Hints: read-only no · destructive yes · idempotent not declared · open-world not declared

• test_operator_channels

  Fire a synthetic job at every enabled channel for an operator so the onboarding agent (and the human watching) can confirm the integration end-to-end before a real job lands. Returns per-channel dispatch results (delivered, ref, warnings).

  Parameters:

  • slug (required) — string — Operator slug.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• suggest_csd_templates read-only

  Bidirectional onboarding: the registry talks back. Describe in plain English what you are trying to set up — 'wood-fired pizza shop in SF', 'Opentrons OT-2 liquid handler', 'same-day SF courier' — and the registry returns N candidate Capability StructureDefinition (CSD) templates ranked by keyword-overlap relevance (name×3, tags×2, description×1; tie-break on usage). Empty query falls back to popularity-ordered top picks. After picking one, pass the chosen type to pcc-author-integration. Score-zero results are dropped.

  Parameters:

  • q — string — Plain-English description of the capability the user is trying to set up. Optional — empty falls back to popularity.
  • kind — string — Filter by CSD kind.
  • limit — integer — Max results (1..20, default 5).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_popular_csd_templates read-only

  Return CSDs sorted by adoption (usage-count descending). Useful for first-time operators who want to see what kind of capabilities others are publishing. Each entry includes the CSD record plus usage attribution: count, recent adopters (deduped, capped at 50), and lastUsedAt.

  Parameters:

  • limit — integer — Max results (1..50, default 10).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• get_operator_status read-only

  Four-slot substrate view for an operator: kernels, capabilities (with sla + availability), notification channels, and the per-kernel A2A agent-card URLs. Returns totals and a `missing` list naming any of the four onboarding slots that are still empty. Use this from an onboarding agent's wrap-up step to confirm 'are all four slots wired before I go live?' status is `ready` | `partial` | `unconfigured`. Public — operator slug is non-secret and the response carries no credentials (channel `credentialRef` values are vault references, not secrets).

  Parameters:

  • slug (required) — string — Operator slug — typically the operator's wallet address used as `operatorAddress` on their kernels.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• propose_composition

  Propose a composition — a sequenced DAG of capability instances to satisfy a multi-step outcome under a budget + assurance tier. Accepts either a flat `steps` list or an outcome chain. Returns a candidate plan ranked by `optimizeFor` (price | speed | quality) with per-step assignments. The composition is persisted for ~30 minutes (proposed status) and can be executed once via execute_composition.

  Parameters:

  • outcomeType (required) — string — High-level outcome label, ≤120 chars. Example: 'desk-robot-prototype'.
  • budgetUSD (required) — number — Total budget the user is willing to spend across all steps.
  • minAssuranceTier (required) — integer — Minimum acceptable assurance tier on every step.
  • steps — array — Ordered list of capability types this composition needs (1..20). Use this OR `outcomeChain`.
  • location — object — Geographic constraint (lat/lng + radius, or country, etc).
  • requester — object — {agentId, did?} — the agent submitting the request.
  • description — string — Free-form natural-language description (≤4000 chars).
  • optimizeFor — string — Ranking objective (default `price`).
  • outcomeChain — array — Alternative to `steps`: chain of named sub-outcomes. The planner expands each into capability types.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_composition read-only

  Retrieve a previously-proposed composition by id. Returns 404 if unknown, 410 if the 30-minute proposal window has expired. Use this to inspect a plan before executing, or to recover a plan id after a restart.

  Parameters:

  • id (required) — string — Composition id (returned from propose_composition).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• execute_composition

  Commit a proposed composition: drives the DAG through the workflow engine, each step records a reputation outcome, the composition's reputation is finalized when the run ends. When `PCC_COMPOSE_EXECUTE_REAL=true` is set on the gateway, steps submit real jobs via JobFacade and the workflow run is durable (@pcc/workflow). When the flag is off, the NOOP runner returns synthetic success — useful in dev/test. Re-executing an already-run composition replays the stored result (idempotent — reputation deltas are applied exactly once).

  Parameters:

  • id (required) — string — Composition id from propose_composition. Must be in `proposed` status and not expired.
  • idempotencyKey — string — Optional caller-supplied key (≤120 chars) to dedupe execute calls.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_report

  Report a bug, friction, or dead-end you hit while using PCC. Call this the moment you get stuck and cannot recover: a 5xx (its response carries a `report_hint` with pre-filled fields), a 4xx you cannot fix from its message, the same step failing twice, or a misleading tool/description. PUBLIC — works before you provision an API key (cold agents are exactly who this is for). Persisted durably and reviewed by the PCC team. Report each distinct failure ONCE; never include an API key, token, or wallet secret. Rate-limited per IP.

  Parameters:

  • summary (required) — string — 1-line description of what you were doing and what went wrong. Example: 'POST /api/build/contract returned 500 with no hint about the missing field.'
  • logs — array — Optional but valuable: your last few steps as SUMMARIES (never full request/response bodies) — the sequence that led to the failure. Secrets are never allowed in a note.
  • type — string — bug = something is broken/wrong; friction = it works but was confusing/harder than it should be; idea = a suggestion or missing capability. Defaults to bug.
  • detail — string — Multi-line context: the full error body, what you tried, what you expected. Optional but recommended.
  • method — string — The HTTP method you used. From `report_hint.send.method`. Example: 'POST'.
  • status — integer — The HTTP status you got. From `report_hint.send.status`. Example: 500.
  • agentId — string — Which model/agent you are. Example: 'claude', 'gpt-4o', 'gemini'. Optional.
  • traceId — string — Your journey ID — returned by provision_api_key and on every response as `x-pcc-trace-id` (also in a 5xx `report_hint.traceId`). Lets PCC replay your full run.
  • endpoint — string — The route you were on when you got stuck. From a 5xx `report_hint.send.endpoint`. Example: '/api/build/contract'.
  • severity — string — How badly this blocked you. Optional.
  • errorCode — string — The machine error code from the response body, if any. From `report_hint.send.errorCode`.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• pcc_report_attempt

  Report one phase of an onboarding attempt, success or failure (attempt reporting contract v1). Send one report when each runbook phase ends, and a final report with phase "session" (with the `phases` roll-up), also when you stop early (outcome abandoned or budget_stop). Generate `sessionId` (UUID v4) once per attempt and increment `seq` with every report; a retried report with the same sessionId and seq is collapsed. Never guess: send null for what you do not know (tokens: source "unknown"). Redact keys, tokens, emails and wallet secrets before sending. Always include `summary`: contract v1 makes it optional, but until the gateway's attempt support lands it is the only field kept, and today's server refuses a report without it. The schema is contract v1: an unknown phase, outcome or harness name is accepted (the server stores it as other or unknown, with the raw value as a label), and budget-stop is a spelling of budget_stop. Never send a transcript; consent.transcript stays false until the operator decides. Unauthenticated.

  Parameters:

  • kind (required) — string
  • sessionId (required) — string — UUID v4, generated once at the start of the attempt
  • seq (required) — integer — Per-session report counter
  • phase (required)
  • outcome (required)
  • env — ['object', 'null']
  • ids — ['object', 'null'] — Only the ids known so far: each at most 200 characters of [A-Za-z0-9:._/-], or null
  • logs — ['array', 'null'] — The phase's step timeline, summaries only
  • pack — ['object', 'null']
  • detail — ['string', 'null']
  • device — ['object', 'null']
  • phases — ['array', 'null'] — Only on phase "session": the roll-up
  • tokens — ['object', 'null'] — Never guess: send null with source "unknown"
  • consent — ['object', 'null']
  • harness — ['object', 'null']
  • summary — ['string', 'null'] — One line, e.g. "register: failed, POST /api/kernels 400"
  • traceId — ['string', 'null'] — x-pcc-trace-id of the last PCC call
  • contract — integer
  • proposal — ['object', 'null'] — One improvement idea
  • durationMs — ['integer', 'null'] — The phase's wall time; on session, the whole attempt

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• save_dashboard

  Save a generated dashboard to the network so the user gets a live, shareable URL: https://capability.network/a/<slug>. Pass a `manifest` — a small declarative DashboardManifest (windows + live-data bindings + actions) conforming to the schema at https://capability.network/ui-kit/v1/manifest.schema.json; the shipped pcc-ui kit renders it identically everywhere (you compose the manifest, the kit renders it — never hand-rolled HTML). WHEN to call this: only when the task needs a surface to watch/approve/compare/reuse (a live job, a value chain, a settlement trail, a recurring order) — never for a one-line answer. RECALL FIRST: call search_dashboards before generating; reload or fork a match instead of duplicating. The manifest MUST NOT contain an API key (a shared artifact travels with its contents — the network rejects one that does). Returns the stored artifact incl. its slug. Defaults visibility to 'unlisted' (link-shareable, not listed).

  Parameters:

  • name (required) — string — Short human name for the dashboard, e.g. 'Watch my pizza + courier'. Used to mint the slug.
  • manifest (required) — object — The DashboardManifest (2-6KB JSON) conforming to https://capability.network/ui-kit/v1/manifest.schema.json. Required top-level keys: `csd` (must be 'pcc://artifacts/dashboard/v1'), `title`, and `sections[]` (each section has `windows[]`). Window kinds: note, metric, capability, list, form, run, approval, receipt, chain, actions. Bindings point at live routes you already use (/api/jobs/:id, /api/escrow/:id, /sse/stream/job/:id). No API key anywhere in the manifest.
  • visibility — string — Who can load it. Default 'unlisted' (anyone with the link; not in listings). 'public' appears in search_dashboards; 'private' is owner-only.
  • composeRefs — array — Optional pinned, re-plannable ComposeRequest objects (value chains). Pin the request, never a compositionId (those expire in 30 min).
  • description — string — One-line description of what the dashboard shows.
  • renderedCid — string — Optional CID of a rendered-HTML export saved via /api/storage.
  • capabilityTypes — array — Capability types this dashboard is about, e.g. ['pizza.order','courier.dispatch']. This is the discovery join — it's how search_dashboards finds this artifact later.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• get_dashboard read-only

  Recall a saved dashboard by its id or slug. Returns the full artifact (manifest + metadata). Use this to reload a dashboard the user asks for again ('open my pizza dashboard') instead of regenerating it — a saved dashboard reloads with zero regeneration. Public for public/unlisted artifacts; owner-only for private ones. Increments the load counter (a popularity signal).

  Parameters:

  • idOrSlug (required) — string — The artifact id (ua_...) or its slug (e.g. 'watch-my-pizza-8k3f', the tail of the /a/<slug> URL).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• search_dashboards read-only

  Discover existing public dashboards before you generate a new one (recall-first — the library accrues; adopt > extend > build for UIs too). Filter by `capabilityType` (e.g. 'pizza.order'), free-text `q` over name/description/types, and `sort` by popularity or recency. Returns { entries, total, offset, limit }. Only public artifacts are listed; unlisted ones load by slug via get_dashboard but never appear here.

  Parameters:

  • q — string — Free-text search over name, description, and capability types.
  • sort — string — Ranking: 'popular' (by use+load+fork counts) or 'recent' (default).
  • limit — integer — Max results (1..100, default 20).
  • offset — integer — Pagination offset (default 0).
  • capabilityType — string — Filter to dashboards tagged with this capability type, e.g. 'pizza.order'.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• fork_dashboard

  Fork an existing dashboard into a new artifact you own, preserving lineage back to the original (the social remix verb). Use this to adapt a popular dashboard rather than build from scratch — e.g. fork a 'watch pizza' dashboard and raise the budget or add a receipt window via update_dashboard. Increments the source's fork counter. You can fork any public/unlisted artifact, or a private one you own.

  Parameters:

  • id (required) — string — The id (ua_...) of the artifact to fork.
  • name — string — Optional name for the fork (defaults to '<original> (fork)').
  • visibility — string — Visibility of the fork (default 'unlisted').

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• update_dashboard

  Modify a dashboard you own (owner-only). Replace the manifest or any metadata field; the version increments. Use this to edit a saved surface meaningfully — 'raise budgetUSD to 40', 'add a receipt window', 'make it public'. A replaced manifest must still conform to the schema and must not contain an API key. Only send the fields you want to change.

  Parameters:

  • id (required) — string — The id (ua_...) of the artifact to update.
  • name — string — New name.
  • manifest — object — Replacement DashboardManifest (must conform to the schema; no API key). Omit to leave the manifest unchanged.
  • visibility — string — New visibility (e.g. flip 'unlisted' -> 'public' to list it).
  • composeRefs — array — Replacement pinned ComposeRequest objects.
  • description — string — New description.
  • renderedCid — string — New rendered-HTML export CID.
  • capabilityTypes — array — Replacement capability-type tags.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• render_pcc_dashboard read-only

  Compose a live PCC dashboard for a physical-capability task — pass a DashboardManifest (windows + live data bindings + actions) and it renders as an interactive MCP App.

  Parameters:

  • csd (required) — The builtin CSD URI this manifest conforms to.
  • title (required) — string
  • sections (required) — array
  • theme
  • api_base — string — Gateway base URL. Default https://capability.network.
  • description — string

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• render_pcc_dashboard_ir read-only

  Compose a live PCC dashboard rendered through the closed, PCC-owned IR (read-only). Pass a DashboardManifest; it renders as an interactive MCP App via the audited closed-IR render path.

  Parameters:

  • csd (required) — The builtin CSD URI this manifest conforms to.
  • title (required) — string
  • sections (required) — array
  • theme
  • api_base — string — Gateway base URL. Default https://capability.network.
  • description — string

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• pcc.op.capability.request_quote read-only

  Price a configured PCC capability (typed operation). Returns the itemized quote for the given capability type + selections. Pure calculation — no funds move and nothing is created. Maps to POST /api/build/price.

  Parameters:

  • type (required) — string — Capability type, e.g. 'fdm'.
  • selections (required) — object — Parameter selections.
  • profileId — string
  • capabilityId — string

  Hints: read-only yes · destructive no · idempotent not declared · open-world no

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.