Skip to main content

Integrate the ClearSKY API with an LLM

Use this page to speed up ClearSKY API integration with LLMs while keeping generated code aligned with the OpenAPI contract and canonical documentation.

  1. State your outcome and constraints (language, runtime, output format, budget controls).
  2. Provide the OpenAPI spec and require strict contract use.
  3. Ask for minimal working code first, then add retries, logging, and tests.
  4. Validate every generated payload and endpoint path against canonical docs before production.

Feed the OpenAPI Spec​

Contract source:

https://api.clearsky.vision/api/specification.json

Copy the full spec directly:

TL;DR LLM Brief (Copy/Paste)​

You are integrating with the ClearSKY Vision HTTP API.

Use only endpoints, fields, enums, and data types from:
https://api.clearsky.vision/api/specification.json

Rules:
- Never invent endpoints, parameters, or casing variants.
- Send x-api-key and Content-Type: application/json on API calls.
- Use exactly one geometry mode per request: Wkt or GeoJson (never both).
- Use Model enum values from GET /api/tasking/models (for example Stratus2), not display labels like Stratus-2.
- For download endpoints, either stream response bytes to .tif or provide UploadUrl.
- Keep estimate and process payload settings aligned.
- Retry 429 and 5xx with exponential backoff and jitter.
- Never print API keys or signed URLs in logs.

Output:
- Return minimal, testable Python code using requests.
- Include clear non-2xx error handling.

Canonical Tasking URLs​

Use these exact tasking URLs when generating cURL snippets or client code:

  • POST https://api.clearsky.vision/api/tasking/orders/estimate
  • POST https://api.clearsky.vision/api/tasking/orders
  • GET https://api.clearsky.vision/api/tasking/orders
  • GET https://api.clearsky.vision/api/tasking/orders/details
  • DELETE https://api.clearsky.vision/api/tasking/orders/cancel
  • GET https://api.clearsky.vision/api/tasking/models

Prompt Templates​

1) Generate a typed client wrapper​

Using the OpenAPI contract, create clearsky_client.py with class ClearSkyClient.

Implement methods for:
- POST https://api.clearsky.vision/api/tasking/orders/estimate
- POST https://api.clearsky.vision/api/tasking/orders
- POST /api/satelliteimages/process/composite/available
- POST /api/satelliteimages/process/composite

Requirements:
- Use requests
- Read CLEARSKY_API_KEY from environment
- Send x-api-key and Content-Type headers
- Type hints and short docstrings tied to OpenAPI request/response shapes
- Raise helpful exceptions for non-2xx responses
- Stream binary responses to disk when downloading files

2) Plan and run a safe end-to-end flow​

Given the OpenAPI contract, implement and run this sequence:
1) Estimate order payload with POST https://api.clearsky.vision/api/tasking/orders/estimate
2) Create order with POST https://api.clearsky.vision/api/tasking/orders (only if estimate is acceptable)
3) Validate date with POST /api/satelliteimages/process/composite/available
4) Download with POST /api/satelliteimages/process/composite and save clearsky_rgb.tif

Constraints:
- Use one geometry mode only (Wkt or GeoJson)
- Keep Model, SatelliteConstellations, EpsgProjection, and Bandnames consistent
- Redact secrets in logs/output
- Return code plus sanitized JSON responses

3) Review generated code for contract compliance​

Audit this code against the ClearSKY OpenAPI spec and list:
- any invalid endpoint paths
- any unknown or misspelled fields
- any mixed geometry mode usage
- any missing retry handling for 429/5xx
- any secret leakage risk

Then provide a corrected version.

Production Guardrails for LLM-Generated Code​

  • Treat OpenAPI as the contract source of truth.
  • Keep request payload casing exactly as specified in the contract.
  • Check availability before estimate/process in download workflows.
  • Handle 400 by fixing payload issues, not blind retries.
  • Handle 429 and 5xx with backoff/jitter and controlled concurrency.
  • Prefer UploadUrl for async pipelines that should avoid large in-memory binaries.
  • Keep API keys and signed URLs out of prompts, logs, and shared output.

Canonical References​

Use these pages to ground and verify generated code: