Reports API reference

Create a report

POST /api/v1/reports

Ask for a report. Answers 202; poll links.self for the result.

reports:write Idempotency-Key honoured

Body

address string required

The property address, as a person would write it. Located for you; the response says where it resolved.

window_start string required

The first day of the period to search, YYYY-MM-DD. Must be in the past.

window_end string required

The last day of the period, on or after window_start.

radius_miles number

How far around the address to search, 1 to 100. The plan may narrow it; window.narrowed_by_plan says so.

reference string

Your own file or claim number, carried on the report unchanged.

recipient string

Who the document is prepared for, printed on the cover.

property_id string

A saved property to file this report under.

layout array

Which sections, imagery and map layers the document is composed with. Requires a plan that can compose layouts; otherwise a 402 names the tier.

Answers

200

Replayed. This Idempotency-Key was honoured before; the earlier answer is returned again, with an Idempotent-Replay: true header.

202

Accepted. The report exists but is not yet generated; poll links.self for the result.

409

This Idempotency-Key was already used for a different request, or its first request is still being processed. A retry must resend the request it is retrying.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

POST /api/v1/reports

curl -X POST https://titanweather.com/api/v1/reports \
  -H "Authorization: Bearer $TITAN_API_TOKEN" \
  -H "Idempotency-Key: claim-48211-first-report" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "1428 Cedar Ridge Dr, Plano, TX 75023",
    "window_start": "2016-08-23",
    "window_end": "2026-08-23",
    "radius_miles": 5
}'

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->post('/api/v1/reports', [
    'headers' => ['Idempotency-Key' => 'claim-48211-first-report'],
    'json' => [
        'address' => '1428 Cedar Ridge Dr, Plano, TX 75023',
        'window_start' => '2016-08-23',
        'window_end' => '2026-08-23',
        'radius_miles' => 5,
    ],
]);

$report = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
    'Idempotency-Key': 'claim-48211-first-report',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    address: '1428 Cedar Ridge Dr, Plano, TX 75023',
    window_start: '2016-08-23',
    window_end: '2026-08-23',
    radius_miles: 5,
  }),
});

const report = await response.json();

import os
import requests

response = requests.post(
    "https://titanweather.com/api/v1/reports",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
        "Idempotency-Key": "claim-48211-first-report",
    },
    json={
        "address": "1428 Cedar Ridge Dr, Plano, TX 75023",
        "window_start": "2016-08-23",
        "window_end": "2026-08-23",
        "radius_miles": 5,
    },
)

report = response.json()

Response 202

{
    "data": {
        "id": "0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
        "object": "report",
        "status": "pending",
        "address": {
            "query": "1428 Cedar Ridge Dr, Plano, TX 75023",
            "street": null,
            "city": null,
            "state": null,
            "postal_code": null,
            "county": null,
            "latitude": null,
            "longitude": null
        },
        "window": {
            "start": "2016-08-23",
            "end": "2026-08-23",
            "radius_miles": 5,
            "narrowed_by_plan": false
        },
        "property_id": null,
        "event_count": 0,
        "observation_count": 0,
        "coverage": {
            "complete": false,
            "provisional": false,
            "summary": null,
            "sources_searched": []
        },
        "headline": null,
        "findings": null,
        "failure_reason": null,
        "plan_tier": "professional",
        "layout": {
            "sections": [
                "summary",
                "findings",
                "map",
                "events"
            ],
            "imagery": [
                "aerial",
                "street_view"
            ],
            "elements": [
                "key_figures"
            ],
            "map": null
        },
        "created_at": "2026-08-23T14:02:11Z",
        "generated_at": null,
        "pdf": {
            "status": null,
            "rendered_at": null
        },
        "links": {
            "self": "https://titanweather.com/api/v1/reports/0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
            "events": null,
            "pdf": null
        }
    }
}

List reports

GET /api/v1/reports

The team's reports, newest first.

reports:read paginated

Query parameters

status enum

Only reports in this state.

address string

Only reports whose address contains this text.

property string

Only reports filed under this saved property.

Answers

200

The answer.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

GET /api/v1/reports

curl https://titanweather.com/api/v1/reports \
  -H "Authorization: Bearer $TITAN_API_TOKEN"

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->get('/api/v1/reports');

$reports = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports', {
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
  },
});

const reports = await response.json();

import os
import requests

response = requests.get(
    "https://titanweather.com/api/v1/reports",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
    },
)

reports = response.json()

Response 200

{
    "data": [
        {
            "id": "0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
            "object": "report",
            "status": "complete",
            "address": {
                "query": "1428 Cedar Ridge Dr, Plano, TX 75023",
                "street": "1428 Cedar Ridge Dr",
                "city": "Plano",
                "state": "TX",
                "postal_code": "75023",
                "county": "Collin",
                "latitude": 33.0412,
                "longitude": -96.6996
            },
            "window": {
                "start": "2016-08-23",
                "end": "2026-08-23",
                "radius_miles": 5,
                "narrowed_by_plan": false
            },
            "property_id": "0198a3f2-6d7e-7b41-92c5-2f6a1c9d4e88",
            "event_count": 14,
            "observation_count": 41,
            "coverage": {
                "complete": true,
                "provisional": false,
                "summary": "All nine sources answered for the full period.",
                "sources_searched": [
                    "noaa_storm_events",
                    "iem_lsr",
                    "spc_reports",
                    "noaa_swdi",
                    "cocorahs"
                ]
            },
            "headline": "Hail to 2.75 in within 1 mile, most recently April 21, 2023.",
            "findings": [
                {
                    "family": "hail",
                    "family_label": "Hail",
                    "event_count": 9,
                    "peak_severity": "severe",
                    "evidence_kinds": [
                        "ground",
                        "radar"
                    ],
                    "evidence_labels": [
                        "Ground report",
                        "Radar detection"
                    ],
                    "dates": [
                        "2023-04-21",
                        "2021-04-28",
                        "2019-06-09"
                    ],
                    "most_recent": "2023-04-21",
                    "peak_hail_in": 2.75,
                    "peak_wind_mph": null,
                    "peak_tornado_ef": null,
                    "nearest_miles": 0.8,
                    "any_observed": true,
                    "confidence": "high",
                    "confidence_label": "High confidence",
                    "statement": "Nine hail events on record, the largest 2.75 in measured 0.8 miles away."
                }
            ],
            "failure_reason": null,
            "plan_tier": "professional",
            "layout": {
                "sections": [
                    "summary",
                    "findings",
                    "map",
                    "events"
                ],
                "imagery": [
                    "aerial",
                    "street_view"
                ],
                "elements": [
                    "key_figures"
                ],
                "map": null
            },
            "created_at": "2026-08-21T16:44:09Z",
            "generated_at": "2026-08-21T16:45:03Z",
            "pdf": {
                "status": "ready",
                "rendered_at": "2026-08-21T16:45:41Z"
            },
            "links": {
                "self": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
                "events": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events",
                "pdf": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf"
            }
        },
        {
            "id": "0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
            "object": "report",
            "status": "pending",
            "address": {
                "query": "1428 Cedar Ridge Dr, Plano, TX 75023",
                "street": null,
                "city": null,
                "state": null,
                "postal_code": null,
                "county": null,
                "latitude": null,
                "longitude": null
            },
            "window": {
                "start": "2016-08-23",
                "end": "2026-08-23",
                "radius_miles": 5,
                "narrowed_by_plan": false
            },
            "property_id": null,
            "event_count": 0,
            "observation_count": 0,
            "coverage": {
                "complete": false,
                "provisional": false,
                "summary": null,
                "sources_searched": []
            },
            "headline": null,
            "findings": null,
            "failure_reason": null,
            "plan_tier": "professional",
            "layout": {
                "sections": [
                    "summary",
                    "findings",
                    "map",
                    "events"
                ],
                "imagery": [
                    "aerial",
                    "street_view"
                ],
                "elements": [
                    "key_figures"
                ],
                "map": null
            },
            "created_at": "2026-08-23T14:02:11Z",
            "generated_at": null,
            "pdf": {
                "status": null,
                "rendered_at": null
            },
            "links": {
                "self": "https://titanweather.com/api/v1/reports/0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
                "events": null,
                "pdf": null
            }
        }
    ],
    "links": {
        "first": "https://titanweather.com/api/v1/reports?page=1",
        "last": "https://titanweather.com/api/v1/reports?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://titanweather.com/api/v1/reports",
        "per_page": 25,
        "to": 2,
        "total": 2
    }
}

Retrieve a report

GET /api/v1/reports/{report}

One report: its findings, coverage and the shape of its document.

reports:read

Path parameters

report

The report id, a uuid from a create or list response.

Answers

200

The answer.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

GET /api/v1/reports/{report}

curl https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60 \
  -H "Authorization: Bearer $TITAN_API_TOKEN"

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->get('/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60');

$report = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60', {
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
  },
});

const report = await response.json();

import os
import requests

response = requests.get(
    "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
    },
)

report = response.json()

Response 200

{
    "data": {
        "id": "0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
        "object": "report",
        "status": "complete",
        "address": {
            "query": "1428 Cedar Ridge Dr, Plano, TX 75023",
            "street": "1428 Cedar Ridge Dr",
            "city": "Plano",
            "state": "TX",
            "postal_code": "75023",
            "county": "Collin",
            "latitude": 33.0412,
            "longitude": -96.6996
        },
        "window": {
            "start": "2016-08-23",
            "end": "2026-08-23",
            "radius_miles": 5,
            "narrowed_by_plan": false
        },
        "property_id": "0198a3f2-6d7e-7b41-92c5-2f6a1c9d4e88",
        "event_count": 14,
        "observation_count": 41,
        "coverage": {
            "complete": true,
            "provisional": false,
            "summary": "All nine sources answered for the full period.",
            "sources_searched": [
                "noaa_storm_events",
                "iem_lsr",
                "spc_reports",
                "noaa_swdi",
                "cocorahs"
            ]
        },
        "headline": "Hail to 2.75 in within 1 mile, most recently April 21, 2023.",
        "findings": [
            {
                "family": "hail",
                "family_label": "Hail",
                "event_count": 9,
                "peak_severity": "severe",
                "evidence_kinds": [
                    "ground",
                    "radar"
                ],
                "evidence_labels": [
                    "Ground report",
                    "Radar detection"
                ],
                "dates": [
                    "2023-04-21",
                    "2021-04-28",
                    "2019-06-09"
                ],
                "most_recent": "2023-04-21",
                "peak_hail_in": 2.75,
                "peak_wind_mph": null,
                "peak_tornado_ef": null,
                "nearest_miles": 0.8,
                "any_observed": true,
                "confidence": "high",
                "confidence_label": "High confidence",
                "statement": "Nine hail events on record, the largest 2.75 in measured 0.8 miles away."
            }
        ],
        "fingerprint": "f3b1c9d84a027e65b2f8a1c40d9e73258c6b0a4f1d92e8735a6c410b9f2d8e07",
        "failure_reason": null,
        "plan_tier": "professional",
        "layout": {
            "sections": [
                "summary",
                "findings",
                "map",
                "events"
            ],
            "imagery": [
                "aerial",
                "street_view"
            ],
            "elements": [
                "key_figures"
            ],
            "map": null
        },
        "created_at": "2026-08-21T16:44:09Z",
        "generated_at": "2026-08-21T16:45:03Z",
        "pdf": {
            "status": "ready",
            "rendered_at": "2026-08-21T16:45:41Z"
        },
        "links": {
            "self": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
            "events": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events",
            "pdf": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf"
        }
    }
}

List the records a report cites

GET /api/v1/reports/{report}/events

The archived records a report cites, with their provenance.

reports:read paginated

Path parameters

report

The report id, a uuid from a create or list response.

Query parameters

type enum

Only records of this type.

family string

Only records in this corroboration family, such as thunderstorm or flash_flood.

from string

Only records on or after this date.

to string

Only records on or before this date.

min_hail_in number

Only records whose hail meets this size, in inches.

min_gust_mph number

Only records whose gust meets this speed, in miles per hour.

observed boolean

Only measured records (true), or only estimates (false).

Answers

200

The answer.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

GET /api/v1/reports/{report}/events

curl https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events?type=hail&min_hail_in=1 \
  -H "Authorization: Bearer $TITAN_API_TOKEN"

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->get('/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events', [
    'query' => [
        'type' => 'hail',
        'min_hail_in' => 1,
    ],
]);

$events = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events?type=hail&min_hail_in=1', {
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
  },
});

const events = await response.json();

import os
import requests

response = requests.get(
    "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
    },
    params={
        "type": "hail",
        "min_hail_in": 1,
    },
)

events = response.json()

Response 200

{
    "data": [
        {
            "id": 188204,
            "object": "weather_event",
            "type": "hail",
            "family": "hail",
            "severity": "severe",
            "occurred_on": "2023-04-21",
            "begins_at": "2023-04-21T20:18:00Z",
            "ends_at": null,
            "measurements": {
                "wind_speed_mph": null,
                "wind_gust_mph": null,
                "hail_size_in": 2.75,
                "tornado_ef_scale": null
            },
            "location": {
                "latitude": 33.041,
                "longitude": -96.699,
                "county": "Collin",
                "state": "TX",
                "precision": "point"
            },
            "relevance": {
                "relevance": "primary",
                "distance_miles": 0.8,
                "bearing": "NE"
            },
            "provenance": {
                "source": "noaa_storm_events",
                "source_label": "NOAA Storm Events Database",
                "evidence_kind": "ground",
                "is_observed": true,
                "qualifier": "measured",
                "methodology": "Reports from trained spotters and local officials, quality controlled by NWS.",
                "citation_url": "https://www.ncei.noaa.gov/stormevents/"
            },
            "description": "Baseball size hail reported by a trained spotter near Cedar Ridge Dr."
        }
    ],
    "links": {
        "first": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events?page=1",
        "last": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events",
        "per_page": 25,
        "to": 1,
        "total": 1
    }
}

Retrieve the verification statement

GET /api/v1/reports/{report}/verification

What the report can be shown to be: its fingerprint, and where to verify it.

reports:read

Path parameters

report

The report id, a uuid from a create or list response.

Answers

200

The answer.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

GET /api/v1/reports/{report}/verification

curl https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/verification \
  -H "Authorization: Bearer $TITAN_API_TOKEN"

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->get('/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/verification');

$verification = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/verification', {
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
  },
});

const verification = await response.json();

import os
import requests

response = requests.get(
    "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/verification",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
    },
)

verification = response.json()

Response 200

{
    "object": "verification",
    "report_id": "0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
    "fingerprint": "f3b1c9d84a027e65b2f8a1c40d9e73258c6b0a4f1d92e8735a6c410b9f2d8e07",
    "short_fingerprint": "F3B1 C9D8 4A02 7E65",
    "verify_url": "https://titanweather.com/verify/F3B1C9D84A027E65",
    "generated_at": "2026-08-21T16:45:03Z",
    "place": "Plano, Collin County, TX",
    "window": {
        "start": "2016-08-23",
        "end": "2026-08-23",
        "radius": 5
    },
    "finding": "Hail to 2.75 in within 1 mile, April 21, 2023.",
    "authoritative": true,
    "records": 14,
    "observations": 41,
    "sources_searched": 9,
    "sources_found": 5,
    "links": {
        "report": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60"
    }
}

Create a download link

POST /api/v1/reports/{report}/pdf/link

The rendered document, as a short-lived signed link; 202 while it is still being rendered.

reports:export

Path parameters

report

The report id, a uuid from a create or list response.

Answers

200

A short-lived signed link to the rendered document.

202

The document is being rendered in the background. The body carries status: preparing and retry_after; poll this endpoint, or pdf.status on the report.

409

The report has not finished generating, so there is no document yet.

503

The rendering engine is unavailable. An outage of ours, not a billing problem; retry later.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

POST /api/v1/reports/{report}/pdf/link

curl -X POST https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf/link \
  -H "Authorization: Bearer $TITAN_API_TOKEN"

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->post('/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf/link');

$download = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf/link', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
  },
});

const download = await response.json();

import os
import requests

response = requests.post(
    "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf/link",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
    },
)

download = response.json()

Response 200

{
    "object": "download",
    "url": "https://titanweather.com/storage/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60.pdf?expires=1787841903&signature=1c9d84a0",
    "signed": true,
    "filename": "titan-weather-plano-tx.pdf",
    "content_type": "application/pdf",
    "bytes": 1284772,
    "expires_at": "2026-08-23T15:05:00Z"
}

Download the PDF

GET /api/v1/reports/{report}/pdf

The rendered document, as bytes; 202 while it is still being rendered.

reports:export

Path parameters

report

The report id, a uuid from a create or list response.

Answers

200

The rendered document, as bytes.

202

The document is being rendered in the background. The body carries status: preparing and retry_after; poll this endpoint, or pdf.status on the report.

409

The report has not finished generating, so there is no document yet.

503

The rendering engine is unavailable. An outage of ours, not a billing problem; retry later.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

GET /api/v1/reports/{report}/pdf

curl https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf \
  -H "Authorization: Bearer $TITAN_API_TOKEN" \
  -o report.pdf

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->get('/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf', [
    'sink' => 'report.pdf',
]);

const response = await fetch('https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf', {
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
  },
});

const bytes = await response.arrayBuffer();

import os
import requests

response = requests.get(
    "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
    },
)

with open("report.pdf", "wb") as file:
    file.write(response.content)

Response 200

The rendered document, as application/pdf bytes. The same file the application produces, byte for byte. The document is rendered in the background once the report and its photographs are in; until then this answers 202 with {"object": "pdf", "status": "preparing", "retry_after": 10} and a Retry-After header. Poll, or read pdf.status on the report.

Create reports in a batch

POST /api/v1/reports/batch

Ask for several reports in one request. One credit each.

reports:write Idempotency-Key honoured

Body

reports array required

The rows, up to the cap in GET /api/v1. Each carries its own address, and may carry window_start, window_end, radius_miles, reference and property_id of its own.

window_start string

A default first day for rows that do not set their own.

window_end string

A default last day for rows that do not set their own.

radius_miles number

A default search radius for rows that do not set their own.

layout array

One document layout applied to every row. Requires a plan that can compose layouts.

Answers

200

Replayed. This Idempotency-Key was honoured before; the earlier answer is returned again, with an Idempotent-Replay: true header.

202

Every row was accepted. Each carries links.self to poll.

207

The rows did not all end the same way. Each row answers for itself.

409

This Idempotency-Key was already used for a different request, or its first request is still being processed. A retry must resend the request it is retrying.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

POST /api/v1/reports/batch

curl -X POST https://titanweather.com/api/v1/reports/batch \
  -H "Authorization: Bearer $TITAN_API_TOKEN" \
  -H "Idempotency-Key: nightly-intake-2026-08-23" \
  -H "Content-Type: application/json" \
  -d '{
    "reports": [
        {
            "address": "1428 Cedar Ridge Dr, Plano, TX 75023",
            "reference": "CLM-48211"
        },
        {
            "address": "742 Bluebonnet Ln, Frisco, TX 75034",
            "reference": "CLM-48214"
        }
    ],
    "window_start": "2016-08-23",
    "window_end": "2026-08-23"
}'

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->post('/api/v1/reports/batch', [
    'headers' => ['Idempotency-Key' => 'nightly-intake-2026-08-23'],
    'json' => [
        'reports' => [
            [
                'address' => '1428 Cedar Ridge Dr, Plano, TX 75023',
                'reference' => 'CLM-48211',
            ],
            [
                'address' => '742 Bluebonnet Ln, Frisco, TX 75034',
                'reference' => 'CLM-48214',
            ],
        ],
        'window_start' => '2016-08-23',
        'window_end' => '2026-08-23',
    ],
]);

$batch = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
    'Idempotency-Key': 'nightly-intake-2026-08-23',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reports: [
      {
        address: '1428 Cedar Ridge Dr, Plano, TX 75023',
        reference: 'CLM-48211',
      },
      {
        address: '742 Bluebonnet Ln, Frisco, TX 75034',
        reference: 'CLM-48214',
      },
    ],
    window_start: '2016-08-23',
    window_end: '2026-08-23',
  }),
});

const batch = await response.json();

import os
import requests

response = requests.post(
    "https://titanweather.com/api/v1/reports/batch",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
        "Idempotency-Key": "nightly-intake-2026-08-23",
    },
    json={
        "reports": [
            {
                "address": "1428 Cedar Ridge Dr, Plano, TX 75023",
                "reference": "CLM-48211",
            },
            {
                "address": "742 Bluebonnet Ln, Frisco, TX 75034",
                "reference": "CLM-48214",
            },
        ],
        "window_start": "2016-08-23",
        "window_end": "2026-08-23",
    },
)

batch = response.json()

Response 202

{
    "object": "report_batch",
    "submitted": 2,
    "accepted": 2,
    "rejected": 0,
    "skipped": 0,
    "credits_spent": 2,
    "credits_remaining": 16,
    "out_of_credits": false,
    "results": [
        {
            "index": 0,
            "address": "1428 Cedar Ridge Dr, Plano, TX 75023",
            "status": "accepted",
            "message": null,
            "report": {
                "id": "0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
                "object": "report",
                "status": "pending",
                "address": {
                    "query": "1428 Cedar Ridge Dr, Plano, TX 75023",
                    "street": null,
                    "city": null,
                    "state": null,
                    "postal_code": null,
                    "county": null,
                    "latitude": null,
                    "longitude": null
                },
                "window": {
                    "start": "2016-08-23",
                    "end": "2026-08-23",
                    "radius_miles": 5,
                    "narrowed_by_plan": false
                },
                "property_id": null,
                "event_count": 0,
                "observation_count": 0,
                "coverage": {
                    "complete": false,
                    "provisional": false,
                    "summary": null,
                    "sources_searched": []
                },
                "headline": null,
                "findings": null,
                "failure_reason": null,
                "plan_tier": "professional",
                "layout": {
                    "sections": [
                        "summary",
                        "findings",
                        "map",
                        "events"
                    ],
                    "imagery": [
                        "aerial",
                        "street_view"
                    ],
                    "elements": [
                        "key_figures"
                    ],
                    "map": null
                },
                "created_at": "2026-08-23T14:02:11Z",
                "generated_at": null,
                "pdf": {
                    "status": null,
                    "rendered_at": null
                },
                "links": {
                    "self": "https://titanweather.com/api/v1/reports/0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
                    "events": null,
                    "pdf": null
                }
            }
        },
        {
            "index": 1,
            "address": "742 Bluebonnet Ln, Frisco, TX 75034",
            "status": "accepted",
            "message": null,
            "report": {
                "id": "0198b6c1-8a02-7cd4-b7e6-0f2d94c1a583",
                "object": "report",
                "status": "pending",
                "address": {
                    "query": "1428 Cedar Ridge Dr, Plano, TX 75023",
                    "street": null,
                    "city": null,
                    "state": null,
                    "postal_code": null,
                    "county": null,
                    "latitude": null,
                    "longitude": null
                },
                "window": {
                    "start": "2016-08-23",
                    "end": "2026-08-23",
                    "radius_miles": 5,
                    "narrowed_by_plan": false
                },
                "property_id": null,
                "event_count": 0,
                "observation_count": 0,
                "coverage": {
                    "complete": false,
                    "provisional": false,
                    "summary": null,
                    "sources_searched": []
                },
                "headline": null,
                "findings": null,
                "failure_reason": null,
                "plan_tier": "professional",
                "layout": {
                    "sections": [
                        "summary",
                        "findings",
                        "map",
                        "events"
                    ],
                    "imagery": [
                        "aerial",
                        "street_view"
                    ],
                    "elements": [
                        "key_figures"
                    ],
                    "map": null
                },
                "created_at": "2026-08-23T14:02:11Z",
                "generated_at": null,
                "pdf": {
                    "status": null,
                    "rendered_at": null
                },
                "links": {
                    "self": "https://titanweather.com/api/v1/reports/0198b6c1-8a02-7cd4-b7e6-0f2d94c1a583",
                    "events": null,
                    "pdf": null
                }
            }
        }
    ]
}

Delete a report

DELETE /api/v1/reports/{report}

Delete a report and its stored document.

reports:write

Path parameters

report

The report id, a uuid from a create or list response.

Answers

204

Deleted. The stored document goes with it.

Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.

DELETE /api/v1/reports/{report}

curl -X DELETE https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60 \
  -H "Authorization: Bearer $TITAN_API_TOKEN"

$titan = new \GuzzleHttp\Client([
    'base_uri' => 'https://titanweather.com',
    'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);

$response = $titan->delete('/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60');

$response = json_decode((string) $response->getBody(), true);

const response = await fetch('https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
  },
});

const response = await response.json();

import os
import requests

response = requests.delete(
    "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
    },
)

response = response.json()

Response 204

No body. The report and its stored document are gone; its credit is not returned.