POST /api/zeq/agent/spawn

Spawn a new agent run. The runtime auto-ticks once on spawn so you see immediate progress; subsequent ticks fire from the per-machine ticker or via POST /:id/tick.

Auth

Authorization: Bearer zeq_ak_…. Account-scoped — the spawn lives on the caller's chain. Roles admin+ can spawn on chains they're members of (via the entangled state admin's RBAC).

Cost

75 ZEQ atomic. If the wallet has less than 75, the endpoint returns HTTP 402 INSUFFICIENT_BALANCE and no agent is created.

Request

curl -X POST https://YOUR-FRAMEWORK/api/zeq/agent/spawn \
  -H "Authorization: Bearer zeq_ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "problem": "optimal radiation shielding for 180-day Mars transit",
    "population": 4,
    "generations": 3,
    "precision": 0.001,
    "credential_id": "5b7a9c12-..."
  }'

Body

Field	Type	Required	Notes
problem	string	yes	Plain-language problem statement (max 500 chars).
population	int (1–10)	yes	Genotypes per generation.
generations	int (1–10)	yes	Max generations before the run gives up.
precision	float (0.0001–0.1)	yes	ZeqProof fitness gate. Lower = stricter. 0.001 = ≤0.1% (the framework's default tolerance).
credential_id	uuid	no	BYOK credential to use for per-tick LLM enrichment. Omit → deterministic-only mode.
parent_master_id	uuid	no	Spawn under an existing master agent (mesh mode).

Response · 200 OK

{
  "ok": true,
  "agent_id":   "5b7a9c12-3f1d-4b88-9e3c-1a2b3c4d5e6f",
  "agent_zid":  "ZID-9ad838d5",
  "tally_charge": {
    "charged":         75,
    "burned":          60,
    "toFoundation":    15,
    "remainingAfter":  925
  },
  "first_tick": {
    "generation": 0,
    "best_fitness": 0.0421,
    "operators":   ["KO42", "GR34"],
    "result":      { /* ZeqState */ }
  }
}

Errors

Status	Code	Cause
400	invalid_problem	Empty or > 500 chars.
400	invalid_population	Out of 1–10 range.
400	invalid_precision	Out of 0.0001–0.1 range.
401	—	No bearer / cookie auth.
402	INSUFFICIENT_BALANCE	Wallet < 75 ZEQ. Top up at /tally/.
403	not_chain_member	Caller isn't admin+ on the spawn target chain.
409	quota_exceeded	Account already has too many running agents.

What happens

1. Atomic 75 ZEQ charge.
2. New agent row in agent_lineage. agent_zid minted.
3. First-tick population (4 genotypes by default) generated.
4. Each genotype picks ≤4 operators, kernel computes, ZeqProof scores.
5. Result + best-fitness genotype committed to chain (5 ZEQ for that tick).
6. Total spawn charge surfaced as tally_charge.charged (75 + 5 = 80 if first tick fires synchronously, else 75 alone).
7. Subsequent ticks fire automatically per the agent's cadence (one per Zeqond by default) until generations reached, kill called, or precision gate cleared.

Related

• POST /:id/tick — manual tick
• POST /:id/kill — stop a run
• GET /:id — read state
• Agents concept