openapi: 3.0.3
info:
  title: SkyWatch EarthCache API
  description: >-
    The EarthCache API gives developers a single, provider-agnostic interface to
    discover, price, order, and deliver commercial satellite imagery and
    geospatial data. Create an archive Search over historical imagery, stand up a
    Pipeline that monitors an area of interest and delivers imagery on a
    schedule, retrieve interval results with analytics and metadata download
    URLs, estimate cost, manage reusable output configurations and saved
    locations, and subscribe to platform events via callback URIs. All requests
    are authenticated with an `x-api-key` header. Imagery is billed per square
    kilometre with resolution-based purchase minimums.


    This description is authored by API Evangelist for the apis.io network and is
    grounded in SkyWatch's public EarthCache API specification
    (v1.7, https://api-docs.earthcache.com/). It is not an official SkyWatch
    artifact.
  version: '1.7'
  contact:
    name: SkyWatch Support
    url: https://skywatch.com/support
    email: support@skywatch.com
servers:
  - url: https://api.skywatch.co/earthcache
    description: EarthCache production
security:
  - ApiKey: []
tags:
  - name: Archive Search
    description: Query historical imagery and retrieve matching search results.
  - name: Pipelines
    description: Standing orders that monitor an AOI and deliver imagery on a schedule.
  - name: Interval Results
    description: Results and delivery URLs produced by pipeline intervals.
  - name: Cost Estimation
    description: Estimate the cost of locations, intervals, and pipelines.
  - name: Outputs
    description: Reusable output configurations - format, bands, and mosaicking.
  - name: Locations
    description: Reusable server-side areas of interest from KML or GeoJSON.
  - name: Subscriptions
    description: Callback-based subscriptions to EarthCache platform events.
paths:
  /archive/search:
    post:
      tags:
        - Archive Search
      summary: Create a search
      operationId: createArchiveSearch
      description: >-
        Creates an asynchronous archive search over historical imagery for an
        area of interest and date window and returns the search id used to
        retrieve results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCreated'
        '400':
          description: Invalid search request.
  /archive/search/{id}/search_results:
    get:
      tags:
        - Archive Search
      summary: Get search results
      operationId: getArchiveSearchResults
      description: >-
        Returns the results of a previously created search. Returns 202 while the
        search is still processing and 200 with results once complete.
      parameters:
        - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '202':
          description: Search still processing; retry after a short delay.
  /pipelines:
    get:
      tags:
        - Pipelines
      summary: List pipelines
      operationId: listPipelines
      responses:
        '200':
          description: A list of pipelines.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineList'
    post:
      tags:
        - Pipelines
      summary: Create a pipeline
      operationId: createPipeline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineRequest'
      responses:
        '201':
          description: Pipeline created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
    delete:
      tags:
        - Pipelines
      summary: Delete multiple pipelines
      operationId: deletePipelines
      description: Delete multiple pipelines by id.
      responses:
        '204':
          description: Pipelines deleted.
  /pipelines/{id}:
    get:
      tags:
        - Pipelines
      summary: Get a pipeline
      operationId: getPipeline
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      responses:
        '200':
          description: The pipeline.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
    patch:
      tags:
        - Pipelines
      summary: Update a pipeline
      operationId: updatePipeline
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineRequest'
      responses:
        '200':
          description: Pipeline updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
    delete:
      tags:
        - Pipelines
      summary: Delete a pipeline
      operationId: deletePipeline
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      responses:
        '204':
          description: Pipeline deleted.
  /pipelines/{id}/interval_results:
    get:
      tags:
        - Interval Results
      summary: List interval results for a pipeline
      operationId: listPipelineIntervalResults
      description: >-
        The most common method of accessing pipeline results - lists the interval
        results produced by a single pipeline, including delivery URLs.
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      responses:
        '200':
          description: A list of interval results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntervalResultList'
  /pipelines/calculate:
    post:
      tags:
        - Cost Estimation
      summary: Calculate pipeline cost and probability of collection
      operationId: calculatePipeline
      description: >-
        Calculate the cost of the area and intervals of a pipeline, and the
        probability of collection for any tasking intervals.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineRequest'
      responses:
        '200':
          description: Calculated pipeline cost estimate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostEstimate'
  /price/calculate:
    post:
      tags:
        - Cost Estimation
      summary: Calculate price of a location and intervals
      operationId: calculatePrice
      description: >-
        Calculate the cost of a specified location and intervals, taking purchase
        minimums and pre-purchase discounts into account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceRequest'
      responses:
        '200':
          description: Calculated price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostEstimate'
  /price/{resolution}:
    get:
      tags:
        - Cost Estimation
      summary: Get price information
      operationId: getPrice
      description: Get price information for the caller's plan and an optional resolution.
      parameters:
        - name: resolution
          in: path
          required: true
          description: Resolution band (for example low, medium, high, very_high).
          schema:
            type: string
      responses:
        '200':
          description: Price information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostEstimate'
  /interval_results:
    get:
      tags:
        - Interval Results
      summary: List all interval results
      operationId: listIntervalResults
      description: List interval results across all of the caller's pipelines.
      responses:
        '200':
          description: A list of interval results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntervalResultList'
  /outputs:
    get:
      tags:
        - Outputs
      summary: List outputs
      operationId: listOutputs
      description: List the reusable output configurations available to the caller.
      responses:
        '200':
          description: A list of outputs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutputList'
  /outputs/{id}:
    get:
      tags:
        - Outputs
      summary: Get an output
      operationId: getOutput
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The output configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Output'
  /locations:
    get:
      tags:
        - Locations
      summary: List locations
      operationId: listLocations
      responses:
        '200':
          description: A list of saved locations.
    post:
      tags:
        - Locations
      summary: Create a location
      operationId: createLocation
      description: >-
        Create a saved location from KML or GeoJSON, abstracted into a reusable
        server-side instance referenced by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Location'
      responses:
        '201':
          description: Location created.
  /locations/{id}:
    get:
      tags:
        - Locations
      summary: Fetch a location
      operationId: getLocation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The location.
    patch:
      tags:
        - Locations
      summary: Update a location
      operationId: updateLocation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Location'
      responses:
        '200':
          description: Location updated.
    delete:
      tags:
        - Locations
      summary: Delete a location
      operationId: deleteLocation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Location deleted.
  /subscriptions:
    get:
      tags:
        - Subscriptions
      summary: List subscriptions
      operationId: listSubscriptions
      responses:
        '200':
          description: A list of subscriptions.
    post:
      tags:
        - Subscriptions
      summary: Create a subscription
      operationId: createSubscription
      description: >-
        Register a callback URI to receive events from the EarthCache platform.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '201':
          description: Subscription created.
  /subscriptions/{id}:
    post:
      tags:
        - Subscriptions
      summary: Update a subscription
      operationId: updateSubscription
      description: Update subscription properties such as callback_uri and status.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '200':
          description: Subscription updated.
    delete:
      tags:
        - Subscriptions
      summary: Delete a subscription
      operationId: deleteSubscription
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Subscription deleted.
  /subscriptions/{id}/sample:
    post:
      tags:
        - Subscriptions
      summary: Send subscription samples
      operationId: sampleSubscription
      description: Send sample event payloads to the subscription's callback URI.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Sample sent.
  /callbacks:
    get:
      tags:
        - Subscriptions
      summary: List callbacks
      operationId: listCallbacks
      description: >-
        Returns a list of callback invocations over the last 3 months (the
        retention period).
      responses:
        '200':
          description: A list of callback invocations.
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
  parameters:
    SearchId:
      name: id
      in: path
      required: true
      description: The id of the search.
      schema:
        type: string
    PipelineId:
      name: id
      in: path
      required: true
      description: The id of the pipeline.
      schema:
        type: string
  schemas:
    GeoJSON:
      type: object
      description: A GeoJSON geometry (typically a Polygon) describing the AOI.
      properties:
        type:
          type: string
          example: Polygon
        coordinates:
          type: array
          items: {}
    SearchRequest:
      type: object
      required:
        - location
        - start_date
        - end_date
      properties:
        location:
          $ref: '#/components/schemas/GeoJSON'
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        resolution:
          type: array
          items:
            type: string
          example:
            - low
        coverage:
          type: number
        interval_length:
          type: integer
        order_by:
          type: array
          items:
            type: string
          example:
            - resolution
    SearchCreated:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
    SearchResults:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              product_name:
                type: string
              source:
                type: string
              resolution:
                type: number
              cost:
                type: number
              preview_url:
                type: string
                format: uri
              thumbnail_url:
                type: string
                format: uri
              start_time:
                type: string
                format: date-time
    PipelineRequest:
      type: object
      required:
        - name
        - start_date
        - end_date
        - aoi
        - output
      properties:
        name:
          type: string
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        budget_per_km2:
          type: number
        max_cost:
          type: number
        cloud_cover_percentage:
          type: number
        min_aoi_coverage_percentage:
          type: number
        resolution_low:
          type: number
        resolution_high:
          type: number
        interval:
          type: string
          example: 1d
        result_delivery:
          type: object
          properties:
            max_latency:
              type: string
              example: 0d
            priorities:
              type: array
              items:
                type: string
              example:
                - latest
                - highest_resolution
                - lowest_cost
        aoi:
          $ref: '#/components/schemas/GeoJSON'
        output:
          type: object
          properties:
            id:
              type: string
            format:
              type: string
              example: geotiff
            mosaic:
              type: string
              example: 'off'
        tags:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              value:
                type: string
        status:
          type: string
          example: active
        sources:
          type: object
          properties:
            include:
              type: array
              items:
                type: string
              example:
                - Pleiades
                - Spot
                - PlanetScope
                - Sentinel-2
    Pipeline:
      allOf:
        - $ref: '#/components/schemas/PipelineRequest'
        - type: object
          properties:
            id:
              type: string
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
    PipelineList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Pipeline'
    Band:
      type: object
      properties:
        name:
          type: string
        data_type:
          type: string
        unit:
          type: string
        spectral_wavelength:
          type: number
        no_data_value:
          type: number
        raster_width:
          type: number
        raster_height:
          type: number
    IntervalResult:
      type: object
      properties:
        id:
          type: string
        output_id:
          type: string
        pipeline_id:
          type: string
        status:
          type: string
        message:
          type: string
        interval:
          type: string
        total_interval_cost:
          type: number
        probability_of_collection:
          type: number
        results:
          type: array
          items:
            type: object
            properties:
              analytics_url:
                type: string
                format: uri
              metadata_url:
                type: string
                format: uri
              capture_time:
                type: string
                format: date-time
              metadata:
                type: object
                properties:
                  bands:
                    type: array
                    items:
                      $ref: '#/components/schemas/Band'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    IntervalResultList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/IntervalResult'
    Output:
      type: object
      required:
        - id
        - name
        - provider
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        private:
          type: boolean
        cover_image:
          type: object
          properties:
            url:
              type: string
              format: uri
            alt_text:
              type: string
        provider:
          type: object
          required:
            - name
          properties:
            name:
              type: string
            logo_url:
              type: string
              format: uri
    OutputList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Output'
    Location:
      type: object
      properties:
        name:
          type: string
        geometry:
          $ref: '#/components/schemas/GeoJSON'
    CostEstimate:
      type: object
      properties:
        cost:
          type: number
        currency:
          type: string
          example: USD
        area_km2:
          type: number
        probability_of_collection:
          type: number
    Subscription:
      type: object
      required:
        - callback_uri
      properties:
        id:
          type: string
        callback_uri:
          type: string
          format: uri
        status:
          type: string
          example: active