> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thewo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create your first Operational Evidence report with The Wo.

# 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](/operational-evidence/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:

```bash theme={null}
export THE_WO_API_BASE_URL="https://api.thewo.io"
export THE_WO_API_KEY="<your-api-key>"
```

The public production integration origin is:

```text theme={null}
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:

```http theme={null}
POST /v1/evidence/reports
```

```bash theme={null}
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:

```json theme={null}
{
  "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.

```bash theme={null}
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:

```text theme={null}
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](/operational-evidence/guides/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.

```bash theme={null}
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:

```text theme={null}
context
evidence
```

`evidence` must contain at least one of:

```text theme={null}
evidence.text
evidence.images
```

These are valid:

```text theme={null}
text only          ✅
image only         ✅
text + image       ✅
```

These are invalid:

```text theme={null}
empty evidence     ❌
blank text         ❌
relative image URL ❌
ftp image URL      ❌
unknown context    ❌
```

## Usage

One successfully created report consumes:

```text theme={null}
operation: evidence_report
units: 1
```

Monthly quota is checked before report generation.

See [Usage and quotas](/operational-evidence/guides/usage-and-quotas) for the complete behavior.

## Errors

All API errors use a consistent public envelope:

```json theme={null}
{
  "error": {
    "code": "example_error",
    "message": "A safe public error message.",
    "requestId": "req_123"
  }
}
```

Keep `requestId` when investigating a failed request.

See [Errors](/operational-evidence/guides/errors) for the public error catalog.

## Next steps

* Review [Authentication](/platform/authentication).
* Read the full [Report contract](/operational-evidence/guides/report-contract).
* Understand [Usage and quotas](/operational-evidence/guides/usage-and-quotas).
* Review the [TypeScript example](/operational-evidence/examples/typescript).
* Use the API Reference for the exact machine-readable contract.