Tasks API

Tasks API

The goal of Tasks API is to treat each real-world action as a stateful object with explicit inputs, acceptance criteria and lifecycle transitions. Its contract should make real-world uncertainty explicit while remaining familiar to engineers building software and agent workflows.

Task object

Task object should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Creation fields

Creation fields is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

{
  "id": "task_123",
  "status": "accepted",
  "capability": "store_stock_check",
  "location": {"address": "TARGET_ADDRESS"},
  "deadline": "ISO_8601"
}

Lifecycle states

For Lifecycle states, prefer a small number of well-defined fields over free-form conventions. The physical worker may read natural-language instructions, but software should get structured values for anything that affects control flow.

{
  "id": "task_123",
  "status": "accepted",
  "capability": "store_stock_check",
  "location": {"address": "TARGET_ADDRESS"},
  "deadline": "ISO_8601"
}

Revision flow

For Revision flow, prefer a small number of well-defined fields over free-form conventions. The physical worker may read natural-language instructions, but software should get structured values for anything that affects control flow.

Cancellation semantics

Cancellation semantics is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

Exceptions from the physical world

Exceptions from the physical world should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Idempotency

Idempotency should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

State Transitions

Define which transitions are legal. A completed task should not jump back to accepted without a revision object; a cancelled task should not later release payment accidentally. A simple state machine prevents contradictory behavior across web, REST and MCP clients.

Task Templates

Repeat workflows can use templates that predefine evidence, allowed capabilities or instruction structure while still creating a new task resource for every execution. Templates improve consistency without hiding the final request from the worker.

Physical Exceptions as Data

A task blocked by a closed store is not equivalent to a task blocked by denied access. Separate states or structured reasons let the caller decide whether to retry later, change location or accept the observation as the useful result.

Error Model

Physical errors are domain events. A closed venue, denied access, missing item and unsafe condition should not collapse into one generic failure. The client may retry some cases, accept others as evidence and escalate the rest.

Production Readiness

Before production, test duplicate creation, cancellation, a blocked task, incomplete evidence, credential rotation and at least one repeated webhook.

Common Integration Mistake

Avoid one generic failed state; a closed location, unavailable item and denied access require different next actions.

Next Step

Implement one tasks api flow against the canonical task lifecycle, inspect the real payloads and only then generalize the client for more capabilities or locations.

Implementation Notes for Tasks API

Task object

When implementing task object for Tasks API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Creation fields

When implementing creation fields for Tasks API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Lifecycle states

When implementing lifecycle states for Tasks API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Revision flow

When implementing revision flow for Tasks API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Cancellation semantics

When implementing cancellation semantics for Tasks API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Exceptions from the physical world

When implementing exceptions from the physical world for Tasks API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Idempotency

When implementing idempotency for Tasks API, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Test Matrix

A Tasks API integration should be tested against more than the happy path. Include a valid request, invalid input, duplicate retry, no matching supply, worker exception, incomplete evidence and cancellation where the interface supports it. The result of each test should be observable in the canonical task object so developers can reconcile UI, API and agent behavior.