TrueViewly API v1

Quickstart

1. Choose an eligible workspace and create a scoped key in Developer & API keys.
2. Create a report job with coordinates.
3. Poll the job URL until it is completed.
4. Fetch detail=summary for integration-friendly output.
5. Register a webhook or create a batch when your workflow scales.

BASE_URL="https://portal.trueviewly.com"
# Set TRUEVIEWLY_API_KEY securely in your environment; do not commit it.
curl -X POST "$BASE_URL/api/v1/location-risk/report-jobs" \
  -H "Authorization: Bearer $TRUEVIEWLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-001-2026-06-01" \
  -d '{"latitude":36.98154,"longitude":-122.02934}'

A new job returns 202 Accepted with a Location header and statusUrl. Replaying the same idempotency key and payload can return 200 OK. Poll the returned URL, respecting pollAfterSeconds, until completed or failed.

JOB_ID="replace_with_returned_job_id"
curl "$BASE_URL/api/v1/location-risk/report-jobs/$JOB_ID" \
  -H "Authorization: Bearer $TRUEVIEWLY_API_KEY"

# After completion, use the returned result.reportId.
REPORT_ID="replace_with_returned_report_id"
curl "$BASE_URL/api/v1/location-risk/reports/$REPORT_ID?detail=summary" \
  -H "Authorization: Bearer $TRUEVIEWLY_API_KEY"

Authentication

Send the API key as a bearer token. X-API-Key is also accepted for systems that cannot set the Authorization header.

Authorization: Bearer tvly_live_...

Async Jobs

Report generation is asynchronous. Create a job with reports:create, then poll with reports:read. Completed jobs include report and PDF links.

{
  "jobId": "job_xxxxx",
  "status": "completed",
  "result": {
    "reportId": "00000000-0000-0000-0000-000000000000",
    "reportUrl": "/api/v1/location-risk/reports/00000000-0000-0000-0000-000000000000",
    "pdfUrl": "/api/v1/location-risk/reports/00000000-0000-0000-0000-000000000000/pdf"
  }
}

Reports

Use detail=summary for clean decision fields: overall score, risk level, confidence, top risks, module scores, recommendations, review flags, and links. Use detail=full for the complete module payload.

GET /api/v1/location-risk/reports/{reportId}?detail=summary
GET /api/v1/location-risk/reports/{reportId}?detail=full
GET /api/v1/location-risk/reports/{reportId}/pdf

Batch API

Batch API accepts up to 100 coordinate items. Each valid item becomes a normal async report job, so quotas, retries, reports, and webhooks stay consistent.

{
  "name": "West Coast sample",
  "items": [
    { "externalId": "site-001", "latitude": 36.98154, "longitude": -122.02934 },
    { "externalId": "site-002", "latitude": 33.248205, "longitude": -116.670794 }
  ]
}

Webhooks

Webhooks let TrueViewly call your system when a job completes or fails. Verify every event with the signing secret returned when the endpoint is created.

TrueViewly-Timestamp: 1780300800
TrueViewly-Signature: v1=...
TrueViewly-Event: report.job.completed
TrueViewly-Delivery: wd_xxxxx

Compute HMAC-SHA256 over {timestamp}.{rawRequestBody} using the whsec_... signing secret. Reject timestamps older than five minutes to reduce replay risk.

Usage and Quotas

Usage endpoints expose current quota, remaining generations, reset windows, and daily usage history. Existing reports:read keys can read usage, while new keys should use usage:read.

Paid allowances refresh monthly even when billed annually; the workspace response supplies the exact cycle dates. A batch consumes API generation capacity per location. Polling and report reads are rate-limited separately. Current-cycle top-ups expire at the cycle end and do not roll over.

GET /api/v1/usage/current
GET /api/v1/usage/history?bucket=api&days=30

Common errors

Quota exhaustion is 403 quota_exhausted, not rate limiting. Rate limiting is 429 rate_limit_exceeded. Keep the returned request ID when contacting support; never send API keys.

Controller errors use the envelope below. Authentication challenges may use the legacy names Error, Code, Message and RequestId; integrations should accept either casing.

{"error":{"code":"quota_exhausted","message":"API report generation quota is exhausted for the current billing period.","requestId":"example-request-id"}}

Versioning

Current endpoints are under `/api/v1`. Additive fields can appear without a version change. Breaking changes will use a new URL version and a deprecation period for v1.