API Reference

Features

Use this endpoint to get the list of all features with their targeting rules.

GEThttps://front.bucket.co/features

Authorization

secretKey

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

featuresarray of FeatureWithTargeting (object)

Request

JavaScriptCurlPython

const response = await fetch('https://front.bucket.co/features', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200400

{
  "success": true,
  "features": [
    {
      "key": "text",
      "targeting": {
        "version": 0,
        "rules": []
      }
    }
  ]
}

Rules schema

Attribute	Type	Description
filter	Filter	Object containing filtering rules which will evaluate against context object. Filter can be an instance of 5 different filter types described below.

Filter Schema

Group

Attribute	Type	Desription
type	group	Filter group will evaluate by applying a logical operation to the array of filters provided
filters	Filter[]	Array of filters
operator	enum(and, or)	Logical operation

Negation

Attribute	Type	Desription
type	negation	Negation filter is used to negate the evaluation result of the underlying filters.
filter	Filter	Filter object to be negated

Context

Attribute	Type	Desription
type	context
field	string	Refers to a field of the context object. Example: company.tier
values	string[]	Array of values which will be compared with the value of the context field. Operators SET, NOT_SET, IS_TRUE, IS_FALSE require 0 values, ANY_OF and NOT_ANY_OF support multiple values. All the other operators require exactly one value.
operator	enum(IS,IS_NOT,ANY_OF,NOT_ANY_OF,CONTAINS,NOT_CONTAINS","GT" ,LT,AFTER,BEFORE,SET,NOT_SET,IS_TRUE,IS_FALSE)	Operator for comparison of the context field with provided values.

Rollout Percentage

Attribute	Type	Desription
type	rolloutPercentage	Rollout percentage filter is used for gradual rollouts. It evaluates to true or false proportionally based on the rollout threshold provided. Bucket evaluates the filter by calculating a numeric hash from the rollout attribute. Contexts of which hash is under the threshold provided will evaluate to true.
partialRolloutAttribute	company.id	Currently only "company.id" is supported.
partialRolloutThreshold	number	Number from 0 to 10000 where 0 means no one will have access and 10000 means everyone will have access.

Constant

Attribute	Type	Desription
type	constant	Filter constant will evaluate to the value provided. This is expected when the feature is enabled either for everyone or no one.
value	boolean	Value to which the filter should evaluate

Features enabled

Use this endpoint to get the list of enabled features for the user. The response will contain the list of features that are enabled for the user.

GEThttps://front.bucket.co/features/enabled

Authorization

publishableKeypublishableKeyInQuerysecretKey

Query parameters

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

features*FeaturesMap (object)

remoteContextUsed*boolean

Indicates if the remote context was used

Request

JavaScriptPythonCurl

function flattenObject(obj, prefix = '') {
  return Object.keys(obj).reduce((acc, key) => {
    const value = obj[key];
    const newKey = prefix ? `${prefix}.${encodeURIComponent(key)}` : encodeURIComponent(key);

    if (typeof value === 'object' && value !== null) {
      Object.assign(acc, flattenObject(value, newKey));
    } else {
      acc[newKey] = encodeURIComponent(value);
    }

    return acc;
  }, {});
}

function encodeQueryParams(deepObject) {
  const flattened = flattenObject(deepObject);
  return Object.keys(flattened)
    .map(key => `${key}=${flattened[key]}`)
    .join('&');
}

const params = {
  context: {
    user: {
      id: 'u2956',
      role: 'developer',
    },
    company: {
      id: 'c123',
      name: 'Example Inc',
      country: 'US',
    },
  },
};

// Perform the GET request using fetch
const res = await fetch(`https://front.bucket.co/features/enabled?${encodeQueryParams(params)}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer <your_public_key>`,
  },
});
const data = await res.json();
console.log(data);

Response

200400

{
  "success": true,
  "remoteContextUsed": false
}

Features evaluated

Use this endpoint to get the list of all features evaluated for the user.

GEThttps://front.bucket.co/features/evaluated

Authorization

publishableKeypublishableKeyInQuerysecretKey

Query parameters

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

features*FeaturesMap (object)

remoteContextUsed*boolean

Indicates if the remote context was used

Request

JavaScriptPythonCurl

function flattenObject(obj, prefix = '') {
  return Object.keys(obj).reduce((acc, key) => {
    const value = obj[key];
    const newKey = prefix ? `${prefix}.${encodeURIComponent(key)}` : encodeURIComponent(key);

    if (typeof value === 'object' && value !== null) {
      Object.assign(acc, flattenObject(value, newKey));
    } else {
      acc[newKey] = encodeURIComponent(value);
    }

    return acc;
  }, {});
}

function encodeQueryParams(deepObject) {
  const flattened = flattenObject(deepObject);
  return Object.keys(flattened)
    .map(key => `${key}=${flattened[key]}`)
    .join('&');
}

const params = {
  context: {
    user: {
      id: 'u2956',
      role: 'developer',
    },
    company: {
      id: 'c123',
      name: 'Example Inc',
      country: 'US',
    },
  },
};

// Perform the GET request using fetch
const res = await fetch(`https://front.bucket.co/features/evaluated?${encodeQueryParams(params)}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your_public_key>',
  },
});
const data = await res.json();
console.log(data);

Response

200400

{
  "success": true,
  "remoteContextUsed": false
}

Features events

Use this endpoint to send feature events to Bucket.

POSThttps://front.bucket.co/features/events

Authorization

publishableKeysecretKey

Body

application/json

actionenum

evaluatecheck

keyfeatureKey (string)

Feature key - unique identifier of the feature which you can find in app.bucket.co Example:

new-order-created

targetingVersiontargetingVersion (number)

The version of the targeting rules. Every time when targeting rules are updated the version is incremented.

evalContextflagEvaluationContext (object)

Context object has to be flattened and delimited by dots and provided as query parameters. Example:

context.company.id=42&context.user.id=99

evalResultboolean

The result of the evaluation

evalRuleResultsarray of boolean

The results of evaluation for each of the rules

evalMissingFieldsarray of string

The fields that were missing in the context for successful evaluation

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

Request

JavaScriptCurlPython

const response = await fetch('https://front.bucket.co/features/events', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {}
    ]),
});
const data = await response.json();

Response

200400

{
  "success": true
}

User

Use this endpoint when you want to send user attributes to Bucket. If the user does not exist, it will be created. This endpoint is also used whenever you construct bucket client in any of the SDKs.

POSThttps://front.bucket.co/user

Authorization

publishableKeypublishableKeyInQuerysecretKey

Body

application/json

userId*userId (string)

Identifier of the user

attributesattributes

Object consisting of key value pairs Example:

{
  "id": "u25129",
  "domain": "acmeinc.com",
  "plan": "enterprise",
  "monthly_spend": 99,
  "createdAt": "2024-01-01T10:00:00Z"
}

timestamptimestamp (string (date-time))

Number (milliseconds since epoch) or an ISO-8601 datetime string Example:

2021-01-01T13:37:00.000Z

Defaults to current time if not provided

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

Request

JavaScriptCurlPython

const response = await fetch('https://front.bucket.co/user', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "userId": "text"
    }),
});
const data = await response.json();

Response

200400

{
  "success": true
}

Company

Use this endpoint when you want to send company attributes to Bucket. If the company does not exist, it will be created. You can also use this endpoint to assign user to a company by including the user ID. This endpoint is also used whenever you construct bucket client in any of the SDKs.

POSThttps://front.bucket.co/company

Authorization

publishableKeypublishableKeyInQuerysecretKey

Body

application/json

userIduserId (string)

Identifier of the user

companyId*companyId (string)

Identifier of the company

attributesattributes

Object consisting of key value pairs Example:

{
  "id": "u25129",
  "domain": "acmeinc.com",
  "plan": "enterprise",
  "monthly_spend": 99,
  "createdAt": "2024-01-01T10:00:00Z"
}

timestamptimestamp (string (date-time))

Number (milliseconds since epoch) or an ISO-8601 datetime string Example:

2021-01-01T13:37:00.000Z

Defaults to current time if not provided

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

Request

JavaScriptCurlPython

const response = await fetch('https://front.bucket.co/company', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "companyId": "text"
    }),
});
const data = await response.json();

Response

200400

{
  "success": true
}

Event

Use this endpoint when you want to send a tracking events to Bucket.

POSThttps://front.bucket.co/event

Authorization

publishableKeypublishableKeyInQuerysecretKey

Body

application/json

userId*userId (string)

Identifier of the user

event*string

The name of the event

attributesattributes

Object consisting of key value pairs Example:

{
  "id": "u25129",
  "domain": "acmeinc.com",
  "plan": "enterprise",
  "monthly_spend": 99,
  "createdAt": "2024-01-01T10:00:00Z"
}

companyIdcompanyId (string)

Identifier of the company

timestamptimestamp (string (date-time))

Number (milliseconds since epoch) or an ISO-8601 datetime string Example:

2021-01-01T13:37:00.000Z

Defaults to current time if not provided

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

Request

JavaScriptCurlPython

const response = await fetch('https://front.bucket.co/event', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "userId": "text",
      "event": "text"
    }),
});
const data = await response.json();

Response

200400

{
  "success": true
}

Feedback

Use this endpoint when you want to send feedback events to Bucket.

POSThttps://front.bucket.co/feedback

Authorization

publishableKeypublishableKeyInQuerysecretKey

Body

application/json

feedbackIdstring

Use only when updating existing feedback

userId*userId (string)

Identifier of the user

companyIdcompanyId (string)

Identifier of the company

promptIdstring

Identifier of the prompt which initiated the feedback

featureIdstring

Identifier of the feature for which the feedback is given

keyfeatureKey (string)

Feature key - unique identifier of the feature which you can find in app.bucket.co Example:

new-order-created

questionstring

In case the feedback is initiated by a prompt this will be the question which was asked

promptedQuestionstring

In case the feedback is initiated by a prompt this will be the question which was asked

sourceenum

The source of the feedback

apimanualpromptsdkwidget

scorenumber

The score of the feedback

commentstring

The user's input

timestamptimestamp (string (date-time))

Number (milliseconds since epoch) or an ISO-8601 datetime string Example:

2021-01-01T13:37:00.000Z

Defaults to current time if not provided

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

Request

JavaScriptCurlPython

const response = await fetch('https://front.bucket.co/feedback', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "userId": "text"
    }),
});
const data = await response.json();

Response

200400

{
  "success": true
}

Bulk

Use this endpoint when you want to send multiple events to Bucket.

POSThttps://front.bucket.co/bulk

Authorization

publishableKeypublishableKeyInQuerysecretKey

Body

application/json

type*enum

usercompanyeventfeedback

one of

UserCompanyEventFeedbackFeature Event

Response

200400

OK

Body

application/json

success*enum

Indicates if the request was successful

true

Request

JavaScriptCurlPython

const response = await fetch('https://front.bucket.co/bulk', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "type": "user",
        "userId": "text"
      }
    ]),
});
const data = await response.json();

Response

200400

{
  "success": true
}