Quickstart

Create your first Operational Evidence report with a single API request. The current API accepts text evidence, image URL evidence, or both.

Before you start

You need:

an approved The Wo API key;
the API base URL for your environment;
a server-side environment where the API key can remain secret.

During the private beta, credentials are provisioned manually. See Beta access for the current onboarding process.

Configure your environment

Store the values outside your source code. Use the canonical The Wo production API origin and keep your API key outside source code:

export THE_WO_API_BASE_URL="https://api.thewo.io"
export THE_WO_API_KEY="<your-api-key>"

The public production integration origin is:

https://api.thewo.io

The staging API hostname is reserved for internal The Wo release validation and must not be used as a normal customer integration target. Never commit the real API key.

Create a report from text

Send a request to:

POST /v1/evidence/reports

curl \
  --request POST \
  --url "$THE_WO_API_BASE_URL/v1/evidence/reports" \
  --header "content-type: application/json" \
  --header "x-api-key: $THE_WO_API_KEY" \
  --data '{
    "context": "property_maintenance",
    "language": "en",
    "evidence": {
      "text": "Water is collecting under the bathroom sink and the cabinet base is wet."
    }
  }'

A successful request returns 201 Created. Example:

{
  "id": "report_01JXYZ123ABC",
  "status": "completed",
  "result": {
    "title": "Water leak below bathroom sink",
    "description": "Water accumulation is visible below the bathroom sink and the cabinet base appears wet.",
    "category": "plumbing",
    "priority": "high",
    "suggestedNextStep": "Inspect the sink plumbing and stop the source of the leak before further water damage occurs.",
    "tags": ["water", "bathroom", "sink"],
    "riskFlags": ["water_damage"],
    "confidence": 0.92
  },
  "usage": {
    "operation": "evidence_report",
    "units": 1
  }
}

Create a report from an image

Image evidence is represented as an object containing an absolute HTTP or HTTPS URL.

curl \
  --request POST \
  --url "$THE_WO_API_BASE_URL/v1/evidence/reports" \
  --header "content-type: application/json" \
  --header "x-api-key: $THE_WO_API_KEY" \
  --data '{
    "context": "field_inspection",
    "language": "en",
    "evidence": {
      "images": [
        {
          "url": "https://example.com/evidence/inspection-panel.jpg"
        }
      ]
    }
  }'

The image URL must reference content that The Wo can retrieve through its secure remote-resource boundary. Remote image retrieval happens before report generation; the original customer-controlled URL is not delegated to the report provider for an independent fetch. The current Operational Evidence image policy accepts these HTTP content types:

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

A remote image can be rejected when it cannot be accepted safely, exceeds the configured resource limits, follows an unsafe redirect, or returns an unsupported content type. A temporarily unavailable remote image returns a separate 503 error. See Errors. Only submit images that your application is authorized to share with The Wo.

Combine text and image evidence

Text and images can be sent together.

curl \
  --request POST \
  --url "$THE_WO_API_BASE_URL/v1/evidence/reports" \
  --header "content-type: application/json" \
  --header "x-api-key: $THE_WO_API_KEY" \
  --data '{
    "context": "damage_report",
    "language": "en",
    "evidence": {
      "text": "A crack appeared beside the entrance door after the impact.",
      "images": [
        {
          "url": "https://example.com/evidence/entrance-damage.jpg"
        }
      ]
    }
  }'

The API analyzes both forms of evidence as part of the same report.

Evidence rules

Every request must contain:

context
evidence

evidence must contain at least one of:

evidence.text
evidence.images

These are valid:

text only          ✅
image only         ✅
text + image       ✅

These are invalid:

empty evidence     ❌
blank text         ❌
relative image URL ❌
ftp image URL      ❌
unknown context    ❌

Usage

One successfully created report consumes:

operation: evidence_report
units: 1

Monthly quota is checked before report generation. See Usage and quotas for the complete behavior.

Errors

All API errors use a consistent public envelope:

{
  "error": {
    "code": "example_error",
    "message": "A safe public error message.",
    "requestId": "req_123"
  }
}

Keep requestId when investigating a failed request. See Errors for the public error catalog.

Next steps

Review Authentication.
Read the full Report contract.
Understand Usage and quotas.
Review the TypeScript example.
Use the API Reference for the exact machine-readable contract.

Overview

Getting started

Product guides

Examples

Quickstart

Quickstart

Before you start

Configure your environment

Create a report from text

Create a report from an image

Combine text and image evidence

Evidence rules

Usage

Errors

Next steps

​Quickstart

​Before you start

​Configure your environment

​Create a report from text

​Create a report from an image

​Combine text and image evidence

​Evidence rules

​Usage

​Errors

​Next steps

Quickstart

Before you start

Configure your environment

Create a report from text

Create a report from an image

Combine text and image evidence

Evidence rules

Usage

Errors

Next steps