API Overview

Klarity ImageFactory provides a GraphQL API for interacting with the platform programmatically. Whether you are building custom integrations, automating CI/CD pipelines, or developing your own management tools, the API offers full control over your golden image resources.

GraphQL API

The GraphQL API is the same API used by the ImageFactory Web UI. It provides a flexible, efficient way to query and mutate data.

Environment	Endpoint
Production	https://api.imagefactory.nordcloudapp.com/graphql

Key benefits:

• Retrieve only the fields you need in a single request
• Explore the full schema using built-in tools like GraphiQL
• Strong typing with enums, input types, and nullable fields
• Nested resolvers (e.g., fetch a template with its distribution and images in one query)

Authentication

The API supports two methods of authentication:

1. Auth0 Bearer Token: Used for user-based access. Include the token in the Authorization: Bearer <token> header.
2. API Key: Used for programmatic access. Include the secret in the x-api-key: <secret> header.

For more details on managing access, see the API Keys documentation.

Common API Patterns

Pagination

All list queries accept page and limit parameters and return pages (total page count) and count (total result count).

• page: The page number to retrieve (starting from 1).
• limit: The number of items per page (default 10).

query {
  templates(customerId: "cust-123", input: { page: 1, limit: 20 }) {
    results { id name }
    pages
    count
  }
}

Sorting

Results can be sorted using the sort input field with format field,ORDER.

• Supported orders: ASC (ascending) and DESC (descending)

query {
  templates(customerId: "cust-123", input: { sort: { field: "name", order: ASC } }) {
    results { id name }
  }
}

Searching

The API supports search with multiple matching algorithms:

Algorithm	Description
EXACT_MATCH	Case-insensitive exact string match
SUBSTRING_MATCH	Matches if the value is contained within the field
REGEXP_MATCH	Regular expression matching
FUZZY_MATCH	Approximate string matching

query {
  templates(customerId: "cust-123", input: {
    search: { searchValue: "ubuntu", algorithm: SUBSTRING_MATCH }
  }) {
    results { id name }
  }
}

Rate Limiting

The API implements rate limiting to ensure platform stability. If you exceed the allowed number of requests, the API returns HTTP 429 Too Many Requests. Implement exponential backoff in your client applications to handle this gracefully.