Create an Order with the API

Use the Tasking endpoints to estimate and create orders programmatically. For order concepts and lifecycle context, see Ordering overview.

Prefer a Code-First Start?

Use Clearsky-Vision/clearsky_api_tools for runnable examples and a lightweight Python client (clearsky_client.py).

Example scripts include:

• 01_order_composite_area.py (estimate + create)
• 04_get_order_status.py (order status)
• 05_aoi_date_availability.py (availability)
• 06_download_composite.py (download)

Before You Start

• Pick your path:
  • Concept-first: continue with this page.
  • Code-first: start in Clearsky-Vision/clearsky_api_tools, then return here for endpoint-level guidance.
• Confirm API key setup and request headers: Get credentials / API key and Authentication.
• Decide ordering mode first (polygon vs tile/minitile): Choose an order type.
• For AOI input rules, use:
  • Define an area with polygon ordering, or
  • Define an area with tiles and minitiles ordering.
• Review how ordering is billed before automation rollout: Order credits vs processing units.

Typical Flow

1. Build the intended order payload (Wkt/GeoJson or GUID-based tile selection, plus model and date behavior).
2. Call estimate endpoint with that payload.
3. Validate estimated cost and returned candidate dates.
4. Submit the same validated payload to create the order.
5. Track created orders with GET /api/tasking/orders.
6. For recurring orders, cancel before 00:00 UTC on the first day of the next month if no longer needed (DELETE /api/tasking/orders/cancel, see Cancel or modify recurring orders).

Core Endpoints

• GET /api/tasking/orders
• POST /api/tasking/orders/estimate
• POST /api/tasking/orders
• DELETE /api/tasking/orders/cancel

For full endpoint contracts, see Tasking / order endpoints.

Payload Design Guide

1. Choose One AOI Mode

Use one AOI definition strategy per request:

• Polygon mode: Wkt or GeoJson (not both).
• Tile/minitile mode: GUID-based AOI selection from tile search results.

For geometry mode rules, see API conventions.

2. Select Time Behavior

• Historical order: set both From and To.
• Recurring order: set From and leave To empty.

See Historical vs recurring orders.

3. Set Cadence and Retention Intentionally

• ImageFrequency: revisit cadence.
• ReferenceDate: cadence alignment anchor across orders.
• StorageMonths: retention window for later downloads.
• ApiRequests: planned API retrieval pattern.

If you are tuning these for cost and retrieval behavior, also see Storage and extra requests.

4. Tile Deduplication (Tile/Mini-tile Orders)

Use TileDeduplication (boolean) in POST https://api.clearsky.vision/api/tasking/orders.

Set TileDeduplication to true to deduplicate tile/mini-tile orders based on all previous tile/mini-tile orders.

To get reliable deduplication behavior, keep order settings consistent across runs, especially:

• Model
• SatelliteConstellations
• AOI tile selection
• From / To time range behavior
• cadence settings (ImageFrequency, ReferenceDate) where applicable

If these settings drift, deduplication may not match prior orders as intended, and already-ordered data can be ordered again.

For endpoint-specific schema details, use the OpenAPI spec.

Common Date Patterns

Order intent	From	To
Historical backfill only	Start date	End date
Ongoing recurring monitoring	Start date	null
Backfill and continue recurring	Past date	null

See Historical vs recurring orders.

Minimal Example Body

{
  "Wkt": "POLYGON((9.87 56.47,10.19 56.47,10.19 56.28,9.87 56.28,9.87 56.47))",
  "SatelliteConstellations": ["Sentinel1", "Sentinel2", "Landsat89"],
  "Model": "Stratus2",
  "StorageMonths": 1,
  "ApiRequests": 1,
  "ImageFrequency": 3,
  "ReferenceDate": "2025-01-01",
  "From": "2025-04-01",
  "To": null
}

Example: Estimate Then Create (cURL)

curl -X POST "https://api.clearsky.vision/api/tasking/orders/estimate" \
  -H "x-api-key: $CLEARSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Wkt": "POLYGON((9.87 56.47,10.19 56.47,10.19 56.28,9.87 56.28,9.87 56.47))",
    "SatelliteConstellations": ["Sentinel1", "Sentinel2", "Landsat89"],
    "Model": "Stratus2",
    "StorageMonths": 1,
    "ApiRequests": 1,
    "ImageFrequency": 3,
    "ReferenceDate": "2025-01-01",
    "From": "2025-04-01",
    "To": null
  }'

After reviewing the estimate response, send the same body to POST /api/tasking/orders.

Validation and Automation Checklist

• Always estimate before create for large or automated orders.
• Handle 429 and transient 5xx responses with retry/backoff.
• Do not blindly retry validation errors; fix request payload first.
• Run availability checks before triggering downloads downstream.
• Keep model, constellation, and cadence settings stable when automating monthly/weekly programs.

See:

• Request limits
• Error codes
• Check availability
• Download with the API
• Model pricing
• Tile and minitile discounts

SatelliteConstellations affects both coverage behavior and the source-attribution notices that may be required when outputs are shared externally. Preserve and pass through required notices from order/output metadata. See Source attribution and external use.

For a runnable script example, see End-to-end Python workflow. For first-time testing, see Create your first order.