Evidence API

Evidence API

The Evidence API documentation exists to return proof of completion in a structure that software can validate, store and pass downstream. Because a single request can dispatch a real person, the interface needs stronger operational semantics than a read-only data API.

Evidence object

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

Media references

Media references 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.

{
  "task_id": "task_123",
  "status": "submitted",
  "media": [{"type": "photo", "id": "media_1"}],
  "answers": {"item_available": true},
  "captured_at": "ISO_8601"
}

Time and location fields

Time and location 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.

{
  "task_id": "task_123",
  "status": "submitted",
  "media": [{"type": "photo", "id": "media_1"}],
  "answers": {"item_available": true},
  "captured_at": "ISO_8601"
}

Structured answers

Structured answers 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.

Validation status

For Validation status, 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.

Missing evidence

For Missing evidence, 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.

Retention and access

For Retention and access, 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.

Evidence Lineage

Every media item and answer should be tied to a task and, where relevant, a specific requirement. That lineage lets a downstream system know which photo satisfies which requested shot instead of receiving an unlabeled folder.

Validation Versus Truth

The API can validate that required fields are present and metadata is well formed. It should not claim that every submitted observation is objectively true. Verification strength depends on the evidence and the task design.

Access and Retention

Evidence may contain customer locations or operational information. Access controls, signed media URLs and retention policies should be designed before large customers begin sending sensitive tasks.

Error Model

Human execution creates a second failure domain beyond software. Surface that domain with structured reasons so clients can branch intelligently instead of parsing worker notes.

Production Readiness

Do not call the integration production-ready until you can trace one task from client request through worker execution, evidence retrieval, payment state and audit log.

Common Integration Mistake

Evidence should report what was observed, not silently convert an observation into a professional conclusion.

Next Step

Implement one evidence 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 Evidence API

Evidence object

When implementing evidence object for Evidence 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.

Media references

When implementing media references for Evidence 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.

Time and location fields

When implementing time and location fields for Evidence 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.

Structured answers

When implementing structured answers for Evidence 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.

Validation status

When implementing validation status for Evidence 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.

Missing evidence

When implementing missing evidence for Evidence 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.

Retention and access

When implementing retention and access for Evidence 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 Evidence 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.