Copy‑paste friendly. This page is designed so you can copy sections directly into your favorite LLM. Where possible we include minimal JSON and prompts that speed up the integration of ClearSKY API and data services.

TL;DR — Paste this “LLM Brief” first

Use this as a system prompt or the first message to your LLM. Then paste the OpenAPI spec (next section) or continue with the cheat‑sheets below.

You are integrating with the ClearSKY Vision HTTP API.

Base URL: https://api.clearsky.vision
Auth: Send "Authorization: Bearer $CLEARSKY_API_KEY" with every request and "Content-Type: application/json".

Core endpoints you will need:
1) Search orderable tiles:
   POST /api/tasking/search/tiles
   Body supports exactly one of these flows at a time:
     - { "wkt" | "geoJson" }  -> returns matching tile GUIDs (and EPSG/dataGeogWkt)
     - { "tileGuids" | "miniTileGuids" } -> returns geometries for the GUIDs
     - { "tileGuidForMiniTiles" } -> returns the minitile GUIDs in a tile

2) Tasking / Orders:
   - GET  /api/tasking/orders
   - POST /api/satelliteimages/process/tasking/orders/estimate   (price & dates for a proposed order)
   - POST /api/satelliteimages/process/tasking/orders            (create an order)

   Common fields for estimate/create: Wkt | GeoJson | TileGuids | MiniTileGuids (one mode at a time),
   SatelliteConstellations (e.g. ["Sentinel1","Sentinel2","Landsat89"]), Model (e.g. "Stratus2"),
   StorageMonths, ApiRequests, ImageFrequency (1=daily ... 7=weekly), ReferenceDate (YYYY-MM-DD),
   From (YYYY-MM-01), To (YYYY-MM-DD or null for recurring).

3) Data availability:
   - POST /api/satelliteimages/search/available
   - POST /api/satelliteimages/process/composite/available

4) Downloads (binary GeoTIFF unless "uploadUrl" is provided):
   - POST /api/satelliteimages/process/composite
   - POST /api/satelliteimages/process/composite/estimate
   - POST /api/satelliteimages/process/tile
   - POST /api/satelliteimages/process/minitile

Composite required fields: one of {wkt|geoJson}, date, resolution (10..1280 m), epsgProjection, fileType ("tif"),
pixelSelectionMode ("intersect"|"contained"), dataType ("INT16"|"UINT8"), utmDataSelectionMode,
satelliteConstellations, model, bandnames ("all"|"rgb"|comma bands or indices like [B8_B4]).
If "uploadUrl" is set, server will PUT the file to that URL instead of returning bytes.

Important rules:
- Use either Wkt or GeoJson — not both.
- Prefer UTM EPSG (326xx/327xx) for best quality.
- ImageFrequency aligns by ReferenceDate across multiple orders.
- For downloads, write the response body to a .tif file (or provide uploadUrl).
- Respect rate limits and request-size limits.
- Never include API keys in logs or prompts.

1) Base URL & Headers

{
  "baseUrl": "https://api.clearsky.vision",
  "headers": {
    "Authorization": "Bearer $CLEARSKY_API_KEY",
    "Content-Type": "application/json"
  }
}

2) Give the LLM the OpenAPI spec

To avoid hallucinations, download and paste the spec to your LLM:

curl -o specification.json https://api.clearsky.vision/api/specification.json

or copy the entire specification page here:

After downloading, paste the full specification.json into your LLM so it knows every endpoint, parameter, schema, and example.

3) Minimal Endpoint Cheat‑Sheet (verified)

These are the most common endpoints you’ll use. They’re mirrored in the OpenAPI, but presented here for quick copy‑pasting while you work with an LLM.

Search orderable tiles

POST /api/tasking/search/tiles

Body (choose one flow):

{ "wkt": "POLYGON((9.87 56.47, 10.19 56.47, 10.19 56.28, 9.87 56.28, 9.87 56.47))", "geoJson": null, "tileGuids": null, "miniTileGuids": null, "tileGuidForMiniTiles": null }

{ "wkt": null, "geoJson": null, "tileGuids": ["tile-guid-1"], "miniTileGuids": null, "tileGuidForMiniTiles": null }

{ "wkt": null, "geoJson": null, "tileGuids": null, "miniTileGuids": null, "tileGuidForMiniTiles": "tile-guid-xyz" }

Orders — list, estimate, create

GET  /api/tasking/orders
POST /api/satelliteimages/process/tasking/orders/estimate
POST /api/satelliteimages/process/tasking/orders

Estimate/Create body (example):

{
  "Wkt": "GEOMETRYCOLLECTION (POLYGON ((8.675127 55.962046, 8.675127 55.963407, 8.679411 55.963407, 8.679411 55.962046, 8.675127 55.962046)))",
  "GeoJson": null,
  "TileGuids": null,
  "MiniTileGuids": null,
  "SatelliteConstellations": ["Sentinel1","Sentinel2","Landsat89"],
  "Model": "Stratus2",
  "StorageMonths": 1,
  "ApiRequests": 1,
  "ImageFrequency": 3,
  "ReferenceDate": "2025-01-01",
  "From": "2025-04-01",
  "To": null
}

Data availability

POST /api/satelliteimages/search/available
POST /api/satelliteimages/process/composite/available

Downloads (GeoTIFF bytes unless you provide uploadUrl)

POST /api/satelliteimages/process/composite
POST /api/satelliteimages/process/composite/estimate
POST /api/satelliteimages/process/tile
POST /api/satelliteimages/process/minitile

Composite download (example):

{
  "wkt": "POLYGON((9.8778932067 56.4785666824,10.1964967224 56.4785666824,10.1964967224 56.2778208778,9.8778932067 56.2778208778,9.8778932067 56.4785666824))",
  "geoJson": null,
  "date": "2024-05-03",
  "resolution": 10,
  "epsgProjection": 32632,
  "fileType": "tif",
  "pixelSelectionMode": "contained",
  "dataType": "INT16",
  "utmDataSelectionMode": "combined_utm",
  "utmGridForcePixelResolutionSize": true,
  "satelliteConstellations": ["Sentinel1","Sentinel2","Landsat89"],
  "model": "Stratus2",
  "bandnames": "all",
  "allowPartialImage": false,
  "uploadUrl": null
}

4) Copy‑paste Prompt Templates

A. “Wrap the API” (Python)

You are a senior Python engineer. Here is the OpenAPI spec for ClearSKY API:

<PASTE specification.json here>

Write a Python module `clearsky_client.py` with class `ClearSkyClient` that wraps:
- POST /api/satelliteimages/process/composite  -> method `process_composite(...)`
- POST /api/satelliteimages/process/tasking/orders -> method `create_task_order(...)`
- POST /api/satelliteimages/process/tasking/orders/estimate -> `estimate_task_order(...)`
- GET  /api/tasking/orders -> `list_orders(...)`

Requirements:
- use `requests`, read the API key from env `CLEARSKY_API_KEY`
- type hints + docstrings from the spec
- raise for non-2xx with helpful messages
- return parsed JSON for JSON endpoints and write bytes to a .tif for downloads

B. “Plan + run an end‑to‑end flow”

Given the ClearSKY API spec, do this:
1) Estimate an order for the bounding box [minLon,minLat,maxLon,maxLat] = [9.8778932067,56.2778208778,10.1964967224,56.4785666824],
   Model="Stratus2", Constellations=["Sentinel1","Sentinel2","Landsat89"], ImageFrequency=3, From="2025-04-01", ReferenceDate="2025-01-01".
2) Create the order if the current month cost < EUR 1200.
3) For the first available date in April 2025, download a 10 m composite GeoTIFF in EPSG:32632 with bandnames="rgb".
4) Save to disk as `clearsky_rgb.tif`. If there's an `uploadUrl` option in the API, skip returning bytes and have the server upload to a signed URL I provide.
Return the commands/code you ran and the JSON responses for each step.

C. “Safety guardrails” (good to paste before asking an LLM to write code)

Rules you must follow:
- Do NOT invent endpoints or parameters; use only what’s in the spec.
- Use either Wkt or GeoJson in a request body — never both.
- Prefer EPSG:326xx or 327xx for highest quality.
- For downloads, write response bytes to a .tif file or set an uploadUrl to have the server PUT the file.
- Check availability before large downloads where possible.
- Obey rate limits and request credit caps (split requests if necessary).

5) Quick cURL & Python examples

cURL — estimate → create order

# Estimate
curl -H "Authorization: Bearer $CLEARSKY_API_KEY" -H "Content-Type: application/json"   -X POST https://api.clearsky.vision/api/satelliteimages/process/tasking/orders/estimate   -d '{
    "Wkt":"POLYGON((9.8778932067 56.4785666824,10.1964967224 56.4785666824,10.1964967224 56.2778208778,9.8778932067 56.2778208778,9.8778932067 56.4785666824))",
    "SatelliteConstellations":["Sentinel1","Sentinel2","Landsat89"],
    "Model":"Stratus2",
    "StorageMonths":1,
    "ApiRequests":1,
    "ImageFrequency":3,
    "ReferenceDate":"2025-01-01",
    "From":"2025-04-01",
    "To":null
  }'

# Create (reuse the same body when you're ready)
curl -H "Authorization: Bearer $CLEARSKY_API_KEY" -H "Content-Type: application/json"   -X POST https://api.clearsky.vision/api/satelliteimages/process/tasking/orders   -d @order.json

Python — composite download to a local file

import os, requests

API = "https://api.clearsky.vision"
H = {"Authorization": f"Bearer {os.environ['CLEARSKY_API_KEY']}", "Content-Type": "application/json"}

body = {
  "wkt": "POLYGON((9.8778932067 56.4785666824,10.1964967224 56.4785666824,10.1964967224 56.2778208778,9.8778932067 56.2778208778,9.8778932067 56.4785666824))",
  "date": "2024-05-03",
  "resolution": 10,
  "epsgProjection": 32632,
  "fileType": "tif",
  "pixelSelectionMode": "contained",
  "dataType": "INT16",
  "utmDataSelectionMode": "combined_utm",
  "satelliteConstellations": ["Sentinel1","Sentinel2","Landsat89"],
  "model": "Stratus2",
  "bandnames": "rgb",
  "allowPartialImage": False
}

r = requests.post(f"{API}/api/satelliteimages/process/composite", headers=H, json=body, stream=True)
r.raise_for_status()
with open("clearsky_rgb.tif","wb") as f:
    for chunk in r.iter_content(1<<20):
        if chunk: f.write(chunk)
print("Wrote clearsky_rgb.tif")

6) Pitfalls & guardrails for LLM‑written code

WKT vs GeoJSON: Supply one (never both) in bodies that accept geometry.
UTM EPSG recommended: Prefer UTM (EPSG 326xx / 327xx) for best quality reprojection.
Binary responses: Download endpoints return bytes; stream to a file or set uploadUrl.
Indices for free: You can request indices like NDVI using bandnames="[B8_B4]".
Rate limits: Starter plan allows ~4 requests/sec. Split large jobs.
Per‑request cap: Each download has a processing‑credit cap (e.g., 2000). Split large AOIs.
Recurring orders: Leave To null to keep receiving new images monthly; cancel at least a day before next month.
Field casing: Stick to the spec’s exact field names (e.g., epsgProjection, utmDataSelectionMode).

7) Data specifics (for post‑processing)

Data types: UINT8 or INT16; NODATA = -32768 (for int16).
Scaling: bands ÷ 10000; indices ÷ 32767; precomputed indices are in [-1, 1].
GeoTIFF tags: IMAGE_DATE, MODEL_VERSION, IMAGE_VERSION, CONSTELLATIONS are embedded for provenance.

8) Keep secrets safe

Never paste your API key into a chat. Use environment variables and show redacted logs.
If you must share responses, redact order GUIDs and any signed URLs.

Appendix — Where these come from (for your LLM to verify later)

API docs UI and spec at api.clearsky.vision (OpenAPI served at /api/specification.json).
Tasking/Orders (list/estimate/create), Tiles search, Availability, and Download endpoints are documented in the API Guide.
Data specs (types, scaling, NODATA) are documented in the Data Specification page.


# (Optional) We could embed direct links here, but the guide is copy-paste ready.

1) Base URL & Headers​

2) Give the LLM the OpenAPI spec​

3) Minimal Endpoint Cheat‑Sheet (verified)​

Search orderable tiles​

Orders — list, estimate, create​

Data availability​

Downloads (GeoTIFF bytes unless you provide uploadUrl)​

4) Copy‑paste Prompt Templates​

A. “Wrap the API” (Python)​

B. “Plan + run an end‑to‑end flow”​

C. “Safety guardrails” (good to paste before asking an LLM to write code)​

5) Quick cURL & Python examples​

cURL — estimate → create order​

Python — composite download to a local file​

6) Pitfalls & guardrails for LLM‑written code​

7) Data specifics (for post‑processing)​

8) Keep secrets safe​

Appendix — Where these come from (for your LLM to verify later)​