{"uid":"cap_v6Q86Jl5GiT4Knj0Uyt6w","slug":"scheduler-withzero-xyz-create-recurring-cron-task-scheduler-withzero-5f46a7ac","name":"Create Recurring Cron Task (scheduler.withzero.xyz)","description":"Create a recurring or on-demand task. Direct endpoint: max_amount_usdc_micros is refundable escrow and X-Pay-Amount-Micros must match it. ZeroClick endpoint: it is a seller-local lifetime execution cap; marketplace access/usage is authoritative and no seller escrow is created. Optional: schedule, max_sibling_calls, llm, tool_list, dependencies, env, notify_email, end_at. See GET /api/v1 and /llms.txt for rail-specific setup.","url":"https://scheduler.withzero.xyz/api/v1/tasks?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["runtime","source","entrypoint","max_runtime_sec","max_sibling_calls"],"properties":{"env":{"type":"object","description":"BYO env vars injected into the sandbox. Never returned in any GET response.","propertyNames":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]*$"},"additionalProperties":{"type":"string","maxLength":4096}},"llm":{"type":"object","required":["profile"],"properties":{"model":{"type":"string","pattern":"^[a-z][a-z0-9-]*(\\/[A-Za-z0-9._:-]+)?$","description":"Optional preferred model selector used when sandbox code omits a model."},"models":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9-]*(\\/[A-Za-z0-9._:-]+)?$"},"maxItems":16,"minItems":1,"description":"Optional allowlist of internal LLM aliases or provider/model ids this task may use. Defaults from the profile."},"profile":{"enum":["quick","standard","bulk","research","long"],"type":"string","default":"standard","description":"LLM workload envelope. Use 'quick', 'standard', 'bulk', 'research', or 'long'."},"max_calls_per_run":{"type":"integer","maximum":100,"description":"Optional lower hard cap on LLM broker calls per run.","exclusiveMinimum":0},"max_input_bytes_per_call":{"type":"integer","maximum":1048576,"description":"Optional lower hard cap on UTF-8 prompt+system bytes per LLM call.","exclusiveMinimum":0},"max_output_tokens_per_call":{"type":"integer","maximum":128000,"description":"Optional lower hard cap on generated tokens requested from the broker.","exclusiveMinimum":0},"max_cost_usdc_micros_per_run":{"type":"string","pattern":"^[1-9]\\d*$","description":"Optional lower per-run LLM spend ceiling in USDC micros (string or number). Added to the task claim ceiling."}},"description":"Enables the built-in LLM for your source (call generate_text(...) — pre-imported, auto-authenticated). Omit to disable LLM calls. Pick a profile (quick|standard|bulk|research|long); GET /api/v1/rates → llm_profiles lists each profile's models, default_model, and caps. FUNDING: the chosen profile's max_cost_usdc_micros_per_run is reserved into estimated_ceiling_micros every run (quick $0.05, standard $0.15, bulk $0.15, research $1.00, long $2.00), so raise max_amount_usdc_micros to match — or lower the reserve with max_cost_usdc_micros_per_run.","additionalProperties":false},"end_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Optional ISO-8601 auto-stop time. The dispatch loop flips status to `completed` once now() >= end_at."},"source":{"type":"string","minLength":1,"description":"Verbatim code for the run, written to /workspace/<entrypoint>. It can reach the public internet, and four helpers are available as GLOBALS — no import, no keys, no setup: generate_text(...) for the built-in LLM (needs an `llm` profile on the task), call(sibling, path, body?, method?, max_price_micros?) to invoke another Zero capability through the per-run proxy, store_artifact(name, data, content_type?) for durable cdn hosting (needs `artifacts.enabled`), and request_continuation(delay_sec?) to schedule an immediate follow-up run when the work is larger than one run cap (chunk → persist progress externally → request_continuation() → exit 0; granted only on a clean exit, capped back-to-back). Call them directly — e.g. python `r = generate_text('hi')`, node `const r = await call('cdn','/x')`. (The explicit `from withzero_sdk import generate_text, call, store_artifact` / `import { generateText, call, storeArtifact } from './withzero-sdk.js'` also works but is optional.) `generate_text` accepts optional OpenRouter reasoning config. CALL() CONTRACT: every helper returns `{ status, body }` where `status` is the upstream HTTP status (int) and `body` is the parsed JSON response (or null). In node these are ASYNC — `await call(...)` / `await generate_text(...)`; in python they are SYNCHRONOUS — `r = call(...)` (no await). call() TARGETS, two kinds: (a) a FIRST-PARTY sibling by NAME (urlshortener/cdn/forms/screenshot/inbox) — billed a flat per-call fee, no max_price_micros needed. (b) ANY PAID marketplace capability by its capabilityId. PAID MARKETPLACE FLOW (discover-then-cap): the sandbox has public internet egress, so to call a paid third-party capability you FIRST discover its `capabilityId`, price, accepted payment protocol (x402 or MPP), and request path/body by querying Zero yourself at https://api.zero.xyz (capability search/get; the capability's OWN OpenAPI describes its request path + body). THEN call it as `call(capabilityId, path, body?, method?, max_price_micros)` — pass the capabilityId as the FIRST arg and max_price_micros (the most USDC micros you accept for this one call). The scheduler resolves the capabilityId server-side, pays via x402 (from a Base float) or MPP (from Tempo escrow) out of the escrow wallet, enforces your cap before signing, and refunds the difference — you never handle keys or sign anything. EXAMPLE (paid, python): `r = call(\"cap_abc123\", \"/v1/enrich\", {\"domain\": \"acme.com\"}, max_price_micros=50000)` — pays at most 0.05 USDC for one call to capability cap_abc123. ERROR CODES a call() may surface in the proxy response: PRICE_CAP_EXCEEDED (the paid challenge exceeded your max_price_micros — payment aborted before signing, nothing spent), PRICE_UNKNOWN (missing/invalid max_price_micros or capabilityId for a paid target), CAPABILITY_PROTOCOL_UNSUPPORTED (the capability offers neither x402 nor MPP), SIBLING_NOT_ALLOWED (target not in the task `tool_list`), CALL_CAP_EXCEEDED (per-run max_sibling_calls hit), SIBLING_PAYMENT_FAILED (resolution/settlement failed; reservation released). ALLOWLIST: a target (sibling name or capabilityId) is callable only when it is in the task `tool_list`, OR when `tool_list` is left open with `max_sibling_calls` > 0 (then `max_sibling_spend_micros` is REQUIRED and bounds total per-run paid spend). The full catalog + worked examples are at GET /api/v1 (the `sandbox` section)."},"runtime":{"enum":["python","node"],"type":"string","description":"Sandbox runtime; 'python' or 'node'."},"schedule":{"anyOf":[{"type":"object","required":["cron","timezone"],"properties":{"cron":{"type":"string","minLength":1,"description":"Raw 5-field cron expression (e.g. '0 7 * * *')."},"timezone":{"type":"string","default":"UTC","description":"IANA timezone (default UTC)."}},"additionalProperties":false},{"type":"object","required":["every","timezone"],"properties":{"at":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"HH:MM 24h time; required for 'daily' and 'weekly'."},"every":{"enum":["minute","hourly","daily","weekly"],"type":"string"},"timezone":{"type":"string","default":"UTC","description":"IANA timezone (default UTC)."},"dayOfWeek":{"enum":["mon","tue","wed","thu","fri","sat","sun"],"type":"string","description":"Three-letter day of week; required for 'weekly'."}},"additionalProperties":false}],"description":"Either a raw cron expression or a convenience shape; the convenience shape compiles to a 5-field cron string server-side."},"artifacts":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Opt in to durable artifact storage. Off by default."},"max_uploads_per_run":{"type":"integer","maximum":20,"description":"Optional lower hard cap on artifact uploads per run; max 20. Default 5.","exclusiveMinimum":0},"max_bytes_per_upload":{"type":"integer","maximum":10485760,"description":"Optional lower hard cap on decoded bytes per artifact; max 10485760. Default 1048576.","exclusiveMinimum":0}},"description":"Optional durable artifact storage for sandbox code via the cdn capability. Omit to disable. Free in v1; bounded by per-run caps.","additionalProperties":false},"tool_list":{"type":"array","items":{"type":"string","maxLength":256,"minLength":1},"maxItems":64,"description":"Allowlist of capability identifiers the run may proxy through — first-party sibling names (urlshortener/cdn/forms/screenshot/inbox) AND/OR marketplace capabilityIds. THREE states: OMIT the field → OPEN proxy when `max_sibling_calls` > 0 (reach ANY capability; `max_sibling_spend_micros` is then REQUIRED to bound spend) — with `max_sibling_calls` 0/omitted it is stored as DENY-ALL instead; send `[]` → DENY-ALL (every capability is blocked; the safe restriction default); send `[items]` → SCOPED to exactly those identifiers. An explicit `[]` is NOT open — only an omitted tool_list with `max_sibling_calls` > 0 is. Marketplace capabilityIds (and their pricing/protocol) are discovered via Zero's capability search at https://api.zero.xyz; first-party sibling names + their per-call openapi are listed at GET /api/v1/_siblings."},"entrypoint":{"type":"string","minLength":1,"description":"File name for `source` (e.g. 'main.py' or 'index.js')."},"billing_rail":{"enum":["direct","zeroclick","account"],"type":"string","description":"Which payment rail this create is billed against. Optional for direct/zeroclick callers. REQUIRED to be \"account\" when authenticating with an API key (zsk_… bearer) — it is the explicit opt-in that lets max_amount_usdc_micros be omitted."},"dependencies":{"type":"object","properties":{"node":{"type":"array","items":{"type":"string","pattern":"^(@[a-z0-9-]+\\/)?[a-z0-9-]+(@[\\w.-]+)?$"},"maxItems":20},"python":{"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9._-]+(==[\\w.-]+)?$"},"maxItems":20}},"description":"Optional extra packages installed in the sandbox prelude; max 20 per runtime. **Always pin versions** — sandboxes install fresh on every run, so an unpinned package silently upgrades when a new major ships. Node: \"name@version\" or \"@scope/name@version\" (e.g. [\"mppx@0.7.0\", \"viem@2.21.0\"]). Python: \"name==version\" (e.g. [\"requests==2.31.0\"]).","additionalProperties":false},"notify_email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Optional address for best-effort run-completion emails. When set, each scheduled (cron) or async `/trigger` run sends one email on finalize with its status, duration, cost, and the tail of stdout. Synchronous runs (`/runs`, `/webhook`) do not email — the result is returned inline. Delivery never blocks or fails a run."},"max_runtime_sec":{"type":"integer","maximum":900,"description":"Hard cap on per-run wall-clock seconds; max 900.","exclusiveMinimum":0},"max_sibling_calls":{"type":"integer","default":0,"maximum":1000,"minimum":0,"description":"Hard cap on sibling proxy calls per run; max 1000. Defaults to 0 — no sibling calls; set it > 0 to let `source` use call(...)."},"max_amount_usdc_micros":{"type":"string","pattern":"^[1-9]\\d*$","description":"Channel deposit ceiling in USDC micros (positive integer as string, or number up to 2^53-1). Bounds total lifetime spend. Size it >= estimated_ceiling_micros * (runs you want before a top-up); if it is below one ceiling the task pauses before its first run. LLM-enabled tasks reserve the profile cost cap per run — see the `llm` field. REQUIRED unless billing_rail is \"account\" — account-rail tasks draw from the account credit balance instead; omit for an uncapped task, or set it as an additional per-task lifetime execution cap."},"max_sibling_spend_micros":{"type":"string","pattern":"^[1-9]\\d*$","description":"Optional per-run sibling-spend ceiling in USDC micros (positive integer as string, or number up to 2^53-1). REQUIRED when `tool_list` is omitted AND `max_sibling_calls` > 0 (open proxy) so spend stays bounded; optional otherwise. Replaces the legacy max_sibling_calls × per-call-fee reservation in the run ceiling."}},"additionalProperties":false},"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["id","status","next_run_at","billing_rail","channel_id","channel_open_tx","max_amount_micros","balance_available_micros","estimated_ceiling_micros","cron","timezone"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"cron":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"timezone":{"type":"string"},"channel_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"billing_rail":{"enum":["direct","zeroclick","account"],"type":"string"},"channel_open_tx":{"anyOf":[{"type":"string"},{"type":"null"}]},"max_amount_micros":{"anyOf":[{"type":"string"},{"type":"null"}]},"balance_available_micros":{"anyOf":[{"type":"string"},{"type":"null"}]},"estimated_ceiling_micros":{"type":"string"}},"additionalProperties":false},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":2,"rating":{"score":"0.92","successRate":"0.99","reviews":2,"stars":"4.7","state":"rated"},"availabilityStatus":"healthy","priceObserved":{"p10Cents":"50.0000","medianCents":"350.0000","p90Cents":"900.0000","minCents":"50.0000","maxCents":"900.0000","p95Cents":"900.0000","sampleCount":6,"varies":true,"failureChargeRate":0},"sessionDeposit":null,"pricing":{"kind":"dynamic","summary":"$0.5–$9/call (observed)","primary":null,"accepted":[]},"paymentMethods":[],"brandName":"scheduler.withzero.xyz","brandSlug":"scheduler-withzero-xyz-mpp","brandBaseUrl":"https://scheduler.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Creates a scheduled recurring cron task that runs agent code in a sandboxed environment, billed in real USDC micros per execution.","exampleAgentPrompt":"Schedule a recurring cron task that runs every day at 8am UTC, using the Python 3.11 runtime, with my entrypoint function 'main' in 'handler.py', a max runtime of 120 seconds, up to 5 sibling calls, a USDC budget of 500000 micros, using the 'standard' LLM profile, and send run notifications to alerts@mycompany.com.","exampleUseCases":null,"resultDescription":"Returns a task object with the new task UUID, its status, the next scheduled run timestamp, the payment channel ID and on-chain open transaction, the maximum USDC micros allocated, the available balance, the estimated per-run ceiling, the parsed cron expression, and the resolved timezone.","failureModes":["Missing required fields (schedule, runtime, source, entrypoint, max_amount_usdc_micros) → 400 validation error","X-Pay-Amount-Micros header does not match max_amount_usdc_micros → payment mismatch error","Missing or duplicate Idempotency-Key header → 422 or replay of existing task","Insufficient USDC balance to open payment channel → payment failure","Invalid cron schedule expression → 400 parse error","Runtime or entrypoint not found in source → 400 error","LLM profile enum value invalid → 400 schema validation error"],"whenToPreferThis":"Use this endpoint when you need to create a brand-new recurring cron-scheduled agent task with a real USDC payment channel backing it. Prefer this over one-off execution endpoints when the workload must repeat automatically on a schedule. Prefer over update endpoints when no task UUID exists yet. This is the canonical task-creation entry point for the scheduler.withzero.xyz platform.","instructions":"# Create Task — first node of the task lifecycle\n\n## Workflow\nThis creates ONE node. The rest of the lifecycle is sibling capabilities:\n- Run now: POST /api/v1/tasks/{id}/runs (sync, returns stdout) or /trigger (async)\n- Watch a run: GET /api/v1/runs/{id} — status: succeeded / failed / timeout\n- Keep alive: POST /api/v1/tasks/{id}/fund — task auto-pauses when balance < one run's ceiling\n- Check state: GET /api/v1/tasks/{id} → status, balance_available_micros, estimated_ceiling_micros\n- Stop + refund: DELETE /api/v1/tasks/{id} — the ONLY way to reclaim the unused deposit (on-chain)\n\n## Contract\n- 1 USDC = 1,000,000 micros. Header X-Pay-Amount-Micros must equal body max_amount_usdc_micros.\n- Reused Idempotency-Key + changed body → IDEMPOTENCY_CONFLICT.\n- Omit `schedule` → on-demand task (never auto-runs). `llm.profile` reserves per-run cost into the ceiling — size the deposit up to match.\n\n## Composition\n- Sandboxes are stateless across runs — BYO storage (S3, etc.) for cross-run state.\n- Call other services from your code as siblings via `tool_list`.","reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":9811,"lastUsedAt":"2026-10-09T13:55:18.913Z","lastSuccessfullyRanAt":"2026-10-09T13:55:18.913Z","lastHealthCheckAt":"2026-10-12T21:07:03.089Z","isFirstParty":true,"canonicalSlug":"scheduler-withzero-xyz-create-recurring-cron-task-scheduler-withzero-5f46a7ac"}