API Reference

Features

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

get

/features

Authorizations

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://front.bucket.co/features' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

200

{
  "success": true,
  "features": [
    {
      "key": "text",
      "targeting": {
        "version": 1,
        "rules": [
          "[Circular Reference]"
        ]
      },
      "config": {
        "version": 1,
        "variants": [
          "[Circular Reference]"
        ]
      }
    }
  ]
}

OK

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.

get

/features/enabled

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Query parameters

contextobject

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

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

keystring · min: 1 · max: 255

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

new-order-created

Responses

application/json

application/json

JavaScript

Python

Curl

JavaScript

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);

200

400

200

{
  "success": true,
  "features": {
    "ANY_ADDITIONAL_PROPERTY": {
      "key": "text",
      "targetingVersion": 1,
      "isEnabled": true,
      "config": {
        "version": 1,
        "default": true,
        "payload": null,
        "name": null,
        "ruleEvaluationResults": [
          true
        ],
        "missingContextFields": [
          "text"
        ]
      },
      "ruleEvaluationResults": [
        true
      ],
      "missingContextFields": [
        "text"
      ]
    }
  },
  "remoteContextUsed": true
}

OK

Features evaluated

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

get

/features/evaluated

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Query parameters

contextobject

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

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

keystring · min: 1 · max: 255

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

new-order-created

Responses

application/json

application/json

JavaScript

Python

Curl

JavaScript

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);

200

400

200

{
  "success": true,
  "features": {
    "ANY_ADDITIONAL_PROPERTY": {
      "key": "text",
      "targetingVersion": 1,
      "isEnabled": true,
      "config": {
        "version": 1,
        "default": true,
        "payload": null,
        "name": null,
        "ruleEvaluationResults": [
          true
        ],
        "missingContextFields": [
          "text"
        ]
      },
      "ruleEvaluationResults": [
        true
      ],
      "missingContextFields": [
        "text"
      ]
    }
  },
  "remoteContextUsed": true
}

OK

Features events

Use this endpoint to send feature events to Bucket.

post

/features/events

Authorizations

publishableKeysecretKey

Body

keystring · min: 1 · max: 255required

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

new-order-created

targetingVersionnumber

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

evalContextobject

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

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

evalResultbooleanrequired

The result of the evaluation

actionstring · enumrequired

Options: evaluate, check

evalRuleResultsboolean[]

The results of evaluation for each of the rules

evalMissingFieldsstring[]

The fields that were missing in the context for successful evaluation

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://front.bucket.co/features/events' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[{"key":"text","evalContext":{"user":{},"company":{}},"evalResult":true,"action":"evaluate","evalRuleResults":[null],"evalMissingFields":[null]}]'

200

400

200

{
  "success": true
}

OK

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.

post

/user

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

userIdstring · min: 1required

Unique identifier for the user

attributesattributes

Additional attributes of the user

timestampstring · date-time

Timestamp associated with the user data

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://front.bucket.co/user' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"userId":"text","attributes":{}}'

200

400

200

{
  "success": true
}

OK

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.

post

/company

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

userIdstring · min: 1

Identifier for the user linked to the company

companyIdstring · min: 1required

Unique identifier for the company

attributesattributes

Additional attributes of the company

timestampstring · date-time

Timestamp associated with the company data

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://front.bucket.co/company' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"companyId":"text","attributes":{}}'

200

400

200

{
  "success": true
}

OK

Event

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

post

/event

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

userIdstring · min: 1required

Identifier for the user initiating the event

eventstring · min: 1required

The name of the generated event

attributesattributes

Additional event-related attributes

companyIdstring · min: 1

Identifier for the company linked to the event

timestampstring · date-time

Timestamp associated with the event

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://front.bucket.co/event' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"userId":"text","event":"text","attributes":{}}'

200

400

200

{
  "success": true
}

OK

Feedback

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

post

/feedback

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

feedbackIdstring · min: 1

Unique identifier for updating existing feedback

userIdstring · min: 1required

Identifier of the user providing feedback

companyIdstring · min: 1

Identifier of the company linked to the feedback

promptIdstring · min: 10 · max: 40

Identifier of the feedback prompt

featureIdstring · min: 1 · max: 14

Identifier of the feature the feedback is related to

keystring · min: 1 · max: 255

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

new-order-created

questionstring · min: 1 · max: 256

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

promptedQuestionstring · min: 1 · max: 256

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

scorenumber · max: 5

The score of the feedback

commentstring · min: 1 · max: 4000

The user's input

timestampstring · date-time

When the feedback was submitted

sourcestring · enum

The source of the feedback

Options: api, manual, prompt, sdk, widget

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://front.bucket.co/feedback' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"userId":"text","source":"api"}'

200

400

200

{
  "success": true
}

OK

Bulk

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

post

/bulk

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

typestring · enumrequired

Options: user, company, event, feedback

one of

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://front.bucket.co/bulk' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[{"type":"user","userId":"text","attributes":{}}]'

200

400

200

{
  "success": true
}

OK