Execute API

Canonical Distributed Compute Entry Point

POST /api/v0/ops/execute

This endpoint is the single public entry point for distributed execution on Forge Pool.

All probabilistic simulations, graph workloads, search execution, media jobs, tensor workloads, and future primitive families are executed through this interface.

There are no workload-specific public compute routes.

---

Authentication

All public execution requests require a project-scoped API token.

Authorization: Bearer fpak_XXXXXXXXXXXXXXXX

Project API tokens are issued and governed by Web Core.

They represent project-scoped execution authority, not human identity and not node trust.

See Authentication.

---

Public Runtime Flow

Client
  ↓
Web Core
  ↓
Hub
  ↓
Agents
  ↓
Hub Reduction + Verification
  ↓
Web Core Response

Responsibilities are separated intentionally:

• Web Core handles authentication, tenancy, request admission, persistence, and billing context
• Hub handles deterministic planning, sharding, verification, reduction, and replay production
• Agents execute shard-level work
• Web Core returns the public response surface

---

Canonical Request Envelope

Every execution request is submitted as one canonical envelope.

{
  "ctx": {
    "job_id": "string",
    "trace_id": "string",
    "billing": {
      "mode": "billable | test"
    }
  },
  "op": {
    "name": "string",
    "version": 1,
    "profile": "string"
  },
  "seed": {
    "mode": "explicit | derived",
    "value": "string"
  },
  "policy": {
    "target": "cpu | gpu | any",
    "min_agents": 1,
    "max_agents": 999,
    "verify": "none | spotcheck | full"
  },
  "args": {
    "iterations": 1000000
  },
  "artifacts": {
  }
}

This structure is canonical.

Different workload families change op and args, not the contract shape.

---

Envelope Fields

ctx

Execution context and caller-supplied metadata.

Field	Description
job_id	Optional client-supplied identifier
trace_id	Optional cross-system tracing identifier
billing.mode	test or billable

Notes:

• ctx does not define workload semantics
• ctx helps connect execution to caller-side systems
• billing.mode=test allows non-ledger-impact execution where permitted

---

op

Operation identity.

Field	Description
name	Primitive family name, e.g. mc, graph, search
version	Family version
profile	Workload specialization inside that family

Example:

{
  "op": {
    "name": "mc",
    "version": 1,
    "profile": "insurance.loss.v1"
  }
}

op is the computational identity of the request.

---

seed

Root seed control for deterministic execution.

Field	Description
mode	explicit or derived
value	Provided root seed when mode=explicit

Behavior:

• explicit pins the caller-provided root seed
• derived lets the Kernel derive a deterministic root seed from the request contract

Determinism requires seed discipline.

---

policy

Execution policy hints and constraints.

Field	Description
target	Preferred execution target: cpu, gpu, or any
min_agents	Minimum parallel agent target
max_agents	Upper bound for parallel agent usage
verify	Verification policy: none, spotcheck, or full

Policy influences execution planning.

It does not redefine workload semantics.

---

args

Profile-specific workload parameters.

args are defined by the selected primitive family and profile.

Examples include:

• iteration counts
• distribution parameters
• graph node/edge sets
• ranking settings
• media transformation controls
• tensor dimensions and numeric inputs

There is no single global args schema across all workloads.

---

artifacts

Optional artifact and persistence hints.

Typical uses may include:

• persist reduced result
• include metrics or execution manifests
• request artifact-side references where supported

Artifact behavior is workload-aware and deployment-aware.

---

Example Request

{
  "ctx": {
    "job_id": "eta-demo-001",
    "trace_id": "trace-eta-001",
    "billing": {
      "mode": "test"
    }
  },
  "op": {
    "name": "mc",
    "version": 1,
    "profile": "eta.v1"
  },
  "seed": {
    "mode": "explicit",
    "value": "eta-seed-001"
  },
  "policy": {
    "target": "cpu",
    "min_agents": 1,
    "max_agents": 16,
    "verify": "spotcheck"
  },
  "args": {
    "iterations": 1000000,
    "base_eta": 3600,
    "traffic_mean": 120,
    "traffic_std": 60,
    "weather_prob": 0.2,
    "weather_mean": 300,
    "weather_std": 120,
    "incident_prob": 0.05,
    "incident_mean": 600,
    "incident_std": 200
  }
}

---

Response Structure

A successful execution returns a normalized public result surface.

{
  "ok": true,
  "job_id": "01KXXXX",
  "status": "COMPLETED",
  "billing": {
    "mode": "test",
    "credits": 0,
    "eur": 0
  },
  "hub": {
    "status": "ok",
    "metrics": {
      "wall_ms": 39639,
      "agents_used": 1,
      "shards": 1
    },
    "executions": [
      {
        "agent_id": "ed25519:...",
        "shard_id": 0,
        "iterations": 1000000,
        "wall_ms": 39000,
        "seed": "....",
        "result_hash": "..."
      }
    ],
    "output": {},
    "replay": {
      "root_seed": "..."
    }
  }
}

---

Response Fields

Top-Level

Field	Description
ok	Success flag
job_id	System job identifier
status	Terminal or current execution state
billing	Public billing summary for the call
hub	Runtime result envelope returned from Kernel execution

hub.metrics

Runtime metrics may include:

• wall time
• agents used
• shard count
• reduction timing
• workload-specific metrics where applicable

hub.executions

Per-shard or per-execution metadata may include:

• public agent identity
• shard identity
• work amount
• wall time
• seed reference
• result hash

hub.output

The reduced workload-specific output surface.

This is where profile semantics become visible to the caller.

hub.replay

Replay metadata sufficient to support deterministic rerun or later audit workflows.

---

Determinism Guarantee

Forge Pool enforces deterministic execution by contract.

If the following are identical:

• op.name
• op.version
• op.profile
• canonical args
• seed
• reduction rules

then final result output must be identical under the same runtime doctrine.

The following must not change final output:

• routing path
• agent ordering
• geographic placement
• host identity

---

Billing Discipline

Billing is intentionally separated from execution truth.

• Hub is money-blind
• Hub returns execution metrics
• Web Core computes ledger effects and customer-visible billing
• providers are credited through runtime/accounting flows outside the public request contract
• billing.mode=test produces no ledger impact

This separation keeps the runtime defensible.

---

Error Model

Errors return a normalized failure surface.

{
  "ok": false,
  "status": "FAILED",
  "error": {
    "code": "invalid_request",
    "message": "..."
  }
}

Common error codes include:

• invalid_request
• unauthorized
• quota_exceeded
• hub_unavailable
• execution_failed

Additional deployment-specific error codes may exist, but they should remain reducible to a stable public model.

---

What This Endpoint Is Not

This endpoint is not:

• a generic RPC tunnel
• a route-per-model gateway
• an adapter-specific API surface
• a direct agent-control interface

It is the canonical public execution surface of the Planetary Kernel.

---

Related

• Kernel Overview
• Execution Model
• Determinism
• Replay
• Primitive Families