Pixxel
DocumentationDeveloper GuidePixxel API
Getting Started
IntroductionAuthentication & SecuritySetting Up
Identity and Access
Projects
Order Desk
BandsetsTasking

Orders & Order Items

Search
List supported satellitesSearch satellite images
AOIs
Create a new AOIList all AOIsGet AOI
Assets
List Assets for an AOIDownload Assets of an AOIGet status of Download request
Indices
Create IndexList all Indices
Visualizations
Create VisualizationList all Visualizations
Blocks
List BlocksGet Block VersionsGet Block by Version
Insights
Create InsightsList InsightsDownload InsightsDelete Insights
Workflows
List WorkflowsGet WorkflowGet Workflow Cost EstimateList Blocks - Workflows
Jobs
About Jobs and TasksCreate JobList JobsGet JobDownload JobDownload Task
Reference
Complete API Request/Response ExamplesData Types
Tasks
Download Tasks
Go to AuroraSupport
v0

Complete API Request/Response Examples

This page provides complete, production-ready examples for Pixxel API endpoints. Example values below are taken directly from the API specification (the same source that powers the Pixxel API reference) wherever the specification defines one. Where the specification does not define an example value for a field, a generic placeholder ("string", 0, true, etc.) is shown instead, consistent with how the field's type is declared in the spec.

Base URL: https://api.pixxel.space

Authentication: All endpoints require:

Authorization: Bearer {{api_token}}

Replace {{api_token}} with your Personal Access Token.

Projects

List Projects

Request:

curl --location 'https://api.pixxel.space/v0/projects' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK):

{
  "count": 0,
  "projects": [
    {
      "id": "string",
      "name": "string",
      "title": "string",
      "org_id": "string",
      "members_count": 0,
      "created_at": "string",
      "updated_at": "string",
      "metadata": {}
    }
  ]
}

Note: Project creation is not available via the API. Projects are created in the Aurora platform UI.

Get Project by ID

Request:

curl --location 'https://api.pixxel.space/v0/projects/{id}' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK):

{
  "project": {
    "id": "string",
    "name": "string",
    "title": "string",
    "org_id": "string",
    "created_at": "string",
    "updated_at": "string",
    "metadata": {}
  }
}

Bandsets

List Bandsets

Request:

curl --location 'https://api.pixxel.space/v0/bandsets' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK):

{
  "bandsets": [
    {
      "id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "name": "Agriculture",
      "description": "Agriculture bandset",
      "captures": 1,
      "bands": [
        {
          "name": "B001",
          "wavelength": 473
        }
      ]
    }
  ]
}

Orders

Submit Order

Both archive and tasking orders use the same endpoint. The fields that apply depend on the order type — see the Tasking guide and Archive Ordering guide for which fields are required for each.

Request:

curl --location 'https://api.pixxel.space/v0/orders' \
  --header 'Authorization: Bearer {{api_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "dry_run": false,
  "order_items": [
    {
      "project_id": "1234567890",
      "name": "Order Item 1",
      "geometry": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "properties": {},
            "geometry": {
              "type": "Polygon",
              "coordinates": [
                [
                  [-102.41263671019601, 34.221627630943814],
                  [-102.41263671019601, 34.189892538147575],
                  [-102.28599400714128, 34.189892538147575],
                  [-102.28599400714128, 34.221627630943814],
                  [-102.41263671019601, 34.221627630943814]
                ]
              ]
            }
          }
        ]
      },
      "recurrence": "ONCE",
      "start_date": "2020-10-22T00:00:00Z",
      "end_date": "2020-10-28T00:00:00Z",
      "no_of_occurrences": 0,
      "cloud_cover": 20,
      "bandset": {
        "bandset_id": "<BANDSET_ID>"
      },
      "delivery_speed": "STANDARD",
      "usecase": "agriculture",
      "item_ids": ["<ARCHIVE_ITEM_ID>"],
      "cloud_delivery": {
        "config": "d5f40033-4abd-48a1-a2f1-276df6edfeaf",
        "path": "my-bucket/my-folder"
      }
    }
  ]
}'

geometry is required for tasking and archive orders. recurrence, start_date, end_date, and no_of_occurrences are required for tasking. item_ids is required for archive orders. bandset.bandset_id is required for tasking.

Response (201 Created):

{
  "id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
  "org_id": "e31ab6f8-d359-4c6a-83c6-bfa32229bb01",
  "user_id": "90afd20d-8447-4636-a60d-73102008856c",
  "status": "PAID",
  "total_amount": 1000,
  "transaction_id": "3671066b-c4fd-4201-8e02-470cb6bc088e",
  "paid_at": "",
  "created_at": "2020-01-01T00:00:00+00:00",
  "created_by": "47435e2b-d8c4-41ff-9de9-2be3bfc92270",
  "updated_at": "2020-01-01T00:00:00+00:00",
  "updated_by": "47435e2b-d8c4-41ff-9de9-2be3bfc92270",
  "order_items": [
    {
      "id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "order_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "org_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "user_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "project_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "name": "order item 1",
      "type": "TASKING",
      "status": "ACTIVE",
      "payment_status": "PAID",
      "feasibility_status": "SUCCESS",
      "usecase": "agriculture",
      "area": 1000,
      "base_amount": 10000,
      "final_amount": 12000,
      "tokens_used": 100,
      "cloud_cover": 0,
      "number_of_bands": 2,
      "image_type": "VNIR",
      "delivery_speed": "STANDARD",
      "recurrence": "ONCE",
      "no_of_occurrences": 0,
      "start_date": "2020-10-22T00:00:00Z",
      "end_date": "2020-10-28T00:00:00Z",
      "last_feasibility_check": "2024-05-27T06:50:20.056549Z",
      "transaction_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "created_at": "2024-05-27T06:50:20.056549Z",
      "created_by": "b64d2c37-89c3-404d-8395-dedb0fe9131c",
      "updated_at": "2024-05-27T06:50:20.056549Z",
      "updated_by": "274a30f5-9ff2-4cc7-8680-7b2e076b9faf",
      "bandset": {
        "bandset_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276"
      },
      "cloud_delivery": {
        "config": "9af9ca14-8c0f-4b7b-ab5e-3a29fc7325b6",
        "path": "path/subdirectory1/"
      }
    }
  ]
}

status, type, payment_status, and feasibility_status are enums. The values shown above (PAID, TASKING, ACTIVE, SUCCESS) are examples — see the Pixxel API reference for all possible values.

List Orders

Request:

curl --location 'https://api.pixxel.space/v0/orders' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK):

{
  "orders": [
    { "...": "see the Submit Order response above for the full Order object shape" }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 100
  }
}

Get Order by ID

Request:

curl --location 'https://api.pixxel.space/v0/orders/{id}' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): Same shape as the Submit Order response above.

List Order Items

Request:

curl --location 'https://api.pixxel.space/v0/order-items' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK):

{
  "order_items": [
    {
      "id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "order_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "name": "order item 1",
      "type": "TASKING",
      "status": "ACTIVE",
      "tasks": [
        {
          "id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
          "order_item_id": "TD1_006800_20230528_L2A_20230615_03001067",
          "type": "ARCHIVE",
          "status": "FULFILLED",
          "delivery_status": "SUCCESSFUL",
          "start_date": "15-05-2024",
          "end_date": "25-05-2024",
          "number_of_strips": 4,
          "tokens_used": 10,
          "transaction_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
          "created_at": "2024-05-27T06:50:20.056549Z",
          "created_by": "e3ff4960-2d5a-4737-90dd-9cfb31bfa71e",
          "updated_at": "2024-05-27T06:50:20.056549Z",
          "updated_by": "77345b90-0677-4889-b4d8-2ddb93c0467f"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 100
  }
}

Get Order Item by ID

Request:

curl --location 'https://api.pixxel.space/v0/order-items/{id}' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): Same shape as one item of the List Order Items response above.

Archives

Search Archive Items

Request:

curl --location 'https://api.pixxel.space/v0/archives/search' \
  --header 'Authorization: Bearer {{api_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "bbox": [3, 4, 5, 6],
  "datetime": "2020-04-05T11:56:49.865Z/2023-06-05T11:56:49.865Z",
  "limit": 10,
  "offset": 0
}'

Response (200 OK):

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "20201211_223832_CS25",
      "type": "Feature",
      "collection": "simple-collection_2",
      "stac_version": "1.0.0",
      "bbox": ["172.91173669923782", "1.3438851951615003", "172.95469614953714", "1.3690476620161975"],
      "geometry": {
        "type": "Polygon",
        "coordinates": []
      },
      "properties": {
        "datetime": "2022-06-15T12:00:00Z",
        "startdatetime": "2022-01-01T00:00:00Z",
        "created": "2022-01-01T10:00:00Z",
        "updated": "2022-06-01T10:00:00Z",
        "title": "Example Title",
        "description": "Example description of the dataset",
        "license": "CC-BY-4.0",
        "platform": "TD1",
        "constellation": "TD1",
        "instruments": ["VNIR"],
        "gsd": 30,
        "altitude": 700,
        "eo:cloud_cover": 23.5,
        "proj:code": "EPSG:4326",
        "rd:product_level": "L2A",
        "rd:sat_id": "SAT-123",
        "view:off_nadir": 5,
        "view:sun_azimuth": 135,
        "view:sun_elevation": 45,
        "view:scene_center_lat": 12.3456,
        "view:scene_center_lon": -76.5432
      },
      "assets": {
        "B091": {
          "href": "https://example.com/asset.tif",
          "type": "image/tiff",
          "title": "Example Asset Title",
          "roles": ["data", "metadata"]
        }
      },
      "links": [
        { "href": "https://example.com", "rel": "self", "title": "Example Link Title", "type": "application/json" }
      ]
    }
  ],
  "links": []
}

List Collections

Request:

curl --location 'https://api.pixxel.space/v0/archives/collections' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK):

{
  "collections": [
    {
      "id": "pixxel-dd2",
      "type": "Collection",
      "title": "Pixxel-DD01",
      "description": "A collection description",
      "license": "proprietary",
      "stac_version": "0.1.0",
      "created_at": "2023-08-06T20:46:56.815552Z",
      "updated_at": "2023-08-06T20:46:56.815552Z",
      "providers": [
        { "name": "Pixxel", "description": "Pixxel is a space data company", "roles": ["producer"], "url": "https://pixxel.space" }
      ]
    }
  ]
}

Get Collection by ID

Request:

curl --location 'https://api.pixxel.space/v0/archives/collections/{cid}' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): Same shape as one item of the List Collections response above.

List Items in a Collection

Request:

curl --location 'https://api.pixxel.space/v0/archives/collections/{cid}/items' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): Same shape as the Search Archive Items response above.

Get Collection Item by ID

Request:

curl --location 'https://api.pixxel.space/v0/archives/collections/{cid}/items/{id}' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): Same shape as one item of features[] in the Search Archive Items response above.

Catalogs

Catalogs represent the fulfilled imagery from your orders — distinct from Archive search, which queries Pixxel's historical imagery library.

Search Catalogs

Request:

curl --location 'https://api.pixxel.space/v0/catalogs/search' \
  --header 'Authorization: Bearer {{api_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "bbox": [160.6, -55.95, -170, -25.89],
  "datetime": "2020-04-05T11:56:49.865Z/2023-06-05T11:56:49.865Z",
  "ids": ["47435e2b-d8c4-41ff-9de9-2be3bfc92276"],
  "item_ids": ["TD1_2024_ABC"],
  "order_ids": ["57435e2b-d8c4-41ff-9de9-2be3bfc92277"],
  "order_item_ids": ["57435e2b-d8c4-41ff-9de9-2be3bfc92278"],
  "limit": 50,
  "offset": 0
}'

Response (200 OK):

{
  "catalogs": [
    {
      "id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
      "org_id": "e31ab6f8-d359-4c6a-83c6-bfa32229bb01",
      "task_id": "ef8195b7-5ca6-4aca-a3fc-df6ffd58892d",
      "bandset_id": "47435e2b-d8c4-41ff-9de9-2be3bfc92277",
      "area": 100,
      "delivery_status": "SUCCESSFUL",
      "created_at": "2024-05-27T06:50:20.056549Z",
      "created_by": "0d7b3c5e-3b2a-4e77-bedb-5e0d2257cdb6",
      "updated_at": "2024-05-27T06:50:20.056549Z",
      "updated_by": "0ada9483-e3ed-4f31-8a69-372686966451"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 100
  }
}

Get Catalog by ID

Request:

curl --location 'https://api.pixxel.space/v0/catalogs/{id}' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): Same shape as one item of the Search Catalogs response above.

Delivery (Cloud Stores)

List Stores

Request:

curl --location 'https://api.pixxel.space/v0/stores' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK):

{
  "stores": [
    {
      "id": "576d8241-6e78-40ad-b3e6-295edbfe71f5",
      "name": "my-analysis-store",
      "type": "S3",
      "configs": {
        "bucket": "my-data-bucket",
        "region": "us-east-2",
        "path_prefix": "data/processed/"
      },
      "labels": {
        "env": "prod",
        "team": "data"
      },
      "created_at": "2024-03-20T15:04:05Z",
      "updated_at": "2024-03-20T15:04:05Z",
      "created_by": "ea2a79fc-6f68-40d7-8b79-18195bf74872"
    }
  ]
}

type is one of S3, GCS, AZBLOB.

Create Store

Request:

curl --location 'https://api.pixxel.space/v0/stores' \
  --header 'Authorization: Bearer {{api_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "my-analysis-store",
  "type": "S3",
  "configs": {
    "bucket": "my-data-bucket",
    "region": "us-east-2",
    "path_prefix": "data/processed/"
  },
  "secrets": {
    "access_key_id": "{{aws_access_key}}",
    "secret_access_key": "{{aws_secret_key}}"
  },
  "labels": {
    "env": "prod",
    "team": "data"
  }
}'

Required secrets keys depend on the store type: S3 needs access_key_id and secret_access_key; AZBLOB needs account_name, tenant_id, client_id, client_secret; GCS needs project_id and service_account_credentials.

Response (201 Created): Same shape as one item of the List Stores response above.

Delete Store

Request:

curl --location --request DELETE 'https://api.pixxel.space/v0/stores/{id}' \
  --header 'Authorization: Bearer {{api_token}}'

Response: 204 No Content — no response body.

Create Delivery

Request:

curl --location 'https://api.pixxel.space/v0/catalogs/deliveries' \
  --header 'Authorization: Bearer {{api_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "deliveries": [
    {
      "catalog_ids": ["47435e2b-d8c4-51ff-9de9-2be3bfc92276"],
      "cloud_info": {
        "config": "9af9ca14-8c0f-4b7b-ab5e-3a29fc7325b6",
        "path": "path/subdirectory1/"
      }
    }
  ]
}'

Provide either catalog_ids or order_item_ids per delivery — not both.

Response (201 Created):

{
  "deliveries": [
    {
      "delivery_id": "47435e2b-d8c4-41ff-9de9-2be3cfc92276",
      "catalog_id": "47435e2b-d8c4-51ff-9de9-2be3bfc92276",
      "task_id": "7f74a393-236f-4e02-9d22-b11dea4eac8a",
      "status": "SUCCESS",
      "target_path": "order_1/catalogs.zip",
      "cloud_delivery": {
        "config": "9af9ca14-8c0f-4b7b-ab5e-3a29fc7325b6",
        "path": "path/subdirectory1/"
      },
      "created_at": "2024-05-27T06:50:20.056549Z",
      "created_by": "60795589-8759-4d00-9162-b1537b66fb3e",
      "updated_at": "2024-05-27T06:50:20.056549Z",
      "updated_by": "b23d9181-4de1-4856-950b-e83b2ac52830"
    }
  ]
}

List/Get Deliveries

Request:

curl --location 'https://api.pixxel.space/v0/catalogs/deliveries?delivery_id={delivery_id}' \
  --header 'Authorization: Bearer {{api_token}}'

Optional query parameters: delivery_id, catalog_id, task_id, order_item_id.

Response (200 OK): Same shape as the Create Delivery response above.

Download

Create Download

Request:

curl --location 'https://api.pixxel.space/v0/catalogs/download' \
  --header 'Authorization: Bearer {{api_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "catalog_ids": ["47435e2b-d8c4-51ff-9de9-2be3bfc92276"]
}'

Provide either catalog_ids or order_item_ids — not both.

Response (201 Created):

{
  "id": "47435e2b-d8c4-41ff-9de9-2be3bfc92276",
  "status": "success",
  "signed_url": "http://signed_url_link"
}

status is one of success, created, failed, in_progress.

Get Download Status

Request:

curl --location 'https://api.pixxel.space/v0/catalogs/download/{download_id}' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): Same shape as the Create Download response above.

Reports

Download Order Report

Request:

curl --location 'https://api.pixxel.space/v0/reports' \
  --header 'Authorization: Bearer {{api_token}}'

Optional query parameter: tz (local timezone of the client).

Response: 200 OK with a text/csv file body (not JSON). Error responses (400/403/500) may be returned as text/csv or application/json, using the standard error format.

Health Check

Ping Server

Request:

curl --location 'https://api.pixxel.space/ping' \
  --header 'Authorization: Bearer {{api_token}}'

Response (200 OK): A plain string body (not a JSON object). The specification does not define its exact contents.

Common Response Codes

Status CodeMeaning
200OK
201Created
204No Content
400Bad Request
403Forbidden
404Not Found
409Conflict
500Internal Server Error

Error Response Format

Most endpoints (Orders, Bandsets, Catalogs, Stores, Deliveries, Downloads) return errors in this format:

{
  "error": {
    "code": "short string based code reflecting the type of error",
    "details": "additional details on the error",
    "message": "info message on the error"
  }
}

Archive endpoints (/v0/archives/*) use the same top-level shape:

{
  "error": {
    "code": "string",
    "details": {},
    "message": "string"
  }
}
Download TaskData Types