openapi: 3.0.3
info:
  title: Arlula Archive Tasking 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: Tasking
  description: Schedule future satellite captures
paths:
  /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.0
        '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.0
        '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:
                  - analyst@example.com
      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:
                  - analyst@example.com
      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
components:
  schemas:
    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'
    TaskingOpportunity:
      title: TaskingOpportunity
      description: A future satellite capture opportunity.
      type: object
      properties:
        id:
          type: string
          description: Ordering ID for this tasking opportunity.
          example: opp-a1b2c3d4
        supplier:
          type: string
          description: Supplier identifier.
          example: supplier-001
        captureStart:
          type: string
          format: date-time
          description: Earliest start time for the capture window.
          example: '2026-05-10T10:00:00Z'
        captureEnd:
          type: string
          format: date-time
          description: Latest end time for the capture window.
          example: '2026-05-10T10:05:00Z'
        gsd:
          type: number
          description: Expected ground sample distance in meters.
          example: 0.5
        price:
          type: number
          description: Price for this tasking opportunity.
          example: 500.0
    CancelResponse:
      title: CancelResponse
      description: Response after cancelling a tasking campaign.
      type: object
      properties:
        success:
          type: boolean
          description: Whether the cancellation was successful.
          example: true
        campaignId:
          type: string
          description: ID of the cancelled campaign.
          example: campaign-a1b2c3d4
    TaskingOrderRequest:
      title: TaskingOrderRequest
      description: Request body for ordering a future satellite capture.
      type: object
      required:
      - id
      - bundleKey
      - eula
      properties:
        id:
          type: string
          description: Ordering ID of the tasking opportunity.
          example: opp-a1b2c3d4
        bundleKey:
          type: string
          description: Bundle key for this order.
          example: bundle-standard
        eula:
          type: string
          description: EULA identifier.
          example: EULA-001
        cloud:
          type: integer
          description: Maximum acceptable cloud cover percentage.
          example: 20
        priorityKey:
          type: string
          description: Priority level for the capture.
          example: standard
        emails:
          type: array
          description: Email notifications for order completion.
          items:
            type: string
        webhooks:
          type: array
          description: Webhook URLs for status notifications.
          items:
            type: string
        coupon:
          type: string
          description: Optional coupon code.
    TaskingSearchRequest:
      title: TaskingSearchRequest
      description: Request body for searching future satellite capture opportunities.
      type: object
      required:
      - start
      - end
      properties:
        start:
          type: string
          format: date-time
          description: Start of the search window.
          example: '2026-05-01T00:00:00Z'
        end:
          type: string
          format: date-time
          description: End of the search window.
          example: '2026-05-31T00:00:00Z'
        gsd:
          type: number
          description: Maximum ground sample distance in meters.
          example: 0.5
        lat:
          type: number
          description: Latitude of the area of interest.
          example: -33.8523
        long:
          type: number
          description: Longitude of the area of interest.
          example: 151.2108
        cloud:
          type: integer
          description: Maximum acceptable cloud cover percentage.
          example: 20
        offNadir:
          type: number
          description: Maximum off-nadir angle in degrees.
          example: 30.0
        suppliers:
          type: array
          description: Filter to specific suppliers.
          items:
            type: string
        platformTypes:
          type: array
          description: Filter by platform type (optical, radar, etc.).
          items:
            type: string
        sensorTypes:
          type: array
          description: Filter by sensor type.
          items:
            type: string
    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
    BatchTaskingOrderRequest:
      title: BatchTaskingOrderRequest
      description: Request body for placing multiple tasking orders simultaneously.
      type: object
      required:
      - orders
      properties:
        orders:
          type: array
          description: List of tasking orders to place.
          items:
            $ref: '#/components/schemas/TaskingOrderRequest'
        emails:
          type: array
          description: Email addresses for all orders in the batch.
          items:
            type: string
  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.