Response Field Control

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

How It Works

The fields parameter supports three modes:

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:

• Notes Configuration
• Entities Configuration

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