.. Copyright (C) 2025 SpaceKnow, Inc.

.. _api.quickstart:

==============
API Quickstart
==============

The goal of this part of the documentation is to give a quickstart instructions
on how to use SpaceKnow API.

* **Authenticate**. You received a SpaceKnow account with user name (email) and password.
  SpaceKnow API uses `JWT Bearer Token`_ authentication.

    * First, you need to obtain a token by calling the :docs:`OAuth endpoint<redoc.html#/paths/~1oauth~1ro/post>`.

    * For subsequent API calls, use header ``Authorization`` with value ``Bearer <token>``.

* **Asynchronous APIs**. Most of our APIs are asynchronous, see :ref:`Asynchronous APIs<api.mechanics.asynchronous>`
  for details.

    * Such API is started by calling ``.../initiate`` endpoint which returns a pipeline ID on success.

    * Status of a pipeline can be polled using :ref:`Tasking API<api.tasking>`.

    * Once a pipeline has finished, its status will change to ``RESOLVED`` and its result can be then
      retrieved using ``.../retrieve`` endpoint.

    * Both **Search for imagery** and **Run analysis** endpoints mentioned below are asynchronous.

- **Search for imagery**.

    * The flow starts with searching for imagery ("scenes"). See :ref:`Search Scenes <api.ragnar.search>` for details.

    * We have several scenes which are free of charge to use, so you probably want to start with those,
      see :ref:`Free scenes <api.credits.free-scenes>`. To narrow the search down to actually find one of the
      free scenes, we recommend using an appropriate extent and start and end datetimes
      in :docs:`search API call<redoc.html#tag/Imagery/operation/Search_Initiate_imagery_search_initiate_post>`.
      You can identify the scenes in results by their ``sceneId``.

- **Run analysis**. Once you have the scene, you can run analysis over it. See :ref:`Kraken Release API<api.kraken.release>`.

    * Use scene ID of the free scene found above. For ``mapTypes`` use ``["imagery"]`` to get only image tiles. For real usage, you can
      set any algos you have permission to access to.

- **Get mercator tiles**. When Kraken release finishes, you obtain ``mapId`` and ``tiles`` available for your finished map.
  See :ref:`Grid API<api.kraken.grid>` and :docs:`Grid API reference<redoc.html#tag/Kraken/operation/Tile_File_kraken_grid__signed_map_id___request_geometry_id___zoom___x___y___file_name__get>`.

    * For ``zoom``, ``x`` and ``y`` use one of the ``tiles`` returned in the previous call.
      The ``tiles`` are returned as ``zoom, x, y`` triples. You can also request any of the child WebMercator
      tiles up to ``maxZoom``. See `Web Mercator Tiles`_ tool to play with this system.

.. _JWT Bearer Token: https://jwt.io/
.. _Web Mercator Tiles: https://docs.maptiler.com/google-maps-coordinates-tile-bounds-projection/