API Reference

Flux's GraphQL API — authentication, queries, mutations, and type reference.

Overview

Flux exposes a GraphQL API for programmatic access to all platform operations. The API is available at the /api/graphql endpoint and supports queries and mutations.

Authentication

API keys

API keys are the primary method for programmatic access. Each key is scoped to a set of permissions and paired to a specific tenant.

Create API keys in Settings → API Keys in the Flux dashboard. Include the key in the Authorization header:

Authorization: Bearer <your-api-key>

Shopify OAuth

Interactive dashboard sessions use Shopify OAuth. The API validates both app-level and user-level session tokens. App-level tokens are preferred for server-side operations as they don't expire.

Queries

config

Returns the store group configuration for the current tenant.

query {
  config {
    storeGroup {
      name
      stores {
        domain
        classification
      }
    }
  }
}

syncStatus

Returns the current sync status — whether a sync is running and whether one is queued.

Argument	Type	Default	Description
`type`	`SyncType`	—	Filter by sync type (`OBJECTS`, `THEME`, `FILES`)

query {
  syncStatus(type: OBJECTS) {
    current {
      id
      status
      triggeredBy
      triggeredAt
      stats {
        processed
        created
        updated
        warnings
        errors
      }
    }
    queued {
      id
      status
    }
  }
}

SyncStatusResult

Field	Type	Description
`current`	`Sync`	The currently running sync, if any
`queued`	`Sync`	The next queued sync, if any

syncHistory

Returns a paginated list of past syncs.

Argument	Type	Default	Description
`type`	`SyncType`	—	Filter by sync type
`status`	`SyncStatus`	—	Filter by status
`limit`	`Int`	`20`	Number of results
`offset`	`Int`	`0`	Pagination offset

query {
  syncHistory(type: OBJECTS, limit: 10) {
    syncs {
      id
      type
      status
      triggeredBy
      triggeredAt
      startedAt
      completedAt
      stats {
        processed
        created
        updated
        warnings
        errors
      }
      operationsCount
    }
    total
  }
}

Sync

Field	Type	Description
`id`	`ID!`	Unique sync identifier
`type`	`String!`	Sync type (`OBJECTS`, `THEME`, `FILES`)
`status`	`String!`	Current status
`triggeredBy`	`String`	Who or what initiated the sync
`triggeredAt`	`String!`	When the sync was triggered
`startedAt`	`String`	When execution began
`completedAt`	`String`	When execution finished
`error`	`String`	Error message if failed
`stats`	`SyncStats`	Processing statistics
`operationsCount`	`Int!`	Total number of operations

sync

Returns a single sync by ID.

query {
  sync(id: "sync_abc123") {
    id
    status
    stats {
      processed
      created
      updated
    }
  }
}

syncOperations

Returns the individual operations within a sync — each object that was created, updated, or deleted.

Argument	Type	Default	Description
`syncId`	`ID!`	—	The sync to query
`type`	`OperationType`	—	Filter by operation type (`CREATE`, `UPDATE`, `DELETE`)
`limit`	`Int`	`100`	Number of results
`offset`	`Int`	`0`	Pagination offset

query {
  syncOperations(syncId: "sync_abc123", limit: 50) {
    operations {
      id
      type
      objectType
      canonical
      shop
      details
      createdAt
    }
    total
  }
}

listProducts

Lists products from a specific store. Supports configurable field selection and incremental fetching.

Argument	Type	Default	Description
`shop`	`String!`	—	Store domain
`cursor`	`String`	—	Pagination cursor
`limit`	`Int`	`50`	Number of results
`config`	`ProductSyncConfigInput`	—	Field selection config
`updatedSince`	`String`	—	ISO timestamp for incremental fetch

query {
  listProducts(shop: "my-store.myshopify.com", limit: 10) {
    products {
      id
      handle
      title
      status
      vendor
      tags
      variants {
        id
        title
        sku
        price
        inventoryQuantity
        selectedOptions {
          name
          value
        }
      }
      media {
        id
        mediaContentType
        alt
        image {
          url
          width
          height
        }
      }
      metafields {
        namespace
        key
        value
        type
      }
      publications {
        name
        isPublished
      }
    }
    pageInfo {
      hasNextPage
      cursor
    }
  }
}

ProductSyncConfigInput

Controls which fields are included in the response:

Field	Type	Description
`productFields`	`[String!]`	Product-level field groups to include
`syncVariants`	`Boolean`	Whether to include variants
`variantFields`	`[String!]`	Variant-level field groups (when `syncVariants` is true)
`inventoryOptions`	`[String!]`	Inventory fields to include (use with caution — overwrites stock)

listCollections

Lists collections from a specific store.

Argument	Type	Default	Description
`shop`	`String!`	—	Store domain
`cursor`	`String`	—	Pagination cursor
`limit`	`Int`	`50`	Number of results
`includeMetafields`	`Boolean`	`false`	Include metafield data
`updatedSince`	`String`	—	ISO timestamp for incremental fetch

query {
  listCollections(shop: "my-store.myshopify.com", limit: 20) {
    collections {
      id
      handle
      title
      descriptionHtml
      sortOrder
      templateSuffix
    }
    pageInfo {
      hasNextPage
      cursor
    }
  }
}

listPages, listBlogs, listArticles

Lists pages, blogs, or articles from a specific store. All follow the same pattern.

query {
  listPages(shop: "my-store.myshopify.com", limit: 50) {
    pages { id, handle, title, bodyHtml }
    pageInfo { hasNextPage, cursor }
  }

  listBlogs(shop: "my-store.myshopify.com") {
    blogs { id, handle, title }
    pageInfo { hasNextPage, cursor }
  }

  listArticles(shop: "my-store.myshopify.com", blogId: "gid://shopify/Blog/123") {
    articles { id, handle, title, bodyHtml, tags }
    pageInfo { hasNextPage, cursor }
  }
}

listMenus

Lists navigation menus from a specific store.

query {
  listMenus(shop: "my-store.myshopify.com") {
    menus {
      id
      handle
      title
      items {
        title
        url
        items { title, url }
      }
    }
    pageInfo { hasNextPage, cursor }
  }
}

listDiscounts

Lists discounts from a specific store.

Argument	Type	Default	Description
`shop`	`String!`	—	Store domain
`cursor`	`String`	—	Pagination cursor
`limit`	`Int`	`50`	Number of results
`includeMetafields`	`Boolean`	`false`	Include metafield data
`updatedSince`	`String`	—	ISO timestamp for incremental fetch

listMetaobjectDefinitions, listMetaobjects, listMetafieldDefinitions

Lists metaobject definitions, metaobject entries, or metafield definitions from a store.

query {
  listMetaobjectDefinitions(shop: "my-store.myshopify.com") {
    definitions { id, name, type }
    pageInfo { hasNextPage, cursor }
  }

  listMetaobjects(shop: "my-store.myshopify.com", type: "lookbook") {
    metaobjects { id, handle, type, fields { key, value, type } }
    pageInfo { hasNextPage, cursor }
  }

  listMetafieldDefinitions(shop: "my-store.myshopify.com", ownerType: "PRODUCT") {
    definitions { id, name, namespace, key, type }
    pageInfo { hasNextPage, cursor }
  }
}

listFiles

Lists files from the store's asset library.

Argument	Type	Default	Description
`shop`	`String!`	—	Store domain
`cursor`	`String`	—	Pagination cursor
`limit`	`Int`	`50`	Number of results
`updatedSince`	`String`	—	ISO timestamp for incremental fetch

Canonical mapping queries

Look up the mapping between canonical paths and Shopify GIDs.

# Look up canonical path by Shopify GID
query {
  lookupByGid(objectType: PRODUCT, gids: ["gid://shopify/Product/123"]) {
    gid
    canonical
    shop
  }
}

# Look up Shopify GID by canonical path
query {
  lookupByCanonical(objectType: PRODUCT, canonicals: ["classic-leather-bag"]) {
    canonical
    gid
    shop
  }
}

# List all mappings for an object type
query {
  mappings(objectType: PRODUCT, shop: "my-store.myshopify.com", limit: 100) {
    items {
      canonical
      gid
    }
    total
  }
}

release, releaseByPrNumber

Look up a release by ID or by its associated PR number.

query {
  release(id: "rel_abc123") {
    id
    name
    status
    sourceShop
    targetShop
  }
}

query {
  releaseByPrNumber(prNumber: 42) {
    id
    name
    status
  }
}

deployJob

Check the status of an async deployment job.

query {
  deployJob(jobId: "job_abc123") {
    id
    status
    phase
    progress
    error
  }
}

Mutations

startSync

Starts a sync operation.

Argument	Type	Description
`type`	`SyncType!`	Sync type (`OBJECTS`, `THEME`, `FILES`)
`triggeredBy`	`String`	Label for what triggered the sync

mutation {
  startSync(type: OBJECTS, triggeredBy: "api") {
    syncId
    status
    message
    config {
      stores { domain, classification }
      readFromStores
    }
  }
}

createRelease

Creates a new release from a source store to a target store.

Argument	Type	Description
`input`	`CreateReleaseInput!`	Release configuration

mutation {
  createRelease(input: {
    name: "March product update"
    sourceShop: "source-store.myshopify.com"
    targetShop: "production-store.myshopify.com"
  }) {
    success
    releaseId
    error
  }
}

approveRelease

Approves a release for deployment.

mutation {
  approveRelease(releaseId: "rel_abc123", comment: "LGTM") {
    success
    message
    error
  }
}

triggerReleaseDeploy

Triggers deployment of an approved release. Runs the same eligibility checks as the dashboard deploy button.

mutation {
  triggerReleaseDeploy(releaseId: "rel_abc123") {
    success
    message
    error
  }
}

cancelRelease

Cancels a release.

mutation {
  cancelRelease(releaseId: "rel_abc123") {
    success
    message
    error
  }
}

upsertMappings

Creates or updates canonical mappings in batch.

mutation {
  upsertMappings(mappings: [
    {
      objectType: PRODUCT
      canonical: "classic-leather-bag"
      gid: "gid://shopify/Product/123"
      shop: "my-store.myshopify.com"
    }
  ]) {
    canonical
    gid
    shop
  }
}

deleteMappings

Deletes canonical mappings.

mutation {
  deleteMappings(
    objectType: PRODUCT
    canonicals: ["old-product-handle"]
    shop: "my-store.myshopify.com"
  )
}

Returns the number of mappings deleted.

Write mutations

Flux provides write mutations for each object type. These create or update objects in a target store.

Mutation	Description
`writeProduct`	Create or update a product (uses Shopify's `productSet`)
`writeCollection`	Create or update a collection
`writePage`	Create or update a page
`writeBlog`	Create or update a blog
`writeArticle`	Create or update an article
`writeMenu`	Create or update a navigation menu
`writeDiscount`	Create or update a discount
`writeMetaobjectDefinition`	Create or update a metaobject definition
`writeMetaobject`	Create or update a metaobject entry
`writeMetafieldDefinition`	Create or update a metafield definition
`uploadFile`	Upload a file via Shopify's staged upload
`updateFile`	Update file metadata (e.g., alt text)

Each write mutation accepts an input object with the target shop domain and the object data, and returns:

{
  success: Boolean!
  shopifyGid: String    # The created/updated object's GID
  canonical: String!    # The canonical path
  shop: String!         # The target store
  action: String!       # "created" or "updated"
  error: String         # Error message if failed
}

REST endpoints

In addition to GraphQL, Flux provides REST endpoints for specific operations:

Endpoint	Description
`/api/health`	Health check with detailed component status
`/api/heartbeat`	Simple liveness probe
`/api/rate-limits`	Current Shopify API rate limit status
`/api/object-diff`	Compute diff between two snapshots
`/api/object-history`	Sync history for a specific object
`/api/object-revert`	Revert an object to a previous version
`/api/audit-export`	Export audit logs as CSV

MCP integration

Flux includes a Model Context Protocol (MCP) server at /api/mcp, enabling AI assistants to interact with the platform. The MCP server exposes tools for querying sync status, browsing store content, viewing canonical mappings, and inspecting configuration.

Next steps

Learn about permissions and API key scoping
Read about releases and the deployment workflow