openapi: 3.0.3
info:
  title: Arlula Archive Orders 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: Orders
  description: Manage orders, campaigns, datasets, and resources
paths:
  /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:
  schemas:
    Dataset:
      title: Dataset
      description: A dataset produced from a campaign containing downloadable resources.
      type: object
      properties:
        datasetId:
          type: string
          description: Dataset identifier.
          example: dataset-a1b2c3d4
        campaignId:
          type: string
          description: Parent campaign identifier.
          example: campaign-a1b2
        status:
          type: string
          description: Dataset status.
          example: completed
        resources:
          type: array
          description: Downloadable resources in this dataset.
          items:
            $ref: '#/components/schemas/Resource'
    OrderResponse:
      title: OrderResponse
      description: Response after placing an imagery order.
      type: object
      properties:
        orderId:
          type: string
          description: Unique order identifier.
          example: order-500123
        status:
          type: string
          description: Current order status.
          enum:
          - processing
          - pending-approval
          - scheduled
          - completed
          - failed
          example: processing
        createdAt:
          type: string
          format: date-time
          description: Time the order was created.
          example: '2026-04-19T09:00:00Z'
    Resource:
      title: Resource
      description: A downloadable resource within a dataset.
      type: object
      properties:
        resourceId:
          type: string
          description: Resource identifier.
          example: resource-001
        type:
          type: string
          description: Resource type (GeoTIFF, Preview, Metadata, etc.).
          example: GeoTIFF
        filename:
          type: string
          description: Original filename.
          example: imagery.tif
    Order:
      title: Order
      description: A detailed order with campaigns and datasets.
      type: object
      properties:
        orderId:
          type: string
          description: Order identifier.
          example: order-a1b2c3d4
        status:
          type: string
          description: Order status.
          example: completed
        createdAt:
          type: string
          format: date-time
          description: Order creation timestamp.
          example: '2026-04-15T09:00:00Z'
        campaigns:
          type: array
          description: Campaigns within this order.
          items:
            $ref: '#/components/schemas/Campaign'
    OrdersListResponse:
      title: OrdersListResponse
      description: Paginated list of orders.
      type: object
      properties:
        orders:
          type: array
          description: List of orders.
          items:
            $ref: '#/components/schemas/OrderResponse'
    DatasetsListResponse:
      title: DatasetsListResponse
      description: Paginated list of datasets.
      type: object
      properties:
        datasets:
          type: array
          description: List of datasets.
          items:
            $ref: '#/components/schemas/Dataset'
    CampaignsListResponse:
      title: CampaignsListResponse
      description: Paginated list of campaigns.
      type: object
      properties:
        campaigns:
          type: array
          description: List of campaigns.
          items:
            $ref: '#/components/schemas/Campaign'
    ErrorResponse:
      title: ErrorResponse
      description: Error response from the API.
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code.
          example: 400
        message:
          type: string
          description: Error message.
          example: Bad Request - invalid parameters
    Campaign:
      title: Campaign
      description: A capture campaign within an order.
      type: object
      properties:
        campaignId:
          type: string
          description: Campaign identifier.
          example: campaign-001
        orderId:
          type: string
          description: Parent order identifier.
          example: order-a1b2c3d4
        status:
          type: string
          description: Campaign status.
          example: completed
  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.