Skip to main content

FarEarth APIs

FarEarth has a comprehensive set of APIs to query and control the system. You can add new users, start processing orders, query their status, and much more.

The curl examples below are meant as a quick start for a few common interactions.

Examples​

Hello world​

A simple way to test your API key and whether you can communicate with FarEarth is to use the hello api:

curl -k -s \
  -H "X-API-Key: <your-api-key>" \
  https://gateway.farearth.space/api/ext/v1/test/hello

You can also use the whoAmI endpoint, which will return your user information:

curl -k -s \
  -H "X-API-Key: <your-api-key>" \
  https://gateway.farearth.space/api/ext/v1/test/whoAmI

You should receive a response:

{
  "email": "jane.smith@example.com",
  "roles": ["OPERATOR", "ADMIN", "USER"],
  "subscriptionId": "jsmith",
  "familyName": "Smith",
  "givenName": "Jane" 
}
note

The subscriptionId is useful as they are often required for other API calls

Starting orders from the Catalogue​

To start orders from the Catalogue, you require the STAC feature (see STAC examples for more information).

Step 1: Obtain a product from the Catalogue​

The example below searches the Catalogue for a product given a specific date-range.

curl -k -s \
  -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5, "datetime": "2025-12-01T00:00:00Z/2025-12-31T23:59:59Z"}' \
  "https://gateway.farearth.space/api/ext/v1/stac/catalogs/<farearth-catalogue-id>/<catalog-id>/search"

The response is a FeatureCollection, which contains a Product ID (id), as well as an assets block for each result. The URLs in the assets block are short-lived temporary URLs to download the individual files.

Step 2: Start the order​

To start the order, you specify the product ID:

curl -k -s \
  -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "Feature",
      "id": "ID_1",
      "stac_version": "1.0.0",
      "assets": {},
      "properties": {
        "productType": "L1A",
        "spacecraft": "<your-spacecraft-id>",
        "datetime": "2025-12-03T12:19:36Z" 
      },
      "links": []
    },
    "orderParameters": {
      "workflowId": "<your-workflow-id>"
    }
  }' \
  "https://gateway.farearth.space/api/ext/v1/pickups/<pickup-id>/markInputReady"

The response will contain the unique Order ID (example, AAAA-1234).

Starting orders with a Workflow ID​

To start an order for a specific Workflow, you will require the Workflow ID. This is useful to run Workflows that do not require a specific input product. To process a specific product with a chosen Workflow, see Starting orders from the Catalogue.

You can start the order using a Workflow ID:

curl -k -s \
  -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://gateway.farearth.space/api/ext/v1/orders/workflow/<workflow-id>/start"

The response will contain the unique Order ID (example, AAAA-1234).

Check progress of an order​

To check the progress of an order using the Order ID, use:

curl -k -s \
  -H "X-API-Key: <your-api-key>" \
  "https://gateway.farearth.space/api/ext/v1/orders/order/<your-order-id>/jobs"

The response contains a map of Jobs--the individual steps being executed to complete the Order. Each Job will have a status: one of [SUCCESS, FAILED, IN_PROGRESS].

Here is an example response for an Order with a single Job (Step):

[
  {
    "id": "50421",
    "stepId": "step-1",
    "executorId": "<workflow-id>",
    "appId": "<your-app-id>",
    "startMillis": 1776842016364,
    "endMillis": 1776842017375,
    "jobState": {
      "status": "SUCCESS",
      "progress": 100.0,
      "progressMessage": "Started" 
    }
  }
]
note

For more information about Workflows, Orders and Jobs, see our blog post available here

List all orders​

To list all orders using a text-search (similar to how you can search for products in FarEarth), use:

curl -k -s \
  -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"searchText": "<query>"}' \
  "https://gateway.farearth.space/api/ext/v1/orders/search"

Below is an example response. The second response shows the response for a failed Order, with the error provided.

{
  "data": [
    {
      "subscriptionId": "jsmith",
      "id": "<your-order-id>",
      "createdMillis": 1776842007141,
      "startMillis": 1776842007234,
      "endMillis": 1776842021006,
      "status": "SUCCESS" 
    },
    {
      "subscriptionId": "jsmith",
      "id": "<your-order-id>",
      "createdMillis": 1776841705766,
      "startMillis": 1776841705775,
      "endMillis": 1776841705775,
      "status": "FAILED",
      "error": "Workflow not found." 
    }
  ],
  "page": 0,
  "limit": 100,
  "total": 313,
  "count": 100
}

List and download Workflows​

These APIs are useful for inspecting what a Workflow does before running it, or for creating a modified copy. The list endpoint returns all available Workflows with their steps and executor IDs. The download endpoint returns the full workflow definition as JSON.

To list all Workflows:

curl -k -s \
  -H "X-API-Key: <your-api-key>" \
  https://gateway.farearth.space/api/ext/v1/app/<your-app-id>/workflows/list

To download a Workflow:

curl -k -s \
  -H "X-API-Key: <your-api-key>" \
  "https://gateway.farearth.space/api/ext/v1/app/<your-app-id>/workflow/<workflow-id>.workflow.json"

The response will be a Workflow definition in JSON format.

Start order from Pickup​

If the data to be processed is already in the Pickup location (typically an S3 bucket), you can start an order by referring to the file or folder path.

To process a single file:

curl -k -s \
  -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://gateway.farearth.space/api/ext/v1/pickups/<pickup-id>/markFileReady?path=<path-to-file>"

To process a complete product folder:

curl -k -s \
  -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://gateway.farearth.space/api/ext/v1/pickups/<pickup-id>/markFolderReady?path=<path-to-folder>"