HumanTask API OpenAPI

OpenAPI

The goal of OpenAPI is to describe the REST surface in a machine-readable contract for client generation, validation and agent tooling. Its contract should make real-world uncertainty explicit while remaining familiar to engineers building software and agent workflows.

Why publish an OpenAPI contract

For Why publish an OpenAPI contract, 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.

Schema organization

Schema organization 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.

paths:
  /v1/tasks:
    post:
      operationId: createTask
      requestBody:
        required: true
      responses:
        "201":
          description: Task created

Reusable components

A production treatment of Reusable components 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.

paths:
  /v1/tasks:
    post:
      operationId: createTask
      requestBody:
        required: true
      responses:
        "201":
          description: Task created

Examples that remain truthful

Examples that remain truthful 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.

Client generation

For Client generation, 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.

Keeping docs and production aligned

Keeping docs and production aligned 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.

Schema Reuse

Define reusable components for money, location, evidence items, task status and error objects. Reuse keeps generated clients consistent and makes it easier to change a shared field once without copying slightly different definitions across endpoints.

Operation IDs and Examples

Stable operation IDs help code generators and agent tooling. Examples should use placeholders for addresses, credentials and media, but the shape must match production. A beautiful example that cannot validate against the schema is harmful documentation.

Contract Testing

The OpenAPI document should be checked against implementation in CI or another release process. Documentation drift is especially expensive for machine consumers because generated clients will fail mechanically rather than interpret intent.

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 document endpoints or fields that do not exist in production; generated clients amplify inconsistencies quickly.

Next Step

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

Implementation Notes for OpenAPI

Why publish an OpenAPI contract

When implementing why publish an openapi contract for OpenAPI, 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.

Schema organization

When implementing schema organization for OpenAPI, 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.

Reusable components

When implementing reusable components for OpenAPI, 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.

Examples that remain truthful

When implementing examples that remain truthful for OpenAPI, 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.

Client generation

When implementing client generation for OpenAPI, 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.

Keeping docs and production aligned

When implementing keeping docs and production aligned for OpenAPI, 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 OpenAPI 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.