Brist API Reference

Welcome to the Brist GraphQL API!

Contact

API Support

support@brist.ai

Terms of Service

https://www.brist.ai/terms

API Endpoints
# Production:
https://api.brist.ai/api/query
Headers
# Get your API key on your dashboard at https://app.brist.ai/api_keys.
Authorization: Bearer <YOUR_TOKEN_HERE>

Queries

adAccountAdStats

Description

Get the advertising statistics (clicks, impressions, cost) for a given advertiser on your marketplace.

Response

Returns [AdStat!]

Arguments
Name Description
accountId - Int! The ID of the ad account you want statistics for. This must be an account managed by your marketplace.
range - TimeRange! The date range you want statistics calculated over (day-level resolution). The range is inclusive of both endpoints.

Example

Query
query adAccountAdStats(
  $accountId: Int!,
  $range: TimeRange!
) {
  adAccountAdStats(
    accountId: $accountId,
    range: $range
  ) {
    day
    clicks
    impressions
    price
  }
}
Variables
{"accountId": 123, "range": TimeRange}
Response
{
  "data": {
    "adAccountAdStats": [
      {
        "day": "10:15:30Z",
        "clicks": 123,
        "impressions": 123,
        "price": 123
      }
    ]
  }
}

adAccounts

Description

adAccounts

Response

Returns [AdAccount!]

Arguments
Name Description
limit - Int!
offset - Int!

Example

Query
query adAccounts(
  $limit: Int!,
  $offset: Int!
) {
  adAccounts(
    limit: $limit,
    offset: $offset
  ) {
    id
    name
    accountType
    createdAt
  }
}
Variables
{"limit": 123, "offset": 987}
Response
{
  "data": {
    "adAccounts": [
      {
        "id": 987,
        "name": "xyz789",
        "accountType": "BRIST_MANAGED_ACCOUNT_TYPE",
        "createdAt": "10:15:30Z"
      }
    ]
  }
}

adUnitAdStats

Description

Get the advertising statistics (clicks, impressions, cost) for a specific ad unit.

Response

Returns [AdStat!]

Arguments
Name Description
adUnitId - Int! The ID of the ad unit you want statistics for. This must be an unit that is managed by an account under your marketplace.
range - TimeRange! The date range you want statistics calculated over (day-level resolution). The range is inclusive of both endpoints.

Example

Query
query adUnitAdStats(
  $adUnitId: Int!,
  $range: TimeRange!
) {
  adUnitAdStats(
    adUnitId: $adUnitId,
    range: $range
  ) {
    day
    clicks
    impressions
    price
  }
}
Variables
{"adUnitId": 987, "range": TimeRange}
Response
{
  "data": {
    "adUnitAdStats": [
      {
        "day": "10:15:30Z",
        "clicks": 123,
        "impressions": 123,
        "price": 123
      }
    ]
  }
}

marketplaceAdStats

Description

Get the advertising statistics (clicks, impressions, cost) across all advertisers on your marketplace.

Response

Returns [AdStat!]

Arguments
Name Description
range - TimeRange! The date range you want statistics calculated over (day-level resolution). The range is inclusive of both endpoints.

Example

Query
query marketplaceAdStats($range: TimeRange!) {
  marketplaceAdStats(range: $range) {
    day
    clicks
    impressions
    price
  }
}
Variables
{"range": TimeRange}
Response
{
  "data": {
    "marketplaceAdStats": [
      {
        "day": "10:15:30Z",
        "clicks": 123,
        "impressions": 123,
        "price": 123
      }
    ]
  }
}

Mutations

createAutobiddingSearchAdUnit

Description

Creates a search unit that uses autobidding (a fixed monthly budget, with optional daily maximums), in order to display ads

Response

Returns an AdUnit!

Arguments
Name Description
input - CreateAutobiddingSearchAdUnitInput!

Example

Query
mutation createAutobiddingSearchAdUnit($input: CreateAutobiddingSearchAdUnitInput!) {
  createAutobiddingSearchAdUnit(input: $input) {
    id
    name
    productIds
    monthlyBudgetCents
    unitType
    unitData {
      ... on FixedBidSearchUnitData {
        ...FixedBidSearchUnitDataFragment
      }
      ... on AutobiddingSearchUnitData {
        ...AutobiddingSearchUnitDataFragment
      }
    }
  }
}
Variables
{"input": CreateAutobiddingSearchAdUnitInput}
Response
{
  "data": {
    "createAutobiddingSearchAdUnit": {
      "id": 123,
      "name": "xyz789",
      "productIds": ["xyz789"],
      "monthlyBudgetCents": 123,
      "unitType": "AUTOBIDDING_SEARCH_UNIT",
      "unitData": FixedBidSearchUnitData
    }
  }
}

createFixedBidSearchAdUnit

Description

Creates a search unit that pays a fixed price for all ad space.

Response

Returns an AdUnit!

Arguments
Name Description
input - CreateFixedSearchAdUnitInput!

Example

Query
mutation createFixedBidSearchAdUnit($input: CreateFixedSearchAdUnitInput!) {
  createFixedBidSearchAdUnit(input: $input) {
    id
    name
    productIds
    monthlyBudgetCents
    unitType
    unitData {
      ... on FixedBidSearchUnitData {
        ...FixedBidSearchUnitDataFragment
      }
      ... on AutobiddingSearchUnitData {
        ...AutobiddingSearchUnitDataFragment
      }
    }
  }
}
Variables
{"input": CreateFixedSearchAdUnitInput}
Response
{
  "data": {
    "createFixedBidSearchAdUnit": {
      "id": 123,
      "name": "xyz789",
      "productIds": ["abc123"],
      "monthlyBudgetCents": 123,
      "unitType": "AUTOBIDDING_SEARCH_UNIT",
      "unitData": FixedBidSearchUnitData
    }
  }
}

createSelfManagedAdAccount

Description

Creates an ad account that has billing managed by you.

Response

Returns an AdAccount!

Arguments
Name Description
input - SelfManagedAdAccountInput!

Example

Query
mutation createSelfManagedAdAccount($input: SelfManagedAdAccountInput!) {
  createSelfManagedAdAccount(input: $input) {
    id
    name
    accountType
    createdAt
  }
}
Variables
{"input": SelfManagedAdAccountInput}
Response
{
  "data": {
    "createSelfManagedAdAccount": {
      "id": 123,
      "name": "abc123",
      "accountType": "BRIST_MANAGED_ACCOUNT_TYPE",
      "createdAt": "10:15:30Z"
    }
  }
}

recordAdClick

Description

Records a click on an ad that was created from an auction.

Response

Returns an AdData!

Arguments
Name Description
input - AdClickEventInput!

Example

Query
mutation recordAdClick($input: AdClickEventInput!) {
  recordAdClick(input: $input) {
    time
    auction {
      ...AuctionFragment
    }
    productId
    marketplaceUserId
    dataType
  }
}
Variables
{"input": AdClickEventInput}
Response
{
  "data": {
    "recordAdClick": {
      "time": "10:15:30Z",
      "auction": Auction,
      "productId": "xyz789",
      "marketplaceUserId": "xyz789",
      "dataType": "IMPRESSION_DATA_TYPE"
    }
  }
}

recordAdImpressions

Description

Records an impression on an ad that was created from an auction.

Response

Returns [AdData!]

Arguments
Name Description
input - AdImpressionsEventInput!

Example

Query
mutation recordAdImpressions($input: AdImpressionsEventInput!) {
  recordAdImpressions(input: $input) {
    time
    auction {
      ...AuctionFragment
    }
    productId
    marketplaceUserId
    dataType
  }
}
Variables
{"input": AdImpressionsEventInput}
Response
{
  "data": {
    "recordAdImpressions": [
      {
        "time": "10:15:30Z",
        "auction": Auction,
        "productId": "abc123",
        "marketplaceUserId": "xyz789",
        "dataType": "IMPRESSION_DATA_TYPE"
      }
    ]
  }
}

recordExternalProductClick

Description

Records a click on a product that was shown organically. The data collected will help refine ad targeting.

Response

Returns an ExternalData!

Arguments
Name Description
input - ProductClickInput!

Example

Query
mutation recordExternalProductClick($input: ProductClickInput!) {
  recordExternalProductClick(input: $input) {
    time
    productId
    marketplaceUserId
    dataType
  }
}
Variables
{"input": ProductClickInput}
Response
{
  "data": {
    "recordExternalProductClick": {
      "time": "10:15:30Z",
      "productId": "xyz789",
      "marketplaceUserId": "abc123",
      "dataType": "EXTERNAL_CLICK_DATA_TYPE"
    }
  }
}

runSearchAuction

Description

Runs a search ad auction given a set of candidates.

Response

Returns an Auction!

Arguments
Name Description
input - AuctionInput!

Example

Query
mutation runSearchAuction($input: AuctionInput!) {
  runSearchAuction(input: $input) {
    id
    adSlots
    candidates {
      ...AuctionCandidateFragment
    }
    marketplaceUserId
    auctionWinners {
      ...AuctionWinnerFragment
    }
  }
}
Variables
{"input": AuctionInput}
Response
{
  "data": {
    "runSearchAuction": {
      "id": 123,
      "adSlots": 987,
      "candidates": [AuctionCandidate],
      "marketplaceUserId": "xyz789",
      "auctionWinners": [AuctionWinner]
    }
  }
}

Types

AdAccount

Fields
Field Name Description
id - Int!
name - String!
accountType - AdAccountType!
createdAt - Time!
Example
{
  "id": 987,
  "name": "abc123",
  "accountType": "BRIST_MANAGED_ACCOUNT_TYPE",
  "createdAt": "10:15:30Z"
}

AdAccountType

Values
Enum Value Description

BRIST_MANAGED_ACCOUNT_TYPE

SELF_MANAGED_ACCOUNT_TYPE

Example
"BRIST_MANAGED_ACCOUNT_TYPE"

AdClickEventInput

Fields
Input Field Description
time - Time

The time that this event occurred. If left blank this defaults to the current time.

adUnitData - AdUnitDataInput

adUnitData contains the relevant information about the ad unit that was clicked.

Example
{
  "time": "10:15:30Z",
  "adUnitData": AdUnitDataInput
}

AdData

Description

AdData represents an event (click/impression/etc.) associated with an ad. When you record a click, cost per click ads are billed to your ad accounts.

Fields
Field Name Description
time - Time! The time this event occurred
auction - Auction! The auction that this event is associated with
productId - String! The marketplace's identifier of the product that the event is associated with.
marketplaceUserId - String marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user.
dataType - AdDataType! The type of data (click/impression).
Example
{
  "time": "10:15:30Z",
  "auction": Auction,
  "productId": "xyz789",
  "marketplaceUserId": "xyz789",
  "dataType": "IMPRESSION_DATA_TYPE"
}

AdDataType

Values
Enum Value Description

IMPRESSION_DATA_TYPE

Represents an impression of an ad

CLICK_DATA_TYPE

Represents a click of an ad
Example
"IMPRESSION_DATA_TYPE"

AdImpressionsEventInput

Fields
Input Field Description
time - Time

The time that this event occurred. If left blank this defaults to the current time.

impressionData - [AdUnitDataInput]

impressionData contains information about the ad units that were shown to the user.

Example
{
  "time": "10:15:30Z",
  "impressionData": [AdUnitDataInput]
}

AdStat

Description

AdStat represents a day's worth of advertising data.

Fields
Field Name Description
day - Time! A timestamp @ midnight UTC on the day this stat represents.
clicks - Int! The number of clicks on this day
impressions - Int! The number of impressions on this day
price - Int! The price paid for these clicks/impressions, in cents.
Example
{
  "day": "10:15:30Z",
  "clicks": 987,
  "impressions": 987,
  "price": 987
}

AdUnit

Fields
Field Name Description
id - Int!
name - String!
productIds - [String!]
monthlyBudgetCents - Int!
unitType - AdUnitType!
unitData - AdUnitData!
Example
{
  "id": 123,
  "name": "xyz789",
  "productIds": ["xyz789"],
  "monthlyBudgetCents": 987,
  "unitType": "AUTOBIDDING_SEARCH_UNIT",
  "unitData": FixedBidSearchUnitData
}

AdUnitData

Example
FixedBidSearchUnitData

AdUnitDataInput

Fields
Input Field Description
productId - String!

productId is the product that was clicked in the auction.

marketplaceUserId - String

marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user.

auctionId - Int!

auctionId is the unique identifier for the auction that this ad is associated with.

Example
{
  "productId": "abc123",
  "marketplaceUserId": "abc123",
  "auctionId": 123
}

AdUnitType

Values
Enum Value Description

AUTOBIDDING_SEARCH_UNIT

FIXED_BID_SEARCH_UNIT

Example
"AUTOBIDDING_SEARCH_UNIT"

Auction

Fields
Field Name Description
id - Int!
adSlots - Int! adSlots is the number of ad slots to assign to the winner of the auction
candidates - [AuctionCandidate!] candidates is the list of products to enter into the auction.
marketplaceUserId - String marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user.
auctionWinners - [AuctionWinner!] The winners of the auction
Example
{
  "id": 123,
  "adSlots": 987,
  "candidates": [AuctionCandidate],
  "marketplaceUserId": "abc123",
  "auctionWinners": [AuctionWinner]
}

AuctionCandidate

Description

AuctionCandidate represents an entrant into a search auction.

Fields
Field Name Description
productId - String! productId is the product that is a candidate in this auction.
searchScore - Float searchScore is a value between 0 and 1, representing a prior on how relevant the product is to the context of the auction. For example, when running ads, the searchScore can be the score returned by Algolia/Elastic Search.
Example
{
  "productId": "xyz789",
  "searchScore": 987.65
}

AuctionCandidateInput

Fields
Input Field Description
productId - String!

The marketplace's identifier of the product in the auction

searchScore - Float

A score between 0 and 1 given by a search system like Algolia/Elastic Search, representing the relevance of this candidate to the context.

Example
{
  "productId": "xyz789",
  "searchScore": 987.65
}

AuctionInput

Fields
Input Field Description
candidates - [AuctionCandidateInput!]

candidates is a list of auction candidates to use in the auction.

marketplaceUserId - String

marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user.

slots - Int!

slots is the number of winners to pick in the auction.

Example
{
  "candidates": [AuctionCandidateInput],
  "marketplaceUserId": "xyz789",
  "slots": 123
}

AuctionWinner

Description

AuctionWinner represents a winner of a search auction.

Fields
Field Name Description
productId - String! productId is the product that won this auction.
adUnitId - Int! adUnitId is the ad unit that won the auction.
priceCents - Int! The price, in cents that the winner will pay if a target action (click, etc.) is recorded.
Example
{
  "productId": "xyz789",
  "adUnitId": 987,
  "priceCents": 987
}

AutobiddingSearchUnitData

Fields
Field Name Description
dailyLimitCents - Int
Example
{"dailyLimitCents": 123}

Boolean

Description

The Boolean scalar type represents true or false.

Example
true

CreateAdUnitInput

Fields
Input Field Description
name - String!
accountId - Int!
productIds - [String!]
monthlyBudgetCents - Int!

The maximum that an advertiser is willing to spend per month

Example
{
  "name": "xyz789",
  "accountId": 123,
  "productIds": ["xyz789"],
  "monthlyBudgetCents": 987
}

CreateAutobiddingSearchAdUnitInput

Fields
Input Field Description
adUnitInput - CreateAdUnitInput!

The core inputs to create the ad unit.

dailyBudgetCents - Int

The maximum that an advertiser is willing to spend per day

Example
{
  "adUnitInput": CreateAdUnitInput,
  "dailyBudgetCents": 123
}

CreateFixedSearchAdUnitInput

Fields
Input Field Description
adUnitInput - CreateAdUnitInput!

The core inputs to create the ad unit.

clickBidCents - Int!

The amount that an advertiser is willing to pay per click.

Example
{"adUnitInput": CreateAdUnitInput, "clickBidCents": 987}

ExternalData

Description

ExternalData represents a data point that is used by Brist to improve personalized advertising, but isn't associated with an ad that was shown.

Fields
Field Name Description
time - Time! The time this event occurred.
productId - String! The product that was associated with the event.
marketplaceUserId - String marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user.
dataType - ExternalDataType! The type of event that occured.
Example
{
  "time": "10:15:30Z",
  "productId": "xyz789",
  "marketplaceUserId": "abc123",
  "dataType": "EXTERNAL_CLICK_DATA_TYPE"
}

ExternalDataType

Values
Enum Value Description

EXTERNAL_CLICK_DATA_TYPE

Represents when a user clicks a product

EXTERNAL_PURCHASE_DATA_TYPE

Represents when a user purchases a product
Example
"EXTERNAL_CLICK_DATA_TYPE"

FixedBidSearchUnitData

Fields
Field Name Description
bidCents - Int!
Example
{"bidCents": 987}

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
123.45

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
123

ProductClickInput

Fields
Input Field Description
time - Time

The time that this event occurred. If left blank this defaults to the current time.

productId - String!

productId is the product that was clicked in the auction.

marketplaceUserId - String

marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user.

Example
{
  "time": "10:15:30Z",
  "productId": "abc123",
  "marketplaceUserId": "xyz789"
}

SelfManagedAdAccountInput

Fields
Input Field Description
name - String!
Example
{"name": "xyz789"}

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"xyz789"

Time

Description

Fields of this type will be a ISO string

Example
"10:15:30Z"

TimeRange

Description

Represents range of times, both endpoints are treated as inclusive, given the resolution given by the Query/Mutation (day, minute, second, etc.).

Fields
Input Field Description
start - Time!

The starting point of the range

end - Time

The endpoint of the range. If null, will be set to the current time.

Example
{
  "start": "10:15:30Z",
  "end": "10:15:30Z"
}