The fields parameter allows you to control which fields are included in API responses. This is useful for reducing response size, improving performance, and retrieving only the data your integration needs.

Supported Endpoints

Resource	Endpoint	Method	Parameter Location
Notes	Retrieve note	GET	Query parameter
Notes	List notes	GET	Query parameter
Entities	Retrieve entity	GET	Query parameter
Entities	List entities	GET	Query parameter
Entities	Search entities	POST	Request body

How It Works

The fields parameter supports three modes:

Mode	Behavior
Not specified (default)	Returns only fields that have non-empty values
`all`	Returns all configured fields, including those with `null` values
Specific fields	Returns only the requested fields, even if they have `null` values

Usage in GET Requests

For GET endpoints, use the fields query parameter with array syntax.

Default behavior (no parameter)

When fields is not specified, the response includes only fields that have values set.

curl -X GET "https://api.productboard.com/v2/entities/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

Return all fields

Use fields[]=all to include all fields, even those with null values.

curl -X GET "https://api.productboard.com/v2/entities?type=feature&fields[]=all" \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

Return specific fields

Request only the fields you need by listing them individually.

curl -X GET "https://api.productboard.com/v2/entities?type=feature&fields[]=name&fields[]=status&fields[]=owner" \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

You can also include custom fields by their UUID:

curl -X GET "https://api.productboard.com/v2/entities/123e4567-e89b-12d3-a456-426614174000?fields[]=name&fields[]=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

Usage in POST Requests (Search)

For the Search entities endpoint, include fields in the request body.

Default behavior

When fields is omitted, the response includes only fields that have values set.

curl -X POST "https://api.productboard.com/v2/entities/search" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "types": ["feature"],
      "archived": false
    }
  }'

Return all fields

Set fields to "all" to include all fields, even those with null values.

curl -X POST "https://api.productboard.com/v2/entities/search" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "types": ["feature"],
      "fields": "all"
    }
  }'

Return specific fields

Pass an array of field IDs to request only those fields.

curl -X POST "https://api.productboard.com/v2/entities/search" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "types": ["feature"],
      "fields": ["name", "status", "owner"]
    }
  }'

Field Identifiers

Fields are identified by their id value from the configuration endpoint.

Default fields

Standard fields use descriptive names:

name - Entity or note name
description - Description text
status - Status value
owner - Owner assignment
tags - Tags array
content - Note content
timeframe - Timeframe object

Custom fields

Custom fields are identified by their UUID:

550e8400-e29b-41d4-a716-446655440000

Discovering available fields

Use the configuration endpoints to discover all available fields for each entity or note type:

Each field in the configuration response includes an id property that you can use with the fields parameter. See Using Configuration Endpoints for details.

Error Handling

Unknown field IDs

Requesting a field ID that doesn't exist returns a 400 Bad Request error:

{
  "errors": [
    {
      "code": "request.invalid",
      "title": "Request schema invalid",
      "detail": "Unknown field ID in fields parameter."
    }
  ]
}

Invalid combinations

Combining all with specific field IDs is not allowed. Use either all or a list of specific fields, not both.

Best Practices

Request only what you need - Reduce bandwidth and improve response times by requesting only the fields your integration uses
Use all sparingly - Only use fields[]=all when you genuinely need all fields including empty ones
Cache configuration data - Field availability depends on workspace configuration. Cache it to avoid repeated lookups
Handle null values - When requesting specific fields, those fields are always returned, even if their value is null
Verify fields first - Call the configuration endpoint to check which fields are available before requesting them