HumanTask API Quickstart

Quickstart

The goal of Quickstart is to get from zero to a single test task with the fewest concepts possible. Its contract should make real-world uncertainty explicit while remaining familiar to engineers building software and agent workflows.

Choose an integration path

Choose an integration path 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.

Create the first task

Create the first task 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.

{
  "capability": "on_site_photos",
  "location": {"address": "TARGET_ADDRESS"},
  "instructions": "Capture the requested exterior views.",
  "deadline": "ISO_8601",
  "evidence_required": {"photos_min": 6, "timestamp": true}
}

Read task state

Read task state 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.

{
  "capability": "on_site_photos",
  "location": {"address": "TARGET_ADDRESS"},
  "instructions": "Capture the requested exterior views.",
  "deadline": "ISO_8601",
  "evidence_required": {"photos_min": 6, "timestamp": true}
}

Fetch evidence

A production treatment of Fetch evidence 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.

Handle an exception

A production treatment of Handle an exception 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.

Move from test to production

For Move from test to production, 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.

A Minimal End-to-End Test

The quickest useful test is one task with one address and one proof requirement. Create it, record the task ID, watch each state transition and inspect the exact evidence object returned. This reveals more integration issues than building a broad client library before any real execution has happened.

Use Client References

Attach your own reference to the first task so you can reconcile HumanTask API objects with internal records. The reference should remain stable across retries and logs. This becomes important as soon as more than one agent or backend job can create work.

Test the Failure Path Too

After a successful test, run a controlled scenario that can produce an exception. Your application should know what to do if a location is unavailable, the target cannot be found or a required photo is missing. Quickstarts that show only success leave the hardest integration work for production.

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

Do not automate task volume before you have inspected the evidence from several real completions.

Next Step

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

Implementation Notes for Quickstart

Choose an integration path

When implementing choose an integration path for Quickstart, 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 the first task

When implementing create the first task for Quickstart, 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 task state

When implementing read task state for Quickstart, 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.

Fetch evidence

When implementing fetch evidence for Quickstart, 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.

Handle an exception

When implementing handle an exception for Quickstart, 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.

Move from test to production

When implementing move from test to production for Quickstart, 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 Quickstart 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.