Skip to main content

GraphQL API

Fleet Control provides a GraphQL API that allows you to interact with the platform programmatically. This API is designed to be flexible, and it can be used to automate tasks, integrate with other systems, and more. This section of the documentation provides an overview of the API, including how to authenticate, make requests, and perform common tasks. The API can be accessed at:

https://api.fleetcontrol.nordcloudapp.com/graphql

Playground​

There is a GraphQL Playground available that you can use to explore the API and test queries and mutations. You can access it by clicking the link or by hovering over your profile picture in the top right corner and selecting API Playground from the dropdown menu.

Documentation Explorer​

Click Show Documentation Explorer in the top left corner to see the available queries and mutations. This will show you all the available operations, including their input and output types, and descriptions.

Next click one of the root types to see the available queries and mutations and explore the API. There is also a search bar that you can use to find specific operations and types.

Performing operations​

To perform an operation, you can write a query or mutation in the left pane and then click the Execute query button to execute it. The result will be displayed in the right pane.

caution

Mutations will modify the state of the system and should be used with caution. Make sure you understand what a mutation does before executing it.

Usage​

To use API outside the Playground, you need to send an HTTP POST request to the API endpoint with a JSON body containing the query or mutation you want to execute. There are two mandatory headers that you need to include in your request:

  • X-Api-Key: The API key that you use to authenticate with the API.
  • X-Customer-Id: The ID of the customer you want to interact with.

For example, to get the onboarding template for AWS, you can use the following curl command:

curl 'https://api.fleetcontrol.nordcloudapp.com/graphql' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <YOUR API KEY HERE>' \
  -H 'X-Customer-Id: <YOUR CUSTOMER ID HERE>' \
  --data '{
    "query": "{ awsOnboardingTemplate }"
  }'

GraphQL queries used to retrieve an entity list are paged. You can use the page variable for pagination or the limit variable to reduce the number of entities returned in each page if there is too much data on a single page. To ensure that all pages are retrieved, the pages field in pageInfo can be referenced. Below is an example of proper pagination in Python.

import requests


def fetch_all_pages(query: str) -> list[dict]:
    url = "https://api.fleetcontrol.nordcloudapp.com/graphql"
    headers = {
        "Content-Type": "application/json",
        "x-api-key": "YOUR API KEY HERE",
        "x-customer-id": "YOUR CUSTOMER ID HERE"
    }
    
    page = 1
    limit = 100
    all_results = []
    
    while True:
        current_variables = {
            "page": page,
            "limit": limit
        }
        
        response = requests.post(
            url,
            headers=headers,
            json={"query": query, "variables": current_variables}
        )
        response.raise_for_status()
        
        data = response.json()
        if "errors" in data:
            raise Exception(f"GraphQL Error: {data['errors']}")

        plans_data = data["data"]["plans"]
        results = plans_data["result"]
        page_info = plans_data["pageInfo"]
        
        all_results.extend(results)
        
        if page >= page_info["pages"]:
            break
        page += 1
        
    return all_results
    
    
plans_query = """
query getPlans($page: Int, $limit: Int) {
    plans(page: $page, limit: $limit) {
        result {
            id
        }
        pageInfo {
            count
            pages
        }
    }
}
"""

try:
    all_plans = fetch_all_pages(plans_query)
    print(f"Total plans fetched: {len(all_plans)}")
except Exception as e:
    print(f"Error: {str(e)}")

Example queries​

info

Remember that GraphQL queries can only return the fields you need, so consider adjusting (by removing fields) queries below to avoid retrieving a lot of unnecessary data.

Here are some example queries that you can use to get started with the API:

Resource groups query​

query getResourceGroups {
  groups(page: 1, limit: 100){
    result {
      id
      name
      description
      metadata {
        key
        value
      }
      changeDetails {
        createdAt
        createdBy
        updatedAt
        updatedBy
      }
      resourceSelectors {
        id
        order
        resource {
          id
        }
        tagsExpression
        dynamicResources {
          id
        }
      }
      totalNumberOfResources
    }
    pageInfo {
      count
      pages
    }
  }
}

Fields description

  • id - Unique identifier of the resource group
  • name - Name of the resource group
  • description - Optional description of the resource group
  • changeDetails - Details about the changes made to the resource group
    • createdAt - The timestamp when the entity was created
    • createdBy - The identifier of the user or system that created the entity
    • updatedAt - The timestamp when the entity was last updated
    • updatedBy - The identifier of the user or system that last updated the entity
  • metadata - Custom metadata list provided by user as key-value pairs
    • key - The key for this key-value pair
    • value - The value for this key-value pair
  • resourceSelectors - List of resource selectors that define which resources belong to this resource group
    • id - Unique identifier of the resource selector
    • order - Order of the selector in the group
    • resource - Single resource associated with the selector (not empty if resource is selected manually)
      • id - Unique identifier of the resource
    • tagsExpression - Expression for matching resources by tags
    • dynamicResources - List of resources matched by the tags expression
      • id - Unique identifier of the resource
    • totalNumberOfResources - Total count of resources that match the resource group's resource selectors

Plans query​

query getPlans {
  plans(page: 1, limit: 100) {
    result {
      id
      name
      description
      enabled
      scheduleOption
      scheduleCron
      scheduleTimezone
      scheduleExecutionDates
      scheduleOffset
      changeDetails {
        createdAt
        createdBy
        updatedAt
        updatedBy
      }
      metadata {
        key
        value
      }
      planActions {
        id
        name
        order
        windowDuration
        skipWindow
        executionPolicy
        inputParameters {
          key
          value
        }
        resourceGroups {
          id
        }
        action {
          ... on SystemAction {
            id
            name
            description
            version
            changeDetails {
              createdAt
              createdBy
              updatedAt
              updatedBy
            }
            scope
          }
          ... on Action {
            id
            name
            description
            type
            scope
            synchronous
            changeDetails {
              createdAt
              createdBy
              updatedAt
              updatedBy
            }
          }
        }
        runInSequence
      }
      planActionBatches {
        id
        name
        order
        windowDuration
        skipWindow
        executionPolicy
        batchActions {
          id
          action {
            ... on SystemAction {
              id
              name
              description
              version
              changeDetails {
                createdAt
                createdBy
                updatedAt
                updatedBy
              }
              scope
            }
            ... on Action {
              id
              name
              description
              type
              scope
              synchronous
              changeDetails {
                createdAt
                createdBy
                updatedAt
                updatedBy
              }
            }
          }
          resourceGroups {
            id
          }
        }
      }
    }
    pageInfo {
      count
      pages
    }
  }
}
Fields description
  • id - Unique identifier of the plan
  • name - Name of the plan
  • description - Optional description of the plan's purpose
  • enabled - Indicates if the plan is enabled for execution (new events will be generated or not)
  • scheduleOption - Type of schedule
    1. RECURRING - Plan executes on a recurring schedule (scheduleCron field is not empty)
    2. SPECIFIED_DATES - Plan executes on specified dates (scheduleExecutionDates field is not empty)
    3. ON_DEMAND - Plan executes only when manually triggered (both scheduleCron and scheduleExecutionDates fields are empty)
  • scheduleCron - Schedule cron e.g. 5 4 * * *
  • scheduleTimezone - Schedule time zone e.g. UTC
  • scheduleExecutionDates - Fixed dates on which plan execution will be scheduled
  • scheduleOffset - Schedule offset is a delay expressed in minutes that is added to cron-generated dates
  • changeDetails - Details about the changes made to the plan
    • createdAt - The timestamp when the entity was created
    • createdBy - The identifier of the user or system that created the entity
    • updatedAt - The timestamp when the entity was last updated
    • updatedBy - The identifier of the user or system that last updated the entity
  • metadata - Custom metadata list provided by user as key-value pairs
    • key - The key for this key-value pair
    • value - The value for this key-value pair
  • planActions - List of actions configured in the plan
    • id - Unique identifier of the plan action
    • name - Custom name for the plan action, allowing users to identify it easily
    • order - Execution order (unique) within the plan
    • windowDuration - Maximum duration in minutes allowed for this action to complete
    • skipWindow - Controls action’s window skipping behavior
      1. ALWAYS - Skip window and continue to next action
      2. ON_SUCCESS - Skip window only if action was successful
      3. NEVER - Never skip window, always wait for duration, regardless of the status of the action
    • executionPolicy - Determines when the action can proceed
      1. APPROVAL - Requires explicit approval before execution
      2. SUCCESS_OR_APPROVAL - Proceeds on success or requires approval in case of previous action error status
      3. ANYWAY - Proceeds regardless of previous action status
    • inputParameters - Parameters passed to the action during execution. Must match the parameter definitions of the associated System Action or Custom Action. Non-string values are JSON-serialized:
      • key - The key for this key-value pair
      • value - The value for this key-value pair
    • resourceGroups - Resource groups targeted by this action
      • id - Unique identifier of the resource group
    • action - Reference to the underlying CustomAction or SystemAction that will be executed
      • id - Unique identifier of the action
      • name - Name of the action
      • description - Detailed information about the action's purpose
      • version - Version of action (only for system action)
      • type - Specifies the action category and determines which execution source will be used (only for custom action)
        1. SSM_DOCUMENT - AWS Systems Manager Document
        2. AWS_LAMBDA - AWS Lambda Function
        3. AZURE_FUNCTION - Azure Function
        4. SCRIPT - Script that will be executed directly on resources
        5. WEBHOOK - HTTP webhook that will be called
      • scope - Defines whether the action operates on the plan level or individual resource level
        1. PLAN - Action is executed at plan level without requiring resource context
        2. RESOURCE - Action is executed for each resource in the resource group
      • synchronous - Determines whether the action is executed in a synchronous or asynchronous way
      • changeDetails - Details about the changes made to the action
        • createdAt - The timestamp when the entity was created
        • createdBy - The identifier of the user or system that created the entity
        • updatedAt - The timestamp when the entity was last updated
        • updatedBy - The identifier of the user or system that last updated the entity
    • runInSequence - When true, executes the action sequentially for each resource instead of in parallel.
  • planActionBatches - List of action batches configured in the plan
    • id - Unique identifier of the plan action batch
    • name - Custom name for the plan action batch, allowing users to identify it easily
    • order - Execution order (unique) within the plan
    • windowDuration - Maximum duration in minutes allowed for this action batch to complete
    • skipWindow - Controls action batch’s window skipping behavior
      1. ALWAYS - Skip window and continue to next action batch
      2. ON_SUCCESS - Skip window only if action batch was successful
      3. NEVER - Never skip window, always wait for duration, regardless of the status of the action batch
    • executionPolicy - Determines when the action batch can proceed
      1. APPROVAL - Requires explicit approval before execution
      2. SUCCESS_OR_APPROVAL - Proceeds on success or requires approval in case of previous action batch error status
      3. ANYWAY - Proceeds regardless of previous action batch status
    • batchActions - List of actions that belong to this batch
      • id - Unique identifier of the batch action
      • action - Reference to the underlying CustomAction or SystemAction that will be executed
        • id - Unique identifier of the action
        • name - Name of the action
        • description - Detailed information about the action's purpose
        • version - Version of action (only for system action)
        • type - Specifies the action category and determines which execution source will be used (only for custom action)
          1. SSM_DOCUMENT - AWS Systems Manager Document
          2. AWS_LAMBDA - AWS Lambda Function
          3. AZURE_FUNCTION - Azure Function
          4. SCRIPT - Script that will be executed directly on resources
          5. WEBHOOK - HTTP webhook that will be called
        • scope - Defines whether the action operates on the plan level or individual resource level
          1. PLAN - Action is executed at plan level without requiring resource context
          2. RESOURCE - Action is executed for each resource in the resource group
        • synchronous - Determines whether the action is executed in a synchronous or asynchronous way
        • changeDetails - Details about the changes made to the action
          • createdAt - The timestamp when the entity was created
          • createdBy - The identifier of the user or system that created the entity
          • updatedAt - The timestamp when the entity was last updated
          • updatedBy - The identifier of the user or system that last updated the entity
      • name - Custom name for the batch action, allowing users to identify it easily
      • order - Execution order of the action in the batch
      • inputParameters - Parameters passed to the action during execution. Must match the parameter definitions of the associated System Action or Custom Action. Non-string values are JSON-serialized:
        • key - The key for this key-value pair
        • value - The value for this key-value pair
      • resourceGroups - Resource groups targeted by this batch action
        • id - Unique identifier of the resource group