{ "openapi": "3.1.0", "info": { "title": "TrueViewly Location Risk API", "version": "1.0.0", "summary": "Async location-risk intelligence API for coordinates, reports, batches, usage, and webhooks.", "description": "TrueViewly API v1 creates modular location-risk reports across hydrology, severe weather, wildfire, earthquake, landslide, and environmental exposure. Report generation is asynchronous for production reliability." }, "servers": [ { "url": "https://portal.trueviewly.com", "description": "Current environment" } ], "tags": [ { "name": "Report Jobs", "description": "Create and monitor asynchronous location-risk report jobs." }, { "name": "Reports", "description": "Retrieve generated report JSON and PDF artifacts." }, { "name": "Batch API", "description": "Create and monitor coordinate batches." }, { "name": "Usage", "description": "Inspect current quota and usage history." }, { "name": "Observability", "description": "Inspect recent API operations and integration health." }, { "name": "Webhooks", "description": "Manage webhook endpoints and delivery logs." } ], "components": { "securitySchemes": { "apiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "TrueViewly API key", "description": "Send the API key as \u0060Authorization: Bearer tvly_live_...\u0060. \u0060X-API-Key\u0060 is also accepted." } }, "schemas": { "ApiErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } } } }, "ApiReportJob": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string" }, "statusUrl": { "type": "string" }, "result": { "type": "object" }, "pollAfterSeconds": { "type": "integer" } } }, "ApiReportJobList": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/ApiReportJob" } }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" } } }, "ApiLocationRiskReport": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "detail": { "type": "string" }, "reportId": { "type": "string" }, "summary": { "type": "object" }, "report": { "type": "object" } } }, "ApiBatchJob": { "type": "object", "properties": { "batchId": { "type": "string" }, "status": { "type": "string" }, "totalItems": { "type": "integer" }, "progressPercent": { "type": "integer" }, "itemsUrl": { "type": "string" }, "csvUrl": { "type": "string" } } }, "ApiBatchItems": { "type": "object", "properties": { "batchId": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiBatchItem" } } } }, "ApiBatchItem": { "type": "object", "properties": { "rowNumber": { "type": "integer" }, "externalId": { "type": "string" }, "status": { "type": "string" }, "reportJobId": { "type": "string" }, "reportId": { "type": "string" }, "score": { "type": "integer" }, "riskLevel": { "type": "string" }, "error": { "type": "object" } } }, "ApiUsageCurrent": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "generatedUtc": { "type": "string" }, "quotas": { "type": "array" }, "apiReportJobs": { "type": "object" } } }, "ApiUsageHistory": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "fromUtc": { "type": "string" }, "toUtc": { "type": "string" }, "items": { "type": "array" } } }, "ApiOperationsSummary": { "type": "object", "properties": { "windowStartUtc": { "type": "string" }, "windowEndUtc": { "type": "string" }, "requests": { "type": "object" }, "reportJobs": { "type": "object" }, "batches": { "type": "object" }, "webhooks": { "type": "object" }, "recentFailures": { "type": "array" } } }, "ApiWebhookEndpointList": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/ApiWebhookEndpoint" } } } }, "ApiWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array" }, "isActive": { "type": "boolean" } } }, "CreatedApiWebhookEndpoint": { "type": "object", "properties": { "endpoint": { "type": "object" }, "signingSecret": { "type": "string" } } }, "ApiWebhookDeliveryList": { "type": "object", "properties": { "deliveries": { "type": "array" } } } } }, "security": [ { "ApiKeyBearer": [] } ], "paths": { "/api/v1/location-risk/report-jobs": { "post": { "tags": [ "Report Jobs" ], "summary": "Create report job", "description": "Create an async location-risk report job.\n\nRequired scope: \u0060reports:create\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "latitude": 36.98154, "longitude": -122.02934 } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportJob" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "get": { "tags": [ "Report Jobs" ], "summary": "List report jobs", "description": "List recent report jobs owned by the API key account.\n\nRequired scope: \u0060reports:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportJobList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/report-jobs/{jobId}": { "get": { "tags": [ "Report Jobs" ], "summary": "Get report job", "description": "Retrieve job status and report links.\n\nRequired scope: \u0060reports:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": null, "schema": { "type": "string" } } ], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportJob" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/report-jobs/{jobId}/retry": { "post": { "tags": [ "Report Jobs" ], "summary": "Retry report job", "description": "Retry a failed transient report job.\n\nRequired scope: \u0060reports:create\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": null, "schema": { "type": "string" } } ], "requestBody": null, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportJob" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/reports/{reportId}": { "get": { "tags": [ "Reports" ], "summary": "Get report", "description": "Retrieve report JSON. Use \u0060detail=summary\u0060 for integration-friendly output.\n\nRequired scope: \u0060reports:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": null, "schema": { "type": "string", "format": "uuid" } }, { "name": "detail", "in": "query", "required": false, "description": "\u0060summary\u0060 or \u0060full\u0060.", "schema": { "type": "string" } } ], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiLocationRiskReport" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/reports/{reportId}/pdf": { "get": { "tags": [ "Reports" ], "summary": "Download report PDF", "description": "Download the branded PDF report.\n\nRequired scope: \u0060reports:pdf\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": null, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": null, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/batches": { "post": { "tags": [ "Batch API" ], "summary": "Create batch", "description": "Create an async coordinate batch. Each valid item becomes a normal report job.\n\nRequired scope: \u0060bulk:create\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "West Coast sample", "items": [ { "externalId": "site-001", "latitude": 36.98154, "longitude": -122.02934 }, { "externalId": "site-002", "latitude": 33.248205, "longitude": -116.670794 } ] } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiBatchJob" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/batches/{batchId}": { "get": { "tags": [ "Batch API" ], "summary": "Get batch", "description": "Retrieve batch status and progress.\n\nRequired scope: \u0060bulk:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "description": null, "schema": { "type": "string" } } ], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiBatchJob" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/batches/{batchId}/items": { "get": { "tags": [ "Batch API" ], "summary": "List batch items", "description": "List per-coordinate results and child report job links.\n\nRequired scope: \u0060bulk:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "description": null, "schema": { "type": "string" } } ], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiBatchItems" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/location-risk/batches/{batchId}/results.csv": { "get": { "tags": [ "Batch API" ], "summary": "Download batch CSV", "description": "Download batch results as CSV.\n\nRequired scope: \u0060bulk:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "description": null, "schema": { "type": "string" } } ], "requestBody": null, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/usage/current": { "get": { "tags": [ "Usage" ], "summary": "Current usage", "description": "Inspect current-cycle quotas and API job counts.\n\nRequired scope: \u0060usage:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUsageCurrent" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/usage/history": { "get": { "tags": [ "Usage" ], "summary": "Usage history", "description": "Inspect daily usage events for api, manual, or bulk buckets.\n\nRequired scope: \u0060usage:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "bucket", "in": "query", "required": false, "description": "\u0060api\u0060, \u0060manual\u0060, or \u0060bulk\u0060.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": null, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUsageHistory" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/observability/current": { "get": { "tags": [ "Observability" ], "summary": "Operations summary", "description": "Inspect recent API request, report job, batch, and webhook health for the authenticated account.\n\nRequired scope: \u0060usage:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "hours", "in": "query", "required": false, "description": "Window size from 1 to 168 hours.", "schema": { "type": "integer", "format": "int32" } } ], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiOperationsSummary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List webhook endpoints.\n\nRequired scope: \u0060webhooks:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiWebhookEndpointList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Create a webhook endpoint and receive a one-time signing secret.\n\nRequired scope: \u0060webhooks:write\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "Production webhook", "url": "https://example.com/trueviewly/webhooks", "events": [ "report.job.completed", "report.job.failed" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiWebhookEndpoint" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/webhooks/{endpointId}": { "delete": { "tags": [ "Webhooks" ], "summary": "Disable webhook", "description": "Disable a webhook endpoint.\n\nRequired scope: \u0060webhooks:write\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": null, "schema": { "type": "string" } } ], "requestBody": null, "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v1/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "description": "List recent webhook delivery attempts.\n\nRequired scope: \u0060webhooks:read\u0060.", "security": [ { "ApiKeyBearer": [] } ], "parameters": [ { "name": "endpointId", "in": "query", "required": false, "description": null, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": null, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": null, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiWebhookDeliveryList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } } } }