Why use the configuration endpoint?

The configuration endpoint provides a way to programmatically access and manage the configuration settings of your Productboard workspace. The API provides 2 configuration endpoints:

The configuration endpoint is a critical part of the Productboard API. Productboard provides a flexible data model and the API allows users to interact with this model in a programmatic way.

In a "traditional" API, you might have fixed responses for specific endpoints. For example, a GET /entities?type=feature endpoint might return a list of features with predefined fields like id, name, and status. This allows for a straightforward interaction with the API, but it can be limiting when the underlying data model is flexible and customizable.

In a "configuration-driven" API like Productboard's, the structure of the data returned by the API can change based on the configuration of the workspace. Taking the same example, to interact with the GET /entities?type=feature endpoint, we first have to call the configuration endpoint to understand what fields are available for features in the current workspace. The configuration endpoint will return a list of fields, their types, and other metadata. This allows clients to dynamically adapt to the structure of the data.

The basic structure of the configuration response

The configuration response typically includes the following elements:

type: The type of entity being configured
- For example, for notes configuration, "type": "simple"
- For example, for entities configuration, "type": "feature"
fields: A list of fields available for the entity, including their names, types, constraints, and a list of operations that can be performed on the field

Working with fields

Fields are the building blocks of the configuration endpoint. Each field has a set of properties that define its characteristics and behavior. Here are some common properties you might encounter:

id: A unique identifier for the field
name: The name of the field. This is the name users will see within the Productboard UI.
schema: The data type of the field
constraints: Any constraints that apply to the field, such as whether it is required or whether there are length limits
lifecycle: this determines the operations that can be performed on the field.

Example field definition

Assume we called the configuration endpoint for the feature entity type. In the example below, we can determine:

The id is name
The name is Name
- This is the field name that will be displayed in the Productboard UI
The schema is TextFieldValue
- This indicates that the field is a text field, and can be mapped to a string in your code
The field is required
- This means that when creating or updating a feature, a value for this field must be provided
- You can also reasonably assume that this field will always be present when retrieving a feature
The field has a maxLength constraint of 255 characters
- This can be used for validation when working with this field

"fields": {
  "name": {
    "id": "name",
    "name": "Name",
    "path": "/fields/name",
    "schema": "TextFieldValue",
    "lifecycle": {
      "create": {
        "set": true
      },
      "update": {
        "set": true
      },
      "patch": {
        "set": true
      }
    },
    "constraints": {
      "required": true,
      "maxLength": 255
    },
    "links": {
      "self": null
    }
  }
}

Understanding field lifecycle

The lifecycle property of a field defines the operations that can be performed on that field. The lifecycle object can contain the following properties:

create - Operations allowed when creating a field
update - Operations allowed when updating a field using the simple data.fields approach
patch - Operations allowed when updating a field using JSON Patch arrays via data.patch

The difference between update and patch

Both update and patch are used for modifying existing entities, but they differ in how you structure the request:

Update uses the simpler data.fields approach where you send field updates directly in a fields object:

{
  "data": {
    "fields": {
      "name": "Hello World"
    }
  }
}

Patch uses a JSON Patch-like syntax (inspired by RFC 6902) where you send updates as an array of operations via data.patch:

{
  "data": {
    "patch": [
      { "op": "set", "path": "name", "value": "Hello World" }
    ]
  }
}

The lifecycle configuration tells you which approach is allowed for each field and what operations (set, clear, addItems, removeItems) are supported with each approach. Note that the op values in the patch array correspond directly to the lifecycle operations (set, clear, addItems, removeItems), not the standard JSON Patch operations.

Each of these properties (create, update, patch) can contain a list of operations that are allowed for that field. If the operation is allowed, it will be set to true. The operations are:

set - Allows setting the value of the field
clear - Allows clearing the value of the field
addItems - Allows adding items to an array field
removeItems - Allows removing items from an array field

Example lifecycle definition

Assume we called the configuration endpoint for the feature entity type. In the example below, we can determine that:

When we create, update, or patch a feature, we can set the value of the owner field.
When we update or patch a feature, we can also clear the value of the owner field.

"fields": {
  "owner": {
    "id": "owner",
    "name": "Owner",
    "path": "/fields/owner",
    "schema": "MemberFieldValue",
    "lifecycle": {
      "create": {
        "set": true
      },
      "update": {
        "set": true,
        "clear": true
      },
      "patch": {
        "set": true,
        "clear": true
      }
    },
    "links": {
      "self": null
    }
  }
}

Working with filters

The entity configuration endpoint also provides information about which filters are available for each entity type. Not all entity types support the same filters — for example, status filtering may only be available for types that have a status field, and parent[id] only works for types that have a parent relationship.

The filters array in the configuration response lists all available filter parameters for a given entity type.

Filter properties

Each filter entry contains:

name: The exact query parameter name to use when filtering (e.g., owner[id], status[name])
field: The field ID this filter applies to (when the filter is based on a field)
relationship: The relationship key this filter applies to (when the filter is based on a relationship)
schema: The expected value type and format for the filter value
requiredScopes: Any additional OAuth scopes needed to use this filter (omitted when no extra scopes are required)

Example filter definition

Assume we called the configuration endpoint for the feature entity type. The filters array might include:

"filters": [
  {
    "name": "owner[id]",
    "field": "owner",
    "schema": {
      "type": "string",
      "format": "uuid"
    },
    "requiredScopes": ["members:pii:read"]
  },
  {
    "name": "parent[id]",
    "relationship": "parent",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "status[name]",
    "field": "status",
    "schema": {
      "type": "string"
    }
  }
]

From this example, we can determine:

To filter features by owner, use the query parameter owner[id] with a UUID value, and the members:pii:read scope is required
To filter features by parent, use parent[id] with a UUID value
To filter features by status, use status[name] with a string value

Using filters with list and search endpoints

Filters from the configuration can be used as query parameters on List entities or as keys in the Search entities request body.

For example, if the configuration shows a filter with "name": "status[name]", you can use it like this:

GET request:

GET /v2/entities?type[]=feature&status[name]=in+progress

POST search request:

{
  "data": {
    "type": "feature",
    "status": {
      "name": "in progress"
    }
  }
}

Note: Only AND logic is supported when applying multiple filters. OR, NOT, or nested conditions are not supported.

Combining configuration data with other endpoints

A typical workflow when using the configuration endpoint involves the following steps:

Call the configuration endpoint to retrieve the current configuration settings for the desired entity type (e.g., features, notes, etc.)
Parse the configuration response to understand the available fields, their types, and the operations that can be performed on them
1. It might be useful to build classes or data structures in your code to represent the configuration data. For example, you might create a Field class that encapsulates the properties of a field and provides methods for interacting with it.
Make a request to an endpoint that you have a configuration for. For example, if you have the configuration for features, you might make a request to GET /entities?type=feature to retrieve a list of features.
1. If you're retrieving data, you can validate the response against the data types defined in the configuration.
2. If you're creating, deleting, or updating data, you can ensure that the data you're sending conforms to the constraints and operations defined in the configuration.

Example: Features export

In the Features export recipe, we demonstrate how to use the configuration endpoint to dynamically adapt to the structure of features in a Productboard workspace. The recipe involves:

In the function def fetch_configuration(entity_type), we call the configuration endpoint to retrieve the configuration for features.
In the function def generate_csv(configuration, entities, output_file), we use the configuration data to determine which fields to include in the CSV header row.

The advantage of this approach is that if the configuration of features changes (e.g., new fields are added, existing fields are removed), the export functionality will automatically adapt to these changes without requiring hardcoded field definitions.