HumanTask REST API

REST API

REST API is the developer surface for one specific problem: provide deterministic HTTP endpoints for applications that create and manage physical tasks. The design has to combine ordinary software concerns with physical latency, evidence and money movement.

Resource model

Resource model 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.

Create-task endpoint

Create-task endpoint 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.

POST /v1/tasks
Authorization: Bearer $HUMANTASK_API_KEY
Idempotency-Key: client-job-8421
Content-Type: application/json

Read and cancel operations

A production treatment of Read and cancel operations needs both the normal path and the exception path. Human execution is reliable only when the client knows what happens when the environment does not match the request.

POST /v1/tasks
Authorization: Bearer $HUMANTASK_API_KEY
Idempotency-Key: client-job-8421
Content-Type: application/json

Filtering and pagination

Filtering and pagination 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.

Error responses

For Error responses, 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.

Idempotent writes

For Idempotent writes, 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.

Versioning strategy

Versioning strategy 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.

HTTP Semantics Matter

Use predictable methods and status codes: creation should return a new resource, reads should be safe, cancellation should have explicit rules and invalid state transitions should be distinguishable from validation errors. Developers should not need product-specific guesswork to understand basic API behavior.

Pagination and Filtering

Worker, task and event collections will grow. Filtering by status, creation time, capability and client reference should be designed before large volumes appear. Cursor-based pagination is often easier to make stable than offset pagination when records change while a client is reading.

Version the Contract Deliberately

Physical task fields will evolve as the marketplace learns. Backward-incompatible changes should not silently alter existing integrations. New optional evidence fields are easier to introduce than changing the meaning of a field that production agents already use.

Error Model

Model offline exceptions deliberately. The important question is not only whether a request was valid but whether the intended observation or action could occur under real conditions.

Production Readiness

A release checklist should cover authentication, idempotency, spend limits, exception states, evidence permissions and reconciliation between events and canonical objects.

Common Integration Mistake

A retried HTTP request must not create a second paid field task, so idempotency is a core API behavior rather than an optional convenience.

Next Step

Implement one rest 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 REST API

Resource model

When implementing resource model for REST 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.

Create-task endpoint

When implementing create-task endpoint for REST 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.

Read and cancel operations

When implementing read and cancel operations for REST 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.

Filtering and pagination

When implementing filtering and pagination for REST 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.

Error responses

When implementing error responses for REST 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.

Idempotent writes

When implementing idempotent writes for REST 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.

Versioning strategy

When implementing versioning strategy for REST 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 REST 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.