Skip to main content

API Conventions

Use this page as the integration guardrail for shared request/response behavior across API endpoint families.

Quick Integration Checklist​

  1. Send required headers exactly as documented in Authentication.
  2. Use exactly one geometry mode per request: Wkt or GeoJson.
  3. For downloads, run availability checks before estimate/process calls: Availability endpoints.
  4. Handle 429 and 5xx with retry/backoff and parse 400 Error.Code for corrective action: Error codes, Request limits.
  5. Lock projection choices early, especially for time-series and UTM edge areas: CRS / EPSG / UTM Guidance.

Request Shape Conventions​

Geometry Input Mode​

For endpoints accepting polygon geometry, send one of:

  • Wkt, or
  • GeoJson

Do not send both in the same request.

GeoJSON may appear in dashboard/docs when describing file formats. The API request field key is GeoJson.

Field Names and Types​

Use the OpenAPI contract as the source of truth for required fields, enum values, and data types:

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

Avoid inferred aliases or casing variants in automation code.

Model Value Conventions​

Docs and UI text may use display names such as Stratus-2 and Stratus-2 Fast.

API payloads must use exact Model enum values from GET /api/tasking/models (for example Stratus2, Stratus2Fast).

Do not insert display punctuation (-, spaces, parentheses) unless the API value itself contains it.

For most download automation:

  1. Discover or validate availability.
  2. Run estimate with the same payload shape.
  3. Process/download using unchanged validated settings.
  4. Persist binary output bytes, or provide UploadUrl for server-side delivery.

See endpoint-level contracts in Availability endpoints and Processing / download endpoints.

Status and Retry Conventions​

Status classMeaningRecommended handling
2xxRequest succeeded.Continue pipeline flow.
400Validation or domain rule failure.Parse Error.Code and Data; fix payload before retry. See Error codes.
401 / 403Authentication/authorization issue.Verify key, permissions, and account context. See Authentication.
404Resource/path/identifier mismatch.Re-check endpoint path and IDs; do not blind retry.
429Rate or concurrency limits reached.Exponential backoff with jitter; reduce in-flight concurrency. See Request limits.
5xxTransient server-side failure.Retry with exponential backoff and jitter until response becomes actionable.

Projection Conventions​

Use UTM-oriented EPSG settings as the default for quality-sensitive workflows:

  • explicit UTM EPSG (326xx / 327xx), or
  • 47000 (auto-EPSG mode).

For AOIs near UTM boundaries, decide UtmDataSelectionMode and related settings before production runs. Use CRS / EPSG / UTM Guidance for detailed tradeoffs.

Binary Delivery Conventions​

Processing endpoints may return GeoTIFF bytes directly unless UploadUrl is provided.

Prefer UploadUrl when pipelines should avoid holding large binary responses in memory.