Arlula API

openapi: 3.0.3
info:
  title: Arlula API
  description: >-
    The Arlula API provides programmatic access to satellite imagery ordering,
    archive search, tasking, and earth observation data services. The API covers
    four main areas: Archive (historical imagery search and ordering), Tasking
    (future satellite capture scheduling), Orders Management (order tracking and
    resource downloads), and connection testing.
  version: 2025-10
  contact:
    name: Arlula Support
    url: https://arlula.com/
  x-generated-from: documentation
  x-last-validated: '2026-04-19'
servers:
  - url: https://api.arlula.com
    description: Production API
security:
  - BasicAuth: []
tags:
  - name: Archive
    description: Search and order historical satellite imagery
  - name: Tasking
    description: Schedule future satellite captures
  - name: Orders
    description: Manage orders, campaigns, datasets, and resources
  - name: Connection
    description: API connection testing
paths:
  /api/test:
    get:
      operationId: testConnection
      summary: Arlula Test API Connection
      description: >-
        Validates API authentication credentials without executing any
        operational requests. Use this to confirm credentials are correctly
        configured.
      tags:
        - Connection
      responses:
        '200':
          description: Authentication successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestResponse'
              examples:
                testConnection200Example:
                  summary: Default testConnection 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: Authentication successful.
        '401':
          description: Unauthorized - invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/archive/search:
    post:
      operationId: searchArchive
      summary: Arlula Search Archive Imagery
      description: >-
        Search the Arlula satellite imagery archive and its suppliers for
        historical imagery matching specified date, location, and quality
        criteria. Returns available scenes with pricing, bands, and bundle
        options.
      tags:
        - Archive
      requestBody:
        required: true
        description: Archive imagery search parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveSearchRequest'
            examples:
              searchArchiveRequestExample:
                summary: Default searchArchive request
                x-microcks-default: true
                value:
                  start: '2025-01-01'
                  end: '2025-03-31'
                  gsd: 1.5
                  lat: -33.8523
                  long: 151.2108
                  cloud: 20
      responses:
        '200':
          description: Successfully retrieved archive search results.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArchiveScene'
              examples:
                searchArchive200Example:
                  summary: Default searchArchive 200 response
                  x-microcks-default: true
                  value:
                    - id: scene-a1b2c3d4
                      supplier: supplier-001
                      captureDate: '2025-02-15'
                      gsd: 1.5
                      cloudCover: 12
                      offNadir: 15.2
                      price: 150.00
                      bundles:
                        - key: bundle-basic
                          name: Basic Bundle
                          price: 150.00
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/archive/scene:
    get:
      operationId: getArchiveScene
      summary: Arlula Get Archive Scene Details
      description: >-
        Retrieve details for a previously returned archive search result by its
        ordering ID.
      tags:
        - Archive
      parameters:
        - name: id
          in: query
          required: true
          description: The ordering ID of the archive scene to retrieve.
          schema:
            type: string
            format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Successfully retrieved scene details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveScene'
              examples:
                getArchiveScene200Example:
                  summary: Default getArchiveScene 200 response
                  x-microcks-default: true
                  value:
                    id: scene-a1b2c3d4
                    supplier: supplier-001
                    captureDate: '2025-02-15'
                    gsd: 1.5
                    cloudCover: 12
                    offNadir: 15.2
                    price: 150.00
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/archive/order:
    post:
      operationId: orderArchiveImagery
      summary: Arlula Order Archive Imagery
      description: >-
        Place a single order for archived satellite imagery. The order includes
        a bundle selection, EULA acceptance, and payment information. Returns
        order status as accepted (200) or pending approval (202).
      tags:
        - Archive
      requestBody:
        required: true
        description: Archive imagery order parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveOrderRequest'
            examples:
              orderArchiveImageryRequestExample:
                summary: Default orderArchiveImagery request
                x-microcks-default: true
                value:
                  id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  bundleKey: bundle-basic
                  eula: EULA-001
                  emails:
                    - [email protected]
      responses:
        '200':
          description: Order accepted and processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
              examples:
                orderArchiveImagery200Example:
                  summary: Default orderArchiveImagery 200 response
                  x-microcks-default: true
                  value:
                    orderId: order-500123
                    status: processing
                    createdAt: '2026-04-19T09:00:00Z'
        '202':
          description: Order pending supplier approval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Account not activated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/archive/order/batch:
    post:
      operationId: batchOrderArchiveImagery
      summary: Arlula Batch Order Archive Imagery
      description: >-
        Place multiple archive imagery orders simultaneously in a single API
        call. Shares common settings (emails, webhooks, payment) across all
        orders.
      tags:
        - Archive
      requestBody:
        required: true
        description: Batch archive imagery order parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchArchiveOrderRequest'
            examples:
              batchOrderArchiveImageryRequestExample:
                summary: Default batchOrderArchiveImagery request
                x-microcks-default: true
                value:
                  orders:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      bundleKey: bundle-basic
                      eula: EULA-001
                  emails:
                    - [email protected]
      responses:
        '200':
          description: All orders accepted.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
              examples:
                batchOrderArchiveImagery200Example:
                  summary: Default batchOrderArchiveImagery 200 response
                  x-microcks-default: true
                  value:
                    - orderId: order-500123
                      status: processing
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/tasking/search:
    post:
      operationId: searchTasking
      summary: Arlula Search Tasking Opportunities
      description: >-
        Search for future satellite capture opportunities from Arlula suppliers.
        Specify temporal window, location, resolution, and sensor parameters to
        find available capture slots.
      tags:
        - Tasking
      requestBody:
        required: true
        description: Tasking search parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskingSearchRequest'
            examples:
              searchTaskingRequestExample:
                summary: Default searchTasking request
                x-microcks-default: true
                value:
                  start: '2026-05-01'
                  end: '2026-05-31'
                  gsd: 0.5
                  lat: -33.8523
                  long: 151.2108
                  cloud: 20
      responses:
        '200':
          description: Successfully retrieved tasking opportunities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaskingOpportunity'
              examples:
                searchTasking200Example:
                  summary: Default searchTasking 200 response
                  x-microcks-default: true
                  value:
                    - id: opp-a1b2c3d4
                      supplier: supplier-001
                      captureStart: '2026-05-10T10:00:00Z'
                      captureEnd: '2026-05-10T10:05:00Z'
                      gsd: 0.5
                      price: 500.00
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/tasking/get:
    post:
      operationId: getTaskingOpportunity
      summary: Arlula Get Tasking Opportunity Details
      description: >-
        Retrieve details for a previously returned tasking search result from
        a supplier by its ordering ID.
      tags:
        - Tasking
      requestBody:
        required: true
        description: Tasking opportunity retrieval parameters.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The ordering ID of the tasking opportunity.
                  example: opp-a1b2c3d4
            examples:
              getTaskingOpportunityRequestExample:
                summary: Default getTaskingOpportunity request
                x-microcks-default: true
                value:
                  id: opp-a1b2c3d4
      responses:
        '200':
          description: Successfully retrieved tasking opportunity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskingOpportunity'
              examples:
                getTaskingOpportunity200Example:
                  summary: Default getTaskingOpportunity 200 response
                  x-microcks-default: true
                  value:
                    id: opp-a1b2c3d4
                    supplier: supplier-001
                    captureStart: '2026-05-10T10:00:00Z'
                    captureEnd: '2026-05-10T10:05:00Z'
                    gsd: 0.5
                    price: 500.00
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/tasking/order:
    post:
      operationId: orderTaskingCapture
      summary: Arlula Order Tasking Satellite Capture
      description: >-
        Order a future satellite capture from Arlula suppliers. Billed
        immediately upon placement. Non-cancellable once ordered (unlike archive
        orders which may be pending approval).
      tags:
        - Tasking
      requestBody:
        required: true
        description: Tasking order parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskingOrderRequest'
            examples:
              orderTaskingCaptureRequestExample:
                summary: Default orderTaskingCapture request
                x-microcks-default: true
                value:
                  id: opp-a1b2c3d4
                  bundleKey: bundle-standard
                  eula: EULA-001
                  cloud: 20
                  emails:
                    - [email protected]
      responses:
        '200':
          description: Tasking order accepted and scheduled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
              examples:
                orderTaskingCapture200Example:
                  summary: Default orderTaskingCapture 200 response
                  x-microcks-default: true
                  value:
                    orderId: order-500124
                    status: scheduled
                    createdAt: '2026-04-19T09:00:00Z'
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/tasking/order/batch:
    post:
      operationId: batchOrderTaskingCaptures
      summary: Arlula Batch Order Tasking Captures
      description: >-
        Place multiple tasking capture orders simultaneously. All orders are
        billed immediately and are non-cancellable once submitted.
      tags:
        - Tasking
      requestBody:
        required: true
        description: Batch tasking order parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchTaskingOrderRequest'
            examples:
              batchOrderTaskingCapturesRequestExample:
                summary: Default batchOrderTaskingCaptures request
                x-microcks-default: true
                value:
                  orders:
                    - id: opp-a1b2c3d4
                      bundleKey: bundle-standard
                      eula: EULA-001
                  emails:
                    - [email protected]
      responses:
        '200':
          description: All tasking orders accepted.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
              examples:
                batchOrderTaskingCaptures200Example:
                  summary: Default batchOrderTaskingCaptures 200 response
                  x-microcks-default: true
                  value:
                    - orderId: order-500124
                      status: scheduled
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/tasking/cancel:
    delete:
      operationId: cancelTaskingCampaign
      summary: Arlula Cancel Tasking Campaign
      description: >-
        Cancel a pending tasking campaign that is in the pending-approval state.
        Only campaigns that have not yet been approved can be cancelled.
      tags:
        - Tasking
      parameters:
        - name: id
          in: query
          required: true
          description: The UUID of the tasking campaign to cancel.
          schema:
            type: string
            format: uuid
          example: campaign-a1b2c3d4-e5f6-7890
      responses:
        '200':
          description: Campaign successfully cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResponse'
              examples:
                cancelTaskingCampaign200Example:
                  summary: Default cancelTaskingCampaign 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    campaignId: campaign-a1b2c3d4-e5f6-7890
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method not allowed - campaign not in cancellable state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/orders:
    get:
      operationId: listOrders
      summary: Arlula List Orders
      description: >-
        List all pending and completed orders on the account. Supports
        pagination via page and size parameters.
      tags:
        - Orders
      parameters:
        - name: page
          in: query
          required: false
          description: Page index (0-indexed) for pagination.
          schema:
            type: integer
          example: 0
        - name: size
          in: query
          required: false
          description: Number of results per page.
          schema:
            type: integer
          example: 25
      responses:
        '200':
          description: Successfully retrieved list of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersListResponse'
              examples:
                listOrders200Example:
                  summary: Default listOrders 200 response
                  x-microcks-default: true
                  value:
                    orders:
                      - orderId: order-500123
                        status: completed
                        createdAt: '2026-04-15T09:00:00Z'
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/order/{order}:
    get:
      operationId: getOrder
      summary: Arlula Get Order Details
      description: >-
        Retrieve detailed information about a specific order including its
        campaigns and datasets.
      tags:
        - Orders
      parameters:
        - name: order
          in: path
          required: true
          description: UUID of the order to retrieve.
          schema:
            type: string
            format: uuid
          example: order-a1b2c3d4-e5f6-7890
      responses:
        '200':
          description: Successfully retrieved order details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                getOrder200Example:
                  summary: Default getOrder 200 response
                  x-microcks-default: true
                  value:
                    orderId: order-a1b2c3d4-e5f6-7890
                    status: completed
                    createdAt: '2026-04-15T09:00:00Z'
                    campaigns:
                      - campaignId: campaign-001
                        status: completed
        '400':
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/campaigns:
    get:
      operationId: listCampaigns
      summary: Arlula List Campaigns
      description: >-
        List all pending and completed campaigns across all orders. Supports
        pagination.
      tags:
        - Orders
      parameters:
        - name: page
          in: query
          required: false
          description: Page index (0-indexed).
          schema:
            type: integer
          example: 0
        - name: size
          in: query
          required: false
          description: Results per page.
          schema:
            type: integer
          example: 25
      responses:
        '200':
          description: Successfully retrieved campaigns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignsListResponse'
              examples:
                listCampaigns200Example:
                  summary: Default listCampaigns 200 response
                  x-microcks-default: true
                  value:
                    campaigns:
                      - campaignId: campaign-a1b2
                        orderId: order-a1b2c3d4
                        status: completed
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/datasets:
    get:
      operationId: listDatasets
      summary: Arlula List Datasets
      description: >-
        List all pending and completed datasets across all orders. Supports
        pagination.
      tags:
        - Orders
      parameters:
        - name: page
          in: query
          required: false
          description: Page index (0-indexed).
          schema:
            type: integer
          example: 0
        - name: size
          in: query
          required: false
          description: Results per page.
          schema:
            type: integer
          example: 25
      responses:
        '200':
          description: Successfully retrieved datasets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetsListResponse'
              examples:
                listDatasets200Example:
                  summary: Default listDatasets 200 response
                  x-microcks-default: true
                  value:
                    datasets:
                      - datasetId: dataset-a1b2
                        campaignId: campaign-a1b2
                        status: completed
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/dataset/{dataset}:
    get:
      operationId: getDataset
      summary: Arlula Get Dataset Details
      description: >-
        Retrieve a detailed dataset object with its available resources for
        download.
      tags:
        - Orders
      parameters:
        - name: dataset
          in: path
          required: true
          description: UUID of the dataset to retrieve.
          schema:
            type: string
            format: uuid
          example: dataset-a1b2c3d4
      responses:
        '200':
          description: Successfully retrieved dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
              examples:
                getDataset200Example:
                  summary: Default getDataset 200 response
                  x-microcks-default: true
                  value:
                    datasetId: dataset-a1b2c3d4
                    campaignId: campaign-a1b2
                    status: completed
                    resources:
                      - resourceId: resource-001
                        type: GeoTIFF
                        filename: imagery.tif
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/resource/{resource}/data:
    get:
      operationId: downloadResource
      summary: Arlula Download Resource Data
      description: >-
        Download the binary content of a specific resource (imagery file,
        metadata, thumbnail, etc.). Returns the file content as a binary
        stream.
      tags:
        - Orders
      parameters:
        - name: resource
          in: path
          required: true
          description: UUID of the resource to download.
          schema:
            type: string
            format: uuid
          example: resource-a1b2c3d4
      responses:
        '200':
          description: Resource file content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Resource expired and no longer available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using API Key as username and API Secret as
        password. Credentials are obtained from the Arlula dashboard at
        https://dashboard.arlula.com/apis.
  schemas:
    TestResponse:
      title: TestResponse
      description: Response from the API connection test endpoint.
      type: object
      properties:
        success:
          type: boolean
          description: Whether the authentication was successful.
          example: true
        message:
          type: string
          description: Status message.
          example: Authentication successful.
    ArchiveSearchRequest:
      title: ArchiveSearchRequest
      description: Request body for searching the archive imagery catalog.
      type: object
      required:
        - start
        - gsd
      properties:
        start:
          type: string
          format: date
          description: Start date for imagery search (YYYY-MM-DD).
          example: '2025-01-01'
        end:
          type: string
          format: date
          description: End date for imagery search (YYYY-MM-DD).
          example: '2025-03-31'
        gsd:
          type: number
          description: Maximum ground sample distance in meters.
          example: 1.5
        lat:
          type: number
          description: Latitude of the point of interest.
          example: -33.8523
        long:
          type: number
          description: Longitude of the point of interest.
          example: 151.2108
        cloud:
          type: integer
          description: Maximum cloud cover percentage (0-100).
          example: 20
        offNadir:
          type: number
          description: Maximum off-nadir angle in degrees.
          example: 30.0
        suppliers:
          type: array
          description: Filter results to specific supplier keys.
          items:
            type: string
    ArchiveScene:
      title: ArchiveScene
      description: A satellite imagery scene available in the archive.
      type: object
      properties:
        id:
          type: string
          description: Unique ordering ID for the scene.
          example: scene-a1b2c3d4
        supplier:
          type: string
          description: Supplier identifier.
          example: supplier-001
        captureDate:
          type: string
          format: date
          description: Date the imagery was captured.
          example: '2025-02-15'
        gsd:
          type: number
          description: Ground sample distance in meters.
          example: 1.5
        cloudCover:
          type: integer
          description: Cloud cover percentage at time of capture.
          example: 12
        offNadir:
          type: number
          description: Of

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arlula/refs/heads/main/openapi/arlula-openapi.yaml