API Reference

The Brandmachine GraphQL API gives you programmatic access to the same data you work with in the app: Product Studio sessions, campaigns and campaign images, group shots, batches, fashion models, shooting locations, wardrobe items, the Designer (collections, designs, revisions, size charts), the Media Planner, brand assets, and billing. File uploads go through a set of REST endpoints next to the GraphQL endpoint.

Getting Started

New to the API? Start here:

  1. Authentication: generate an API token and authenticate requests
  2. Getting Started Guide: make your first API call
  3. Exporting Released Images: pick up released images automatically, for a DAM, PIM or shop
  4. Queries: explore the read operations
  5. Mutations: create, change and delete data

API Endpoint

All GraphQL requests go to:

https://production.api.brandmachine.shop/graphql

File uploads use REST endpoints on the same host (for example https://production.api.brandmachine.shop/api/product-studios/:studioId/inputs/upload). See File Uploads for the full list.

GraphQL Resources

Core Operations

Type Definitions

  • Types: object types and their fields
  • Input Types: input objects that operations take as arguments
  • Enums: enumeration types
  • Scalars: custom scalars (Date, UUID)

These pages are generated from the schema. Every type name in a signature links to its definition.

Additional Resources

  • File Uploads: REST endpoints for product images, batch images and looks sheets, wardrobe images, brand assets, fashion model uploads, Designer resources, patterns, size chart imports, and edited images

Operations Not Available With API Tokens

A small set of operations only works from inside the Brandmachine app and is refused for API token callers. These are mainly the operations that start paid generations, release results, or move money. They are marked Not available with API tokens in the Queries and Mutations reference. Authentication has the full list.

Error Handling

GraphQL errors

Errors raised while an operation runs come back with HTTP status 200 and an errors array. The HTTP status of the underlying failure is part of the message, in the form Abort.<status>: <reason>:

{
  "errors": [
    {
      "message": "Abort.404: Batch not found",
      "locations": [{ "line": 1, "column": 3 }],
      "path": ["batch"]
    }
  ]
}

The API does not set extensions.code on errors, so read the status from the start of the message. Common cases:

  • Abort.400: invalid input, for example a value outside the allowed range or a combination of arguments the operation does not accept
  • Abort.402: Top up credits to continue.: the operation would start a paid generation and your team's credit balance is too low (see Billing & Credits)
  • Abort.403: the operation is not allowed for this caller, for example an operation that is not available with API tokens
  • Abort.404: the requested record was not found for your team

A request that fails GraphQL validation (an unknown field, a wrong argument type) also returns HTTP status 200 and an errors array. Its message is the validation message, without the Abort prefix.

Authentication errors

Authentication is checked before the GraphQL request runs. A missing, invalid or revoked token returns HTTP status 401 with a plain JSON body instead of a GraphQL response:

{
  "error": true,
  "reason": "Invalid API token"
}

Authentication lists the possible reasons.

Billing-Related Queries

Brandmachine runs on pay-as-you-go credits. These queries are useful for billing integrations, and all of them work with an API token:

  • currentTeam: your team's identity and whether it is billed pay-as-you-go (isPAYG)
  • creditBalance: current balance in cents
  • creditBalanceDigest: a timestamp that changes whenever the balance changes; poll it and refetch creditBalance when it moves
  • billingLedger: paginated transaction history, newest first
  • billingCostSummary: aggregated costs over a date range
  • pricelist: the current price list, with a label and tier for each charge

Topping up credits (createTopUpCheckoutSession, createShopifyTopUpCharge, createTopUpIntent) and opening the billing portal (createBillingPortalSession) are not available with API tokens. Top up in the app instead.

Support

Need help with the API? Email support@brandmachine.shop with the request you sent and the response you got back.