Getting Started

This guide walks you through your first call to the Brandmachine GraphQL API.

Prerequisites

Before you begin, you need:

1. A Brandmachine account
2. An API token (see Authentication)
3. A tool to make HTTP requests (cURL, Postman, or code)

The examples below use YOUR_API_TOKEN as a placeholder. Replace it with your token.

Your First Query

Start by asking which team your token belongs to.

Using cURL

curl -X POST https://production.api.brandmachine.shop/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { currentTeam { id teamDomain isPAYG } }"
  }'

Using JavaScript

async function whoAmI() {
  const response = await fetch('https://production.api.brandmachine.shop/graphql', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        query {
          currentTeam {
            id
            teamDomain
            isPAYG
          }
        }
      `,
    }),
  });

  const result = await response.json();

  if (result.errors) {
    console.error('GraphQL Errors:', result.errors);
    return;
  }

  console.log('Team:', result.data.currentTeam.teamDomain);
}

whoAmI();

Expected Response

{
  "data": {
    "currentTeam": {
      "id": "881CB316-F30B-48D6-A928-59CD44421CD8",
      "teamDomain": "your-team",
      "isPAYG": true
    }
  }
}

If you get HTTP status 401 instead, the token is missing or not accepted. See Troubleshooting.

Useful Read Queries

Once authentication works, a few common starting points (see Queries for the full list with arguments and return types):

# List all your library fashion models
query {
  fashionModels {
    id
    name
    gender
  }
}

# List your campaign images
query {
  campaignImages(limit: 10, offset: 0) {
    id
    title
    status
  }
}

# List your Product Studio sessions, most recent first
query {
  getAllProductStudios {
    id
    title
  }
}

# Get the current credit balance and team info
query {
  currentTeam {
    id
    teamDomain
    isPAYG
  }
  creditBalance {
    balanceCents
    currency
  }
}

# Fetch the pay-as-you-go price list
query {
  pricelist {
    label
    tier
    outputUnit
    chargeCents
    currency
  }
}

Each price list entry carries its own label (the name to show) and tier: generation is charged per attempt while creating, release is charged once when an asset is exported. outputUnit says what chargeCents buys one of: an image, a video, or a second of video. Use these fields rather than deriving anything from usageType.

Understanding GraphQL Queries

GraphQL lets you request exactly the fields you need:

query {
  fashionModels {
    id
    name
    gender
    revisions {
      id
      fullPortraitKey
    }
  }
}

Key concepts:

• Operation type: query (read) or mutation (write).
• Fields: you choose which fields to return.
• Nested fields: request related data like revisions within fashionModels.

Mutations

Mutations create, change, or delete data. For example, to mark a campaign image result as a favorite:

mutation {
  toggleCampaignImageResultFavorite(id: "6c2a...your-uuid") {
    id
    favorite
  }
}

See Mutations for the full list. Some mutations only work inside the Brandmachine app and are refused for API tokens; they are marked Not available with API tokens in the reference.

Using Variables

For dynamic queries, use GraphQL variables instead of building the query string yourself:

const query = `
  query GetCampaignImage($id: UUID!) {
    campaignImage(id: $id) {
      id
      title
      status
    }
  }
`;

const variables = { id: '6c2a...your-uuid' };

const response = await fetch('https://production.api.brandmachine.shop/graphql', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query, variables }),
});

Error Handling

Check the HTTP status first, then result.errors before using result.data:

if (response.status === 401) {
  const body = await response.json();
  throw new Error(`Not authenticated: ${body.reason}`);
}

const result = await response.json();

if (result.errors) {
  result.errors.forEach((error) => {
    // Messages look like "Abort.404: Batch not found".
    console.error(`- ${error.message}`);
  });
  return;
}

const data = result.data;

A message starting with Abort.402 means the team's credit balance is too low for a paid generation. Top up in the app before retrying. See Error Handling for the other cases.

Best Practices

Request Only What You Need

GraphQL returns exactly the fields you ask for. Keep payloads small by selecting only the fields you use.

Use Fragments

fragment ModelBasics on FashionModel {
  id
  name
  gender
}

query {
  fashionModels {
    ...ModelBasics
  }
}

Retry on Transient Errors

Retry network failures and HTTP 5xx responses with a delay. Do not retry 401 responses or Abort.4xx errors unchanged: they fail the same way again.

async function fetchWithRetry(query, variables, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://production.api.brandmachine.shop/graphql', {
        method: 'POST',
        headers: {
          Authorization: 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ query, variables }),
      });
      if (response.status >= 500) throw new Error(`Server error ${response.status}`);
      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
    }
  }
}

Next Steps

1. Explore Queries: full reference of read operations
2. Learn Mutations: write operations
3. Review Types: object types in the schema
4. Upload Files: REST upload endpoints

Need Help?

Contact support@brandmachine.shop with the request payload and the response you got back if something doesn't work.