Schedule an agent task
agent_task.create
Schedules one operation to run later under this agent grant. When dueAt passes on the wall clock, or on productId's sandbox clock for a sandbox task, the engine's maintenance loop runs the operation through the same admission the agent's own call takes: scopes, Product scope, reason, money caps, approvals and the always-human floor all apply. The run states the task's reason, which defaults to the hyperscale-reason this call sends. One attempt per task: the task ends done with the operation id, or refused with the refusal body, such as agent_cap_exceeded with its approval or agent_grant_revoked when the grant ended first. A retry is a new task. Only an agent session or the founder's CLI login schedules a task, since a task runs under a grant. Callers: the founder's CLI login or any agent token.
POST /v1/agent-tasks
Principal user_session. Idempotency required. Environment sandbox.
Input
| Field | In | Type | Description |
|---|---|---|---|
X-Hyperscale-Environment | header | sandbox | live | |
Idempotency-Key required | header | string | |
X-Hyperscale-Rehearsal | header | "true" | `true` runs the request through admission and execution, keeps nothing, and answers OperationRehearsal with 200 in place of the operation's own output. Needs a signed-in caller. Identity operations, such as sign-in, sessions, team members and agent grants, refuse it with invalid_request. |
tenantId required | body | string | Organization tenant ID |
operation required | body | string | The operation to run, such as sandbox.account.fund |
input required | body | object | The operation's input, checked against its schema now |
environment | body | sandbox | live | Where the operation runs; defaults to sandbox |
dueAt required | body | string | The instant the task becomes due |
clock | body | wall | sandbox | wall (default) or sandbox; sandbox waits for productId's sandbox clock to pass dueAt |
productId | body | string | With clock sandbox, the Product whose sandbox clock the task waits for. A wall-clock task ignores it |
reason | body | string | Why the task runs; the run states it as the agent's reason. Defaults to the reason this call states |
taskKey required | body | string | The task's idempotency key for this grant. A second create with the same key and request returns the first task; the same key with another request refuses idempotency_conflict |
Request sample
curl --request POST 'https://hyperscale0.ai/v1/agent-tasks' \
--header "Authorization: Bearer $HYPERSCALE_API_KEY" \
--header 'X-Hyperscale-Environment: sandbox' \
--header "Idempotency-Key: $(uuidgen)" \
--header 'Content-Type: application/json' \
--data-raw '{"tenantId":"ten_sandbox_example0001","operation":"ops_sandbox_example0001","input":{},"dueAt":"2026-01-01T00:00:00.000Z","taskKey":"x"}'Errors
| Code | HTTP | Cause |
|---|---|---|
agent_approval_denied | 403 | A human denied the agent's proposed operation. |
agent_approval_required | 202 | An agent proposed a protected live operation. |
agent_reason_required | 400 | An agent sent a change without saying why, or the reason is shorter than 8 or longer than 280 characters. |
agent_result_already_delivered | 409 | A caller already claimed this approval's one-time result. |
csrf_token_invalid | 403 | A browser session mutation did not carry a current Hyperscale CSRF token. |
environment_mismatch | 403 | The session was issued for sandbox or live and the request targets the other environment. |
idempotency_conflict | 409 | The request reused an Idempotency-Key for a different logical mutation. |
idempotency_required | 400 | The operation is a mutation and Hyperscale requires a replay key before executing it. |
internal_error | 500 | Hyperscale hit an unexpected server-side condition and hid internal implementation details from this audience. |
invalid_request | 400 | The request does not match the API reference. |
missing_required_permission | 403 | The signed-in member's current role does not grant the permission required for this operation. |
missing_required_scope | 403 | The credential is valid but does not grant one or more operation scopes. |
not_found | 404 | No Hyperscale route matched the requested path and method. |
rate_limited | 429 | The credential sent more than its limit in the current 60-second window: 600 requests per API key or session, 1,200 per IP address. Every response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (Unix seconds). |
request_body_too_large | 413 | The JSON request body exceeded Hyperscale's accepted payload size. |
resource_not_found | 404 | The requested resource does not exist in the credential's visible scope. |
state_conflict | 409 | The operation conflicts with the current durable state of the resource. |
state_constraint_failed | 422 | The request is syntactically valid but violates a business-state constraint. |
tenant_mismatch | 403 | The request mixed tenant-owned identifiers across tenant boundaries. |
tenant_not_found | 404 | The credential resolved to a tenant Hyperscale cannot find. |
unauthorized | 403 | The request did not include a valid Hyperscale bearer credential for this environment. |
agent_token_expired | 401 | The agent token is real, but its grant ended. A grant lasts 30 days, or 7 days unused. `details.expiresAt` holds the date in ISO 8601 and `details.agentName` names the agent. |
agent_token_replaced | 401 | The founder ran `hyperscale agent setup` again for this agent, which replaced this token with a newer one. `details.agentName` names the agent and `details.replacedAt` holds the date. |
device_login_expired | 401 | The bearer is the founder's own device login from `hyperscale auth login`, not an agent token. Its access token lasts an hour and the CLI refreshes it; the login itself ends after 30 days, or 7 days unused. `details.expiresAt` holds when it ended in ISO 8601. |
instrument_instance_not_found | 404 | No record of this instrument matches the `instanceId` in this Product, company and environment. `details.instrumentId` and `details.instrumentInstanceId` name what was looked up. |
invalid_credentials | 401 | Hyperscale could not accept the account or credential request. Signup, login, and bearer authentication use one 401 for every case they reject, so the response exposes no credential-specific reason or registered-email verdict. The single exception is a key that is real but homed in the other environment: because the presented secret already matched a stored key, the message names the mismatch instead of leaving a working credential looking unknown. A bearer that matched nothing gets text that fits its prefix (an agent token, a refresh token, a personal access token, a session or no Hyperscale token at all), which says only what the caller sent, never whether a credential like it exists. |
operation_not_finalized | 409 | The operation in `details.operationId` has started but has no final receipt. It is still running, or its outcome is unknown after a failure past the point where it may have committed. `details.error` carries the underlying failure when there is one. |
session_expired | 401 | The session behind this request has ended. A console session ends 30 days after sign-in, or after 12 hours with no request. An admin or customer session ends 24 hours after sign-in, or after 15 minutes with no request. A personal access token ends at the `expiresAt` set when it was created. |
session_required | 401 | This operation needs a person signed in through the browser or the `hyperscale` CLI. A Product API key cannot call it. The request carried no session, or its token matched no live session. |
session_revoked | 401 | The session or personal access token behind this request was ended before its expiry. Sign-out, `user.session.revoke`, a password reset, a role change, removal from the team, user suspension and `personal_access_token.revoke` all end sessions. |
tenant_status_forbidden | 409 | The company is suspended or closed, so every credential bound to it is refused, reads included. `details.tenantId` names the company. |