Skip to content
Sitemark Developer Documentation

Operations

List Operations

Section titled “List Operations”

Retrieves a paginated list of operations.

Endpoint: GET /operations

Authentication: Required (API Key)

Query Parameters

Section titled “Query Parameters”
Parameter Type Required Description
id integer[] No Filter operations by one or more operation IDs.
site_id integer[] No Filter operations by one or more site IDs.
status string[] No Filter by one or more statuses. Valid values: DRAFT, ORDERED, ASSIGNED, PLANNED, FLOWN, UPLOADED, PROCESSING, IN_REVIEW, COMPLETED, CANCELLED.
data_product_id integer[] No Filter operations by one or more data product IDs.
_page integer No Page number (positive integer, defaults to 1)
_pageSize integer No Number of items per page (positive integer, max varies by configuration)
_sortBy string No Sort order. Format: +field for ascending or -field for descending.

Response Format

Section titled “Response Format”

Returns a paginated response with the following structure:

{
    "data": [
        {
            "id": "integer",
            "site_id": "integer",
            "date_captured": "date | null",
            "status": "string",
            "data_product_id": "integer",
            "data_product_name": "string | null",
            "description": "string | null",
            "date_start": "timestamp | null",
            "date_end": "timestamp | null",
            "contact_name": "string | null",
            "contact_phone": "string | null",
            "contact_mail": "string | null"
        }
    ],
    "pagination": {
        "page": "integer",
        "pageSize": "integer",
        "rowCount": "integer",
        "pageCount": "integer"
    }
}

Response Fields

Section titled “Response Fields”
  • id: Integer ID of the operation
  • site_id: Integer ID of the site this operation belongs to
  • date_captured: ISO 8601 date when the operation data was captured (can be null)
  • status: Current operation status (e.g. ASSIGNED, PLANNED, COMPLETED)
  • data_product_id: Integer ID of the data product associated with this operation
  • data_product_name: Name of the data product (can be null)
  • description: Operation description (can be null)
  • date_start: ISO 8601 timestamp for the start of the capture window (can be null)
  • date_end: ISO 8601 timestamp for the end of the capture window / deadline (can be null)
  • contact_name: Operation contact name (can be null)
  • contact_phone: Operation contact phone number (can be null)
  • contact_mail: Operation contact email address (can be null)

Example Requests

Section titled “Example Requests”

List all operations:

Terminal window
curl -X GET "https://api.sitemark.com/operations?_page=1&_pageSize=25" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by single site ID:

Terminal window
curl -X GET "https://api.sitemark.com/operations?site_id=5678&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by multiple site IDs (without brackets):

Terminal window
curl -X GET "https://api.sitemark.com/operations?site_id=5678&site_id=5679&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by multiple site IDs (with brackets):

Terminal window
curl -g -X GET "https://api.sitemark.com/operations?site_id[]=5678&site_id[]=5679&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by single operation ID:

Terminal window
curl -X GET "https://api.sitemark.com/operations?id=1234&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by multiple operation IDs (without brackets):

Terminal window
curl -X GET "https://api.sitemark.com/operations?id=1234&id=1235&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by multiple operation IDs (with brackets):

Terminal window
curl -g -X GET "https://api.sitemark.com/operations?id[]=1234&id[]=1235&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by status:

Terminal window
curl -g -X GET "https://api.sitemark.com/operations?status[]=ASSIGNED&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by data product ID:

Terminal window
curl -g -X GET "https://api.sitemark.com/operations?data_product_id[]=5&_page=1&_pageSize=50" \
  -H "Authorization: ApiKey your-api-key-here"

Example Response

Section titled “Example Response”
{
    "data": [
        {
            "id": 35495,
            "site_id": 123,
            "date_captured": null,
            "status": "ASSIGNED",
            "data_product_id": 5,
            "data_product_name": "Solar thermography 3cm",
            "description": "Solar thermography 3cm",
            "date_start": "2026-06-10T00:00:00Z",
            "date_end": "2026-06-20T00:00:00Z",
            "contact_name": "Jane Doe",
            "contact_phone": "+15551234567",
            "contact_mail": "jane.doe@example.com"
        }
    ],
    "pagination": {
        "page": 1,
        "pageSize": 25,
        "rowCount": 1,
        "pageCount": 1
    }
}

Error Responses

Section titled “Error Responses”
Status Code Description
401 Unauthorized - Invalid or missing API key
400 Bad Request - Invalid query parameters
429 Too Many Requests - A rate limit was exceeded
500 Internal Server Error

Create Operation

Section titled “Create Operation”

Creates an operation on a site. The operation is set up exactly as one ordered in the Sitemark web app, so flight planning can start right away.

Endpoint: POST /operations

Authentication: Required (API Key with the ORDER permission)

Body Parameters

Section titled “Body Parameters”
Parameter Type Required Description
site_id integer Yes ID of the site to fly
data_product_id integer Yes ID of the data product to order. It must be available for the site’s type
status string Yes DRAFT to save the operation without ordering it, or ORDERED to order it
fly_self boolean Yes true when your own pilots fly the site, false when Sitemark flies it
date_start timestamp When fly_self is false ISO 8601 start of the capture window. When fly_self is false: today or later, on the calendar of its own UTC offset
date_end timestamp When fly_self is false ISO 8601 end of the capture window, not before date_start. When fly_self is false: at least the data product’s minimum number of business days after date_start
geo_boundaries object No GeoJSON Feature with a valid Polygon or MultiPolygon geometry in WGS 84: the area to fly. It can extend outside the site boundary. Defaults to the site boundary
description string No Free-text description of the operation
contact_name string See Contact Name of the on-site contact. Defaults to the site contact
contact_phone string See Contact Phone number of the on-site contact. Defaults to the site contact
contact_mail string See Contact Email address of the on-site contact. Defaults to the site contact

The endpoint ignores any other top-level field, for example epsg, instructions, fast_track, tags and responsible_principal_id. The operation always uses the site’s coordinate system, and the API key is its responsible.

Contact

Section titled “Contact”

When Sitemark flies the site (fly_self is false), the operation must have a contact name, phone number and email address. Sitemark or one of its drone pilots calls this person to agree when to fly, for example around curtailment.

A contact field that you do not send, or send empty, takes its value from the site. When the field is empty on the site too, the request is rejected with 400, and the message names the field.

Ordering

Section titled “Ordering”

An ORDERED operation is rejected with 422 when the company cannot order it:

  • Sitemark flies it (fly_self is false), and there is no active data acquisition order for the data product.
  • There are not enough data product credits for the operation’s area.

The message says which check failed. Create the operation as DRAFT instead, and order it in the web app once the order or credits are in place.

Response Fields

Section titled “Response Fields”

Responds with 201 Created and the new operation, with the fields of the List Operations response. An ORDERED operation may already have moved on (ASSIGNED, PLANNED or FLOWN).

Example Request

Section titled “Example Request”
Terminal window
curl -X POST "https://api.sitemark.com/operations" \
  -H "Authorization: ApiKey your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
        "site_id": 123,
        "data_product_id": 5,
        "status": "ORDERED",
        "fly_self": false,
        "date_start": "2027-03-01T00:00:00Z",
        "date_end": "2027-04-30T00:00:00Z",
        "contact_name": "Jane Doe",
        "contact_phone": "+15551234567",
        "contact_mail": "jane.doe@example.com"
      }'

Example Response

Section titled “Example Response”
{
    "id": 35496,
    "site_id": 123,
    "date_captured": null,
    "status": "ORDERED",
    "data_product_id": 5,
    "data_product_name": "Solar thermography 3cm",
    "description": null,
    "date_start": "2027-03-01T00:00:00Z",
    "date_end": "2027-04-30T00:00:00Z",
    "contact_name": "Jane Doe",
    "contact_phone": "+15551234567",
    "contact_mail": "jane.doe@example.com"
}

Error Responses

Section titled “Error Responses”
Status Code Description
400 Bad Request - The message names the fields that are wrong
401 Unauthorized - Invalid or missing API key
403 Forbidden - The API key does not have the ORDER permission
404 Not Found - The site or data product does not exist, or the API key has no access to it
422 Unprocessable Content - The data product does not fit the site type, or the operation cannot be ordered
429 Too Many Requests - A rate limit was exceeded
500 Internal Server Error