Report contract

Operational Evidence converts submitted evidence into a normalized operational report.

Endpoint

POST /v1/evidence/reports

The endpoint is synchronous in the current MVP. A successful request returns:

201 Created

with a completed report.

Request headers

Header	Required	Description
`content-type`	Yes	Must be `application/json`.
`x-api-key`	Yes	Secret API credential used to authenticate the integration.
`Idempotency-Key`	No	Client-generated key used to make create retries safely idempotent.

See Authentication for API key handling rules.

Idempotent retries

Evidence Report creation supports the optional Idempotency-Key request header.

Idempotency-Key: report-request-123

Use a unique client-generated key for each logical report-creation request. Retrying the same normalized request with the same key returns the original successful Evidence Report result without creating another report, retrieving remote images again, invoking the report provider again, or consuming another usage unit. Do not reuse one key for different requests.

same key + same request
→ original result

same key + different request
→ 409 idempotency_conflict

same key while original request is processing
→ 409 idempotency_in_progress

Keys must contain between 1 and 255 characters after trimming. Requests without Idempotency-Key remain supported but do not receive the safe-retry guarantee.

Rate limiting

Evidence Report creation is protected by technical rate limiting. Rate limiting is separate from monthly quota:

rate limiting protects API capacity and abusive request patterns;
quota controls commercial operation consumption during the current quota period.

When the technical request limit is exceeded, the API returns:

429 rate_limit_exceeded

A rate-limit response includes a Retry-After header indicating how many seconds the client should wait before retrying. Safe retry metadata may also be included in error.details, including:

limit;
remaining;
resetAt;
retryAfterSeconds.

Clients should follow Retry-After instead of immediately retrying the request. Concrete rate-limit values are endpoint/runtime configuration and should not be inferred from monthly quota.

Request body

The request body contains:

Field	Type	Required	Description
`context`	string	Yes	Operational context used to interpret the evidence.
`language`	string	No	Nonblank language guidance for the generated report.
`evidence`	object	Yes	Evidence submitted for analysis.
`evidence.text`	string	Conditional	Nonblank textual evidence.
`evidence.images`	array	Conditional	Image evidence references.
`evidence.images[].url`	string	Yes per image	Absolute HTTP or HTTPS image URL.

evidence must contain either:

nonblank text;
at least one image;
or both.

An empty evidence object is invalid.

Strict request contract

The public HTTP request is strict. Unknown request properties are rejected rather than silently ignored. Image entries are also strict objects containing:

{
  "url": "https://example.com/evidence.jpg"
}

The current public contract does not accept an image URL as a bare array string. Image URLs must:

be absolute;
use http or https;
be nonblank.

Remote image retrieval

Image URL validation at the HTTP boundary is only the first step. When image evidence is present, The Wo retrieves each remote image through the shared secure remote-resource boundary before the report provider is invoked. The remote-resource boundary applies target validation, controlled redirect handling, a bounded timeout, maximum-content-size enforcement, and content-type validation. The current Operational Evidence image policy accepts:

image/jpeg
image/png
image/gif
image/webp

The provider receives the validated image content rather than the original customer-controlled URL. The original URL remains part of the submitted Evidence Report input, but it is not delegated to the provider for an independent network fetch. The relevant execution order is:

authentication
→ technical rate limit
→ idempotency decision
→ monthly quota
→ secure remote image retrieval
→ report provider
→ persistence
→ Usage

Quota is therefore checked before The Wo performs remote image retrieval. An idempotent replay returns the original completed report without retrieving the remote image again. A remote image that cannot be safely accepted returns:

422 remote_evidence_image_rejected

A remote image that cannot currently be retrieved safely returns:

503 remote_evidence_image_unavailable

These public failures do not expose private DNS results, blocked addresses, redirect targets, socket details, or raw network errors.

Language

language is optional. When provided, it must be a nonblank string. The current MVP does not expose a fixed public language whitelist. Integrations should use recognizable language tags such as:

en
en-US
pt-BR
es

When language is omitted, the report generation flow can use the language of the submitted evidence.

Successful response

A successful create operation returns the following public fields.

Field	Type	Description
`id`	string	Evidence Report identifier.
`status`	string	Current public create response status.
`result`	object	Generated operational result.
`result.title`	string	Concise report title.
`result.description`	string	Structured description of the observed evidence.
`result.category`	string	Controlled operational category.
`result.priority`	string	Suggested operational priority.
`result.suggestedNextStep`	string or null	Suggested follow-up action when available.
`result.tags`	string[]	Operational search or classification tags.
`result.riskFlags`	string[]	Detected uncertainty or risk indicators.
`result.confidence`	number	Confidence value from 0 through 1.
`usage`	object	Usage associated with the completed operation.
`usage.operation`	string	Billing/usage operation identifier.
`usage.units`	number	Units consumed by this operation.

For the current synchronous create endpoint:

status = completed
usage.operation = evidence_report
usage.units = 1

The public response intentionally does not expose:

customer identifiers;
API key identifiers;
provider credentials;
provider request identifiers;
raw provider responses;
model configuration;
prompt contents;
persistence metadata;
provider cost.

Supported contexts

The current public contexts are:

Value	Intended operational use
`property_maintenance`	Property and facility maintenance evidence.
`delivery_confirmation`	Delivery-related operational evidence.
`field_inspection`	Evidence collected during field inspections.
`damage_report`	Evidence describing observed damage.
`inventory_check`	Evidence collected during inventory verification.

Unsupported contexts are rejected by the public request validator. Because context is validated at the HTTP contract boundary, an unsupported context results in a 400 invalid_request_payload response. New contexts are product decisions and must be introduced intentionally.

Supported priorities

Generated reports use one of the following priority values:

low
medium
high
urgent

Priority is generated from the submitted evidence. Clients do not submit priority as part of the create request. The value is a suggested operational urgency and should be interpreted together with the report description, risk flags, and confidence.

Supported categories

The current controlled category vocabulary is:

plumbing
electrical
cleaning
security
elevator
structural
appliance
other

The initial category vocabulary originated with property maintenance and is currently the controlled category set accepted by the Operational Evidence domain. Categories may evolve into context-specific vocabularies as additional operational contexts mature. Clients should therefore consume the category as a documented API value and avoid building assumptions that prevent future documented values from being introduced.

Unsupported category behavior

category is not part of the create request. It is generated by the report generation flow. If generated output contains a category that cannot be represented by the current domain contract, the generated report is rejected instead of exposing an unsupported value. The current HTTP behavior for invalid generated output is:

502 invalid_generated_report

Provider independence

The endpoint contract is owned by The Wo. A customer integrates with:

The Wo public contract

not with the concrete AI provider behind the operation. Provider-specific models, prompt structures, SDK responses, credentials, and errors are not part of the public API contract.

Overview

Getting started

Product guides

Examples

Report contract

Report contract

Endpoint

Request headers

Idempotent retries

Rate limiting

Request body

Strict request contract

Remote image retrieval

Language

Successful response

Supported contexts

Supported priorities

Supported categories

Unsupported category behavior

Provider independence

​Report contract

​Endpoint

​Request headers

​Idempotent retries

​Rate limiting

​Request body

​Strict request contract

​Remote image retrieval

​Language

​Successful response

​Supported contexts

​Supported priorities

​Supported categories

​Unsupported category behavior

​Provider independence

​Related guides

Report contract

Endpoint

Request headers

Idempotent retries

Rate limiting

Request body

Strict request contract

Remote image retrieval

Language

Successful response

Supported contexts

Supported priorities

Supported categories

Unsupported category behavior

Provider independence

Related guides