API Reference

Welcome to the Brandmachine GraphQL API. The API gives you programmatic access to brand assets, fashion models, campaigns, product studios, designer instances, billing, and more. File uploads are handled via a set of REST endpoints alongside 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. Queries: explore available read operations
  4. Mutations: write data (create, update, delete)

API Endpoint

All GraphQL requests go to:

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

File uploads use REST endpoints under the same host (e.g. 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
  • Enums: enumeration types
  • Scalars: custom scalars (Date, UUID)

Additional Resources

  • File Uploads: REST endpoints for product images, fashion model uploads, designer resources, patterns, ZIP imports, and more

Rate Limiting

The API implements rate limiting to ensure fair usage:

  • Standard tier: 100 requests per minute
  • Premium tier: 500 requests per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Error Handling

The API uses standard GraphQL error responses. Errors are returned in the errors array:

{
  "errors": [
    {
      "message": "Not authenticated",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Common error codes:

  • UNAUTHENTICATED: missing or invalid authentication token
  • FORBIDDEN: authenticated but not authorized for this operation
  • BAD_USER_INPUT: invalid input parameters
  • INSUFFICIENT_CREDITS: operation requires credits that exceed your current balance (see Billing & Credits)
  • INTERNAL_SERVER_ERROR: unexpected server error

Billing-Related Queries

Brandmachine runs on pay-as-you-go credits. A few queries and mutations are particularly relevant for billing integrations:

  • currentTeam: your team's identity and billing routing
  • creditBalance: current balance in cents
  • creditBalanceDigest: lightweight polling endpoint
  • billingLedger: paginated transaction history
  • pricelist: public price list
  • createTopUpCheckoutSession: create a Stripe Checkout session (recommended)
  • createBillingPortalSession: open the Stripe Customer Portal
  • createShopifyTopUpCharge: create a one-time Shopify charge for credits

The older createTopUpIntent mutation is deprecated; use createTopUpCheckoutSession instead.

Support

Need help with the API?

  • Email: support@brandmachine.shop
  • Documentation Issues: Report problems or suggest improvements
  • Feature Requests: Let us know what you'd like to see