API Reference

Features

get

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

Authorizations

Responses

application/json

all ofoptional

Standard response format for successful API calls

application/json

get

HTTPcURLJavaScriptPython

GET /features HTTP/1.1
Host: front.bucket.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

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

get

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.

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Query parameters

contextobjectoptional

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: 255optional

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

new-order-created

Responses

application/json

all ofoptional

Standard response format for successful API calls

application/json

get

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

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

Features evaluated

get

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

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Query parameters

contextobjectoptional

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: 255optional

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

new-order-created

Responses

application/json

all ofoptional

Standard response format for successful API calls

application/json

get

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

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

Features events

post

Use this endpoint to send feature events to Bucket.

Authorizations

publishableKeysecretKey

Body

Represents an event related to feature flag evaluation

actionstring · enumrequiredAvailable options:

keystring · min: 1 · max: 255required

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

new-order-created

targetingVersionnumberoptional

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

evalContextobjectoptional

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

evalRuleResultsboolean[]optional

The results of evaluation for each of the rules

evalMissingFieldsstring[]optional

The fields that were missing in the context for successful evaluation

Responses

application/json

objectoptional

Standard response format for successful API calls

application/json

post

HTTPcURLJavaScriptPython

POST /features/events HTTP/1.1
Host: front.bucket.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 179

[
  {
    "action": "evaluate-is-enabled",
    "key": "text",
    "targetingVersion": 1,
    "evalContext": {
      "user": {},
      "company": {}
    },
    "evalResult": true,
    "evalRuleResults": [
      true
    ],
    "evalMissingFields": [
      "text"
    ]
  }
]

{
  "success": true
}

User

post

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.

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

Represents a user entity with their attributes and metadata

userIdstring · min: 1required

Unique identifier for the user

attributesobjectoptional

Additional attributes of the user

timestampstring · date-timeoptional

Timestamp associated with the user data

Responses

application/json

objectoptional

Standard response format for successful API calls

application/json

post

HTTPcURLJavaScriptPython

POST /user HTTP/1.1
Host: front.bucket.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "userId": "text",
  "attributes": {},
  "timestamp": "2025-04-17T17:10:39.931Z"
}

{
  "success": true
}

Company

post

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.

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

Represents a company entity with its attributes and associated user

userIdstring · min: 1optional

Identifier for the user linked to the company

companyIdstring · min: 1required

Unique identifier for the company

attributesobjectoptional

Additional attributes of the company

timestampstring · date-timeoptional

Timestamp associated with the company data

Responses

application/json

objectoptional

Standard response format for successful API calls

application/json

post

HTTPcURLJavaScriptPython

POST /company HTTP/1.1
Host: front.bucket.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "userId": "text",
  "companyId": "text",
  "attributes": {},
  "timestamp": "2025-04-17T17:10:39.931Z"
}

{
  "success": true
}

Event

post

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

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

Represents a tracking event with associated user, company, and metadata

userIdstring · min: 1required

Identifier for the user initiating the event

eventstring · min: 1required

The name of the generated event

attributesobjectoptional

Additional event-related attributes

companyIdstring · min: 1optional

Identifier for the company linked to the event

timestampstring · date-timeoptional

Timestamp associated with the event

Responses

application/json

objectoptional

Standard response format for successful API calls

application/json

post

HTTPcURLJavaScriptPython

POST /event HTTP/1.1
Host: front.bucket.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "userId": "text",
  "event": "text",
  "attributes": {},
  "companyId": "text",
  "timestamp": "2025-04-17T17:10:39.931Z"
}

{
  "success": true
}

Feedback

post

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

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

Represents user feedback data with associated context and metadata

feedbackIdstring · min: 1optional

Unique identifier for updating existing feedback

userIdstring · min: 1required

Identifier of the user providing feedback

companyIdstring · min: 1optional

Identifier of the company linked to the feedback

promptIdstring · min: 10 · max: 40optional

Identifier of the feedback prompt

featureIdstring · min: 1 · max: 14optional

Identifier of the feature the feedback is related to

keystring · min: 1 · max: 255optional

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

new-order-created

questionstring · min: 1 · max: 256optional

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

promptedQuestionstring · min: 1 · max: 256optional

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

sourcestring · enumoptional

The source of the feedback

Available options:

scorenumber · max: 5optional

The score of the feedback

commentstring · min: 1 · max: 4000optional

The user's input

timestampstring · date-timeoptional

When the feedback was submitted

Responses

application/json

objectoptional

Standard response format for successful API calls

application/json

post

HTTPcURLJavaScriptPython

POST /feedback HTTP/1.1
Host: front.bucket.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 231

{
  "feedbackId": "text",
  "userId": "text",
  "companyId": "text",
  "promptId": "text",
  "featureId": "text",
  "key": "text",
  "question": "text",
  "promptedQuestion": "text",
  "source": "api",
  "score": 1,
  "comment": "text",
  "timestamp": "2025-04-17T17:10:39.931Z"
}

{
  "success": true
}

Bulk

post

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

Authorizations

publishableKeypublishableKeyInQuerysecretKey

Body

A collection of different types of operations to be processed in bulk

itemsall ofoptional

A single item in a bulk operation request that can be of different types

Responses

application/json

objectoptional

Standard response format for successful API calls

application/json

post

HTTPcURLJavaScriptPython

POST /bulk HTTP/1.1
Host: front.bucket.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 88

[
  {
    "type": "user",
    "userId": "text",
    "attributes": {},
    "timestamp": "2025-04-17T17:10:39.931Z"
  }
]

{
  "success": true
}