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](/apis/pixxel)) 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:**
```bash
curl --location 'https://api.pixxel.space/v0/projects' \
  --header 'Authorization: Bearer {{api_token}}'
```

**Response (200 OK):**
```json
{
  "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](https://aurora.pixxel.space/) UI.

---

### Get Project by ID

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

**Response (200 OK):**
```json
{
  "project": {
    "id": "string",
    "name": "string",
    "title": "string",
    "org_id": "string",
    "created_at": "string",
    "updated_at": "string",
    "metadata": {}
  }
}
```

---

## Bandsets

### List Bandsets

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

**Response (200 OK):**
```json
{
  "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](/developer/orders/tasking) and [Archive Ordering guide](/developer/orders/archive-ordering/archive) for which fields are required for each.

**Request:**
```bash
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):**
```json
{
  "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](/apis/pixxel/SubmitOrder) for all possible values.

---

### List Orders

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

**Response (200 OK):**
```json
{
  "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:**
```bash
curl --location 'https://api.pixxel.space/v0/orders/{id}' \
  --header 'Authorization: Bearer {{api_token}}'
```

**Response (200 OK):** Same shape as the [Submit Order response](#submit-order) above.

---

### List Order Items

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

**Response (200 OK):**
```json
{
  "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:**
```bash
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](#list-order-items) above.

---

## Archives

### Search Archive Items

**Request:**
```bash
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):**
```json
{
  "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:**
```bash
curl --location 'https://api.pixxel.space/v0/archives/collections' \
  --header 'Authorization: Bearer {{api_token}}'
```

**Response (200 OK):**
```json
{
  "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:**
```bash
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](#list-collections) above.

---

### List Items in a Collection

**Request:**
```bash
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](#search-archive-items) above.

---

### Get Collection Item by ID

**Request:**
```bash
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](#search-archive-items) above.

---

## Catalogs

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

### Search Catalogs

**Request:**
```bash
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):**
```json
{
  "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:**
```bash
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](#search-catalogs) above.

---

## Delivery (Cloud Stores)

### List Stores

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

**Response (200 OK):**
```json
{
  "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:**
```bash
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](#list-stores) above.

---

### Delete Store

**Request:**
```bash
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:**
```bash
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):**
```json
{
  "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:**
```bash
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](#create-delivery) above.

---

## Download

### Create Download

**Request:**
```bash
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):**
```json
{
  "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:**
```bash
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](#create-download) above.

---

## Reports

### Download Order Report

**Request:**
```bash
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](#error-response-format).

---

## Health Check

### Ping Server

**Request:**
```bash
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 Code | Meaning |
|-------------|---------|
| 200 | OK |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request |
| 403 | Forbidden |
| 404 | Not Found |
| 409 | Conflict |
| 500 | Internal Server Error |

---

## Error Response Format

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

```json
{
  "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:

```json
{
  "error": {
    "code": "string",
    "details": {},
    "message": "string"
  }
}
```