Workers API

Workers API

The Workers API documentation exists to search human supply by location, capability and operational fit without turning profiles into a generic freelancer directory. Because a single request can dispatch a real person, the interface needs stronger operational semantics than a read-only data API.

Worker object

A production treatment of Worker object 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.

Capability filters

Capability filters 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": "property_verification",
  "near": {"lat": 0.0, "lng": 0.0, "radius_km": 15},
  "available_before": "ISO_8601"
}

Geographic radius

A production treatment of Geographic radius 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.

{
  "capability": "property_verification",
  "near": {"lat": 0.0, "lng": 0.0, "radius_km": 15},
  "available_before": "ISO_8601"
}

Availability

Availability 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.

Verification state

For Verification state, 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.

Matching signals

Matching signals 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.

Privacy boundaries

For Privacy boundaries, 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.

Distance and Service Radius

Worker search should not treat an entire city as one point. Matching can consider distance or travel radius, especially in spread-out metros. The requester may care more about someone who can arrive before a deadline than someone with a slightly stronger generic profile.

Capability Evidence

A worker claiming a capability is useful, but completed history is stronger. Over time the API can expose capability-specific execution signals without turning the response into an invasive personal profile.

Availability Is Time-Bound

Availability should include time context. A worker who is generally active in a city may still be unavailable during the requested visit window. Search endpoints should make that uncertainty explicit.

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

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

Common Integration Mistake

Search results should expose only the information required for matching and execution, not unnecessary personal data.

Next Step

Implement one workers 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 Workers API

Worker object

When implementing worker object for Workers 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.

Capability filters

When implementing capability filters for Workers 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.

Geographic radius

When implementing geographic radius for Workers 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.

Availability

When implementing availability for Workers 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.

Verification state

When implementing verification state for Workers 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.

Matching signals

When implementing matching signals for Workers 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.

Privacy boundaries

When implementing privacy boundaries for Workers 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 Workers 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.