{ "openapi": "3.0.4", "info": { "title": "EarthLife Tasking API", "version": "1.0", "description": "EarthLife Tasking API for authenticating clients, browsing image catalog options, and creating or retrieving satellite tasking requests.\n\n**Base URLs**\n- Most operations use the Gateway base URL (`/gateway`).\n- Token issuance (`POST /connect/token`) uses the Auth base URL (`/auth`).\n\nObtain a Bearer access token from Auth, then call Gateway endpoints with `Authorization: Bearer `.", "contact": { "name": "SARsatX", "url": "https://sarsatx.com" } }, "servers": [ { "url": "https://earthlife.sarsatx.com/gateway", "description": "API Gateway" } ], "tags": [ { "name": "Authentication", "description": "Generate and refresh access tokens (Auth base URL)." }, { "name": "Catalog", "description": "Lookup helpers for tasking options (image types, resolutions)." }, { "name": "Tasking", "description": "Create and retrieve tasking requests." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/connect/token": { "post": { "tags": [ "Authentication" ], "summary": "Generate an access token", "description": "Generate an access token to call Gateway API endpoints.\n\n**Auth base URL required.** This operation is served by the Auth service (`/auth`), not the Gateway. Use one of the Auth servers listed on this operation.\n\nUse `grant_type=password` with your account email and password.\n\nTo renew without sending the password again, use `grant_type=refresh_token` with the refresh token from a previous response that included the `offline_access` scope.\n\nSet `Content-Type` to `application/x-www-form-urlencoded`.", "operationId": "generateAccessToken", "servers": [ { "url": "https://earthlife.sarsatx.com/auth", "description": "Auth Server" } ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PasswordTokenRequest" }, { "$ref": "#/components/schemas/RefreshTokenRequest" } ] }, "examples": { "passwordGrant": { "summary": "Password grant", "value": { "grant_type": "password", "client_id": "earthlife-tasking-api", "username": "user@example.com", "password": "********", "scope": "openid profile email roles offline_access earthlife.orders", "culture": "en" } }, "refreshGrant": { "summary": "Refresh token grant", "value": { "grant_type": "refresh_token", "client_id": "earthlife-tasking-api", "refresh_token": "CfDJ8A..." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "examples": { "tokenResponse": { "summary": "Access token issued", "value": { "access_token": "CfDJ8A...", "expires_in": 3600, "token_type": "Bearer", "refresh_token": "CfDJ8A...", "scope": "openid profile email roles offline_access earthlife.orders" } } } } } }, "400": { "description": "Invalid request. Check `grant_type`, `client_id`, credentials, or refresh token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "401": { "description": "Unauthorized. The credentials are wrong, the client is not allowed, or the refresh token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "415": { "description": "Unsupported media type. Set `Content-Type` to `application/x-www-form-urlencoded`." } } } }, "/order/Lookup/GetImageTypesList": { "get": { "tags": [ "Catalog" ], "summary": "List image types", "description": "Returns available image types for tasking catalog selection.", "operationId": "listImageTypes", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImageTypeModel" } }, "examples": { "imageTypes": { "summary": "Optical and SAR image types", "value": [ { "ImageTypeID": 1, "NameAr": "متعدد الأطياف", "NameEn": "Multispectral", "PreviewImage": "", "IsActive": true, "IsOpenData": true, "IsCommercial": false }, { "ImageTypeID": 2, "NameAr": "خلال النهار", "NameEn": "Daytime", "PreviewImage": "", "IsActive": true, "IsOpenData": true, "IsCommercial": true }, { "ImageTypeID": 3, "NameAr": "SAR", "NameEn": "SAR", "PreviewImage": "", "IsActive": true, "IsOpenData": true, "IsCommercial": true }, { "ImageTypeID": 4, "NameAr": "(Stereo) ستيريو", "NameEn": "Stereo", "PreviewImage": "", "IsActive": true, "IsOpenData": false, "IsCommercial": true } ] } } } } }, "401": { "description": "Unauthorized. Missing or invalid access token." } } } }, "/order/Lookup/GetImageResolutions": { "get": { "tags": [ "Catalog" ], "summary": "List image resolutions", "description": "Returns available image resolutions for tasking catalog selection. When creating a tasking request, use only an `imageResolutionID` where `\"isActive\": true`.", "operationId": "listImageResolutions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResolutionModel" } }, "examples": { "imageResolutions": { "summary": "Sample image resolutions", "value": [ { "ImageResolutionID": 1, "NameAr": "عالي", "NameEn": "High", "MinimumValueInCM": 30, "MaximumValueInCM": 50, "DescriptionAr": "دقة عالية", "DescriptionEn": "High resolution", "PreviewImage": null, "IsActive": true, "IsSubscriberOnly": false, "DisplayOrder": 1 }, { "ImageResolutionID": 2, "NameAr": "فائق", "NameEn": "Very High", "MinimumValueInCM": 10, "MaximumValueInCM": 30, "DescriptionAr": "دقة فائقة", "DescriptionEn": "Very high resolution", "PreviewImage": null, "IsActive": true, "IsSubscriberOnly": false, "DisplayOrder": 2 } ] } } } } }, "401": { "description": "Unauthorized. Missing or invalid access token." } } } }, "/order/Order/CreateOrder": { "post": { "tags": [ "Tasking" ], "summary": "Create a tasking order", "description": "Creates a new tasking order. Use `\"serviceID\": 3` — this is the Tasking service ID — with the tasking `cartItemDataList` fields shown in the example.", "operationId": "createOrder", "parameters": [ { "name": "note", "in": "query", "description": "Optional note attached to the request.", "schema": { "type": "string" } }, { "name": "refNo", "in": "query", "description": "Optional reference number.", "schema": { "type": "string" } }, { "name": "paymentMethod", "in": "query", "description": "Organization payment method for this request.", "schema": { "$ref": "#/components/schemas/OrganizationPaymentTypeEnum" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartItemBaseModel" }, "examples": { "createTasking": { "summary": "Tasking order (`serviceID` 3 = Tasking service)", "value": { "ServiceID": 3, "CartItemDataList": [ { "DataKey": "POI", "DataValue": "{\"type\":\"Point\",\"coordinates\":[39.293687516,21.557888091]}" }, { "DataKey": "ImageResolutionID", "DataValue": "" }, { "DataKey": "FirstImageDate", "DataValue": "2026-09-14T09:00:00.000Z" }, { "DataKey": "SecondImageDate", "DataValue": "2026-09-15T09:00:00.000Z" }, { "DataKey": "ImageTypeID", "DataValue": "" }, { "DataKey": "ImageProviderID", "DataValue": "auto" }, { "DataKey": "CloudCover", "DataValue": "30" } ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponseModelSystemResponse" }, "examples": { "created": { "summary": "Tasking request created", "value": { "IsSuccess": true, "Message": null, "ReturnedValue": { "OrderData": { "OrderID": 694, "UserID": 42, "OrderStatusID": 1, "OrderStatusTitle": "Pending", "PaymentMethodTypeID": 1, "OrganizationPaymentType": 1, "PaymentMethodTypeTitle": "Subscription", "UUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "OrderNo": "ORD-2026-0694", "RefNo": "0", "CostPrice": 0, "Price": 0, "Discount": 0, "Tax": 0, "NetPrice": 0, "Note": null, "OrderDate": "2026-09-13T08:00:00Z", "AddedBy": "user@example.com", "AddedDate": "2026-09-13T08:00:00Z", "Invoice": null, "OrderItems": [] }, "HasSubscription": true, "PaymentURL": "" } } } } } } }, "401": { "description": "Unauthorized. Missing or invalid access token." } } } }, "/order/Order/GetOrderDetails": { "get": { "tags": [ "Tasking" ], "summary": "Get order details", "description": "Returns details for a single order by ID.", "operationId": "getOrderDetails", "parameters": [ { "name": "orderID", "in": "query", "required": true, "description": "The order ID.", "schema": { "type": "integer", "format": "int32" }, "example": 694 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderModel" }, "examples": { "orderDetails": { "summary": "Order details", "value": { "OrderID": 694, "UserID": 42, "OrderStatusID": 1, "OrderStatusTitle": "Pending", "PaymentMethodTypeID": 1, "OrganizationPaymentType": 1, "PaymentMethodTypeTitle": "Subscription", "UUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "OrderNo": "ORD-2026-0694", "RefNo": "0", "CostPrice": 0, "Price": 0, "Discount": 0, "Tax": 0, "NetPrice": 0, "Note": null, "OrderDate": "2026-09-13T08:00:00Z", "AddedBy": "user@example.com", "AddedDate": "2026-09-13T08:00:00Z", "Invoice": null, "OrderItems": [ { "OrderItemID": 2001, "OrderID": 694, "ServiceID": 3, "ServiceName": "مهمة جديدة", "ServiceNameEn": "Tasking", "Price": 0, "Tax": 0, "Quantity": 1, "Note": null, "OrderItemDetail": { "OrderItemID": 2001, "AOI": null, "AOIAreaInKM": null, "CountryCode": "SA", "CountryName": "Saudi Arabia", "ImageTypeID": 2, "ImageTypeName": "Daytime", "ImageResolutionID": 4, "ImageResolutionName": "High", "CaptureAttempFrom": "2026-09-14T09:00:00.000Z", "CaptureAttempTo": "2026-09-15T09:00:00.000Z", "IsTopPriority": false, "AllowflexibleDate": true, "FlexibleDays": 3, "CloudCover": 30, "ImageProviderID": null, "ImageProviderName": "auto" } } ] } } } } } }, "401": { "description": "Unauthorized. Missing or invalid access token." } } } }, "/order/Order/GetOrders": { "post": { "tags": [ "Tasking" ], "summary": "List orders", "description": "Returns a filtered, paged list of orders.", "operationId": "listOrders", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrdersFilterRequest" }, "examples": { "listFilter": { "summary": "Paged list with date range", "value": { "PageIndex": 0, "PageSize": 10, "SortField": "OrderDate", "SortOrder": "desc", "FilterValue": null, "OrderDateFrom": "2026-01-01T00:00:00Z", "OrderDateTo": "2026-12-31T23:59:59Z", "IncludeOrderItems": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderModelListSystemResponseList" }, "examples": { "orderList": { "summary": "Paged orders", "value": { "IsSuccess": true, "Message": null, "ReturnedValue": [ { "OrderID": 694, "UserID": 42, "OrderStatusID": 1, "OrderStatusTitle": "Pending", "PaymentMethodTypeID": 1, "OrganizationPaymentType": 1, "PaymentMethodTypeTitle": "Subscription", "UUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "OrderNo": "ORD-2026-0694", "RefNo": "0", "CostPrice": 0, "Price": 0, "Discount": 0, "Tax": 0, "NetPrice": 0, "Note": null, "OrderDate": "2026-09-13T08:00:00Z", "AddedBy": "user@example.com", "AddedDate": "2026-09-13T08:00:00Z", "Invoice": null, "OrderItems": [] } ], "TotalCount": 1 } } } } } }, "401": { "description": "Unauthorized. Missing or invalid access token." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Bearer", "description": "OAuth2 Bearer access token. Obtain a token from `POST /connect/token` on the Auth base URL. Pass as `Authorization: Bearer YOUR_ACCESS_TOKEN`." } }, "schemas": { "PasswordTokenRequest": { "type": "object", "required": [ "grant_type", "client_id", "username", "password" ], "properties": { "grant_type": { "type": "string", "description": "The OAuth grant type. Must be `password`.", "enum": [ "password" ], "example": "password" }, "client_id": { "type": "string", "description": "The client ID.", "example": "earthlife-tasking-api" }, "username": { "type": "string", "format": "email", "description": "The email address used to sign in.", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "description": "The account password.", "example": "********" }, "scope": { "type": "string", "description": "Space-separated scopes. Include `offline_access` to receive a refresh token.", "example": "openid profile email roles offline_access earthlife.orders" }, "culture": { "type": "string", "description": "Optional culture/locale code for localized responses (for example `en` or `ar`).", "example": "en" } } }, "RefreshTokenRequest": { "type": "object", "required": [ "grant_type", "client_id", "refresh_token" ], "properties": { "grant_type": { "type": "string", "description": "The OAuth grant type. Must be `refresh_token`.", "enum": [ "refresh_token" ], "example": "refresh_token" }, "client_id": { "type": "string", "description": "The client ID.", "example": "earthlife-tasking-api" }, "refresh_token": { "type": "string", "description": "The refresh token returned from a previous token request that included the `offline_access` scope.", "example": "CfDJ8A..." } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "expires_in", "token_type" ], "properties": { "access_token": { "type": "string", "description": "The Bearer access token used in the Authorization header.", "example": "CfDJ8A..." }, "expires_in": { "type": "integer", "description": "The lifetime of the access token in seconds.", "example": 3600 }, "token_type": { "type": "string", "description": "The token type. Always `Bearer`.", "example": "Bearer" }, "refresh_token": { "type": "string", "description": "The refresh token. Present when `offline_access` was requested. Use it with `grant_type=refresh_token` to obtain a new access token.", "example": "CfDJ8A..." }, "scope": { "type": "string", "description": "The scopes granted for this token.", "example": "openid profile email roles offline_access earthlife.orders" } } }, "OAuthError": { "type": "object", "properties": { "error": { "type": "string", "description": "OAuth error code (for example `invalid_grant` or `invalid_client`).", "example": "invalid_grant" }, "error_description": { "type": "string", "nullable": true, "description": "Human-readable description of the error.", "example": "The username/password couple is invalid." } } }, "ImageTypeModel": { "type": "object", "properties": { "ImageTypeID": { "type": "integer", "format": "int32" }, "NameAr": { "type": "string" }, "NameEn": { "type": "string" }, "PreviewImage": { "type": "string", "nullable": true }, "IsActive": { "type": "boolean" }, "IsOpenData": { "type": "boolean" }, "IsCommercial": { "type": "boolean" } } }, "ImageResolutionModel": { "type": "object", "properties": { "ImageResolutionID": { "type": "integer", "format": "int32" }, "NameAr": { "type": "string" }, "NameEn": { "type": "string" }, "MinimumValueInCM": { "type": "number", "nullable": true }, "MaximumValueInCM": { "type": "number", "nullable": true }, "DescriptionAr": { "type": "string" }, "DescriptionEn": { "type": "string" }, "PreviewImage": { "type": "string", "nullable": true }, "IsActive": { "type": "boolean" }, "IsSubscriberOnly": { "type": "boolean" }, "DisplayOrder": { "type": "integer", "format": "int32", "nullable": true } } }, "OrganizationPaymentTypeEnum": { "type": "integer", "format": "int32", "enum": [ 1, 2, 3, 4, 5 ], "description": "Payment method for the request. Use `1` when calling CreateOrder as shown in the guides.", "x-enum-varnames": [ "Subscription", "Credit", "Behalf", "Personaly", "NoneOrganization" ] }, "CartItemDataModel": { "type": "object", "properties": { "ServiceInputDataID": { "type": "integer", "format": "int32" }, "DataKey": { "type": "string", "description": "Input key (for example `POI`, `ImageTypeID`, `ImageResolutionID`, `FirstImageDate`, `SecondImageDate`, `ImageProviderID`, `CloudCover`)." }, "DataValue": { "type": "string", "nullable": true } } }, "CartItemBaseModel": { "type": "object", "properties": { "CartItemID": { "type": "integer", "format": "int32" }, "CartID": { "type": "string", "nullable": true }, "ServiceID": { "type": "integer", "format": "int32", "description": "Service ID. For tasking, use `3` (the Tasking service)." }, "Price": { "type": "number", "nullable": true }, "TaxRatio": { "type": "number", "nullable": true }, "Tax": { "type": "number", "nullable": true }, "Note": { "type": "string", "nullable": true }, "Quantity": { "type": "integer", "format": "int32", "default": 1 }, "IsFree": { "type": "boolean" }, "CartItemDataList": { "type": "array", "items": { "$ref": "#/components/schemas/CartItemDataModel" } } } }, "OrderResponseModel": { "type": "object", "properties": { "OrderData": { "$ref": "#/components/schemas/OrderModel" }, "HasSubscription": { "type": "boolean", "nullable": true }, "PaymentURL": { "type": "string" } } }, "OrderResponseModelSystemResponse": { "type": "object", "properties": { "IsSuccess": { "type": "boolean" }, "Message": { "type": "string", "nullable": true }, "ReturnedValue": { "$ref": "#/components/schemas/OrderResponseModel" } } }, "GetOrdersFilterRequest": { "type": "object", "properties": { "PageIndex": { "type": "integer", "format": "int32", "default": 0 }, "PageSize": { "type": "integer", "format": "int32", "default": 10 }, "SortField": { "type": "string", "nullable": true }, "SortOrder": { "type": "string", "nullable": true, "description": "Sort direction (for example `asc` or `desc`)." }, "FilterValue": { "type": "string", "nullable": true }, "OrderStatusIds": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "ServiceIds": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "OrderDateFrom": { "type": "string", "format": "date-time", "nullable": true }, "OrderDateTo": { "type": "string", "format": "date-time", "nullable": true }, "IncludeOrderItems": { "type": "boolean", "default": true } } }, "OrderModelListSystemResponseList": { "type": "object", "properties": { "IsSuccess": { "type": "boolean" }, "Message": { "type": "string", "nullable": true }, "ReturnedValue": { "type": "array", "items": { "$ref": "#/components/schemas/OrderModel" } }, "TotalCount": { "type": "integer", "format": "int32" } } }, "OrderModel": { "type": "object", "properties": { "OrderID": { "type": "integer", "format": "int32" }, "UserID": { "type": "integer", "format": "int32" }, "OrderStatusID": { "type": "integer", "format": "int32" }, "OrderStatusTitle": { "type": "string" }, "PaymentMethodTypeID": { "type": "integer", "format": "int32", "nullable": true }, "OrganizationPaymentType": { "type": "integer", "format": "int32", "nullable": true }, "PaymentMethodTypeTitle": { "type": "string", "nullable": true }, "UUID": { "type": "string" }, "OrderNo": { "type": "string" }, "RefNo": { "type": "string", "nullable": true }, "CostPrice": { "type": "number" }, "Price": { "type": "number" }, "Discount": { "type": "number" }, "Tax": { "type": "number" }, "NetPrice": { "type": "number" }, "Note": { "type": "string", "nullable": true }, "OrderDate": { "type": "string", "format": "date-time" }, "AddedBy": { "type": "string" }, "AddedDate": { "type": "string", "format": "date-time" }, "Invoice": { "type": "string", "nullable": true }, "OrderItems": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItemModel" } } } }, "OrderItemModel": { "type": "object", "properties": { "OrderItemID": { "type": "integer", "format": "int32" }, "OrderID": { "type": "integer", "format": "int32" }, "ServiceID": { "type": "integer", "format": "int32" }, "ServiceName": { "type": "string" }, "ServiceNameEn": { "type": "string" }, "Price": { "type": "number" }, "Tax": { "type": "number" }, "Quantity": { "type": "integer", "format": "int32" }, "Note": { "type": "string", "nullable": true }, "OrderItemDetail": { "$ref": "#/components/schemas/OrderItemDetailModel" } } }, "OrderItemDetailModel": { "type": "object", "description": "Tasking-relevant order item detail. Includes AOI, image catalog refs, and capture window fields. Some internal or secondary fields are omitted for clarity.", "properties": { "OrderItemID": { "type": "integer", "format": "int32" }, "AOI": { "type": "string", "nullable": true, "description": "Area of interest geometry (typically GeoJSON polygon as a string)." }, "AOIAreaInKM": { "type": "number", "nullable": true }, "AOIIntersection": { "type": "string", "nullable": true }, "AOIIntersectionAreaInKM": { "type": "number", "nullable": true }, "CountryCode": { "type": "string", "nullable": true }, "CountryName": { "type": "string", "nullable": true }, "CountryNameAr": { "type": "string", "nullable": true }, "CityName": { "type": "string", "nullable": true }, "CityNameAr": { "type": "string", "nullable": true }, "RegionName": { "type": "string", "nullable": true }, "RegionNameAr": { "type": "string", "nullable": true }, "ImageProviderID": { "type": "integer", "format": "int32", "nullable": true }, "ImageProviderName": { "type": "string", "nullable": true }, "ImageTypeID": { "type": "integer", "format": "int32", "nullable": true }, "ImageTypeName": { "type": "string", "nullable": true }, "ImageResolutionID": { "type": "integer", "format": "int32", "nullable": true }, "ImageResolutionName": { "type": "string", "nullable": true }, "CloudCover": { "type": "number", "nullable": true }, "GSDInM": { "type": "number", "nullable": true }, "CaptureAttempFrom": { "type": "string", "format": "date-time", "nullable": true, "description": "Start of the requested capture window." }, "CaptureAttempTo": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the requested capture window." }, "IsTopPriority": { "type": "boolean", "nullable": true }, "NewImageRecurrencePerMonth": { "type": "integer", "format": "int32", "nullable": true }, "AllowflexibleDate": { "type": "boolean", "nullable": true }, "FlexibleDays": { "type": "integer", "format": "int32", "nullable": true }, "AllowflexibleDateSecond": { "type": "boolean", "nullable": true }, "FlexibleDaysSecond": { "type": "integer", "format": "int32", "nullable": true }, "PaymentType": { "$ref": "#/components/schemas/OrganizationPaymentTypeEnum" } } } } } }