{"openapi":"3.1.1","info":{"title":"Entities","description":"Productboard API v2 for reading the aggregated customer score of a product hierarchy entity.","version":"2.0.0","contact":{"name":"Productboard Support","url":"https://support.productboard.com","email":"support@productboard.com"},"license":{"name":"Productboard Proprietary","url":"https://www.productboard.com/"}},"servers":[{"url":"https://api.productboard.com/v2","description":"Production server"}],"security":[{"BearerAuth":[]},{"OAuth2":["entities:read","write:entities","entities:delete"]}],"tags":[{"name":"customer-scores","description":"Operations for reading aggregated customer scores."}],"paths":{"/entities/{id}/score":{"get":{"tags":["customer-scores"],"summary":"Get customer score (Beta)","description":"> 🚧 Beta\n>\n> This endpoint is in **beta**. Its behavior may change, or it may be removed,\n> in a future release without notice. We recommend against relying on it in\n> production integrations.\n\nRetrieves the aggregated customer score for a single product hierarchy\nentity, identified by its UUID. Use this endpoint to see, as a single\nnumber, how important an entity is to your customers based on the\nfeedback attached to it and everything below it in the hierarchy.\n\nThe `id` must be the UUID of a **product hierarchy entity** - a\nproduct, component, feature, or subfeature.\n\n## Key Features\n- Aggregates customer importance ratings on the entity **and all of its\n  descendants** in the product hierarchy.\n- Ratings are weighted by importance level, and anonymous feedback also\n  contributes:\n  - `critical` × 3\n  - `important` × 2\n  - `nice to have` × 1\n  - `unknown` × 1\n  - each anonymous note × 1\n- `not important` ratings do not contribute to the score.\n\n## Important Notes\n- Returns a score of `0` when the entity has no customer importance data.\n- Returns `404` when `id` does not match a product hierarchy entity\n  in your workspace (for example, a company, note, or user ID).\n","operationId":"getCustomerScore","security":[{"BearerAuth":["entities:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"UUID of the product hierarchy entity to score - a product, component,\nfeature, or subfeature.\n","schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"}}],"responses":{"200":{"$ref":"#/components/responses/CustomerScoreResponse"},"400":{"$ref":"#/components/responses/BadRequestResponse"},"401":{"$ref":"#/components/responses/UnauthorizedResponse"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"408":{"$ref":"#/components/responses/RequestTimeoutResponse"},"429":{"$ref":"#/components/responses/TooManyRequestsResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API token authentication. Use your API token as the value of the Authorization header"},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication. Use this for user-authorized access to Productboard API.","flows":{"authorizationCode":{"authorizationUrl":"https://app.productboard.com/oauth/authorize","tokenUrl":"https://app.productboard.com/oauth/token","scopes":{"entities:read":"Read access to entities (features, components, initiatives, etc.)","write:entities":"Write access to create and modify entities","entities:delete":"Delete entities"}}}}},"schemas":{"CustomerScore":{"type":"object","description":"Aggregated customer score for a product hierarchy entity.\n","required":["id","type","fields","links"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID of the scored product hierarchy entity.","example":"123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","const":"customerScore","description":"Resource type identifier.","example":"customerScore"},"fields":{"$ref":"#/components/schemas/CustomerScoreFields"},"links":{"$ref":"#/components/schemas/CustomerScoreLinks"}}},"CustomerScoreFields":{"type":"object","description":"Fields of a customer score resource.","required":["score"],"properties":{"score":{"type":"integer","minimum":0,"description":"The aggregated customer score. Higher values indicate greater\naggregate customer importance. `0` means there is no customer\nimportance data for the entity.\n","example":27}}},"CustomerScoreLinks":{"type":"object","description":"Links for navigating customer score resources.","required":["self"],"properties":{"self":{"type":"string","format":"uri","description":"URL of the customer score resource.","example":"https://api.productboard.com/v2/entities/123e4567-e89b-12d3-a456-426614174000/score"}}},"ErrorSource":{"type":"object","description":"An object containing references to the source of the error. It helps with location of the problematic field or parameter.\n","properties":{"pointer":{"type":"string","description":"JSON Pointer [RFC6901] to the associated entity in the request document.\n","example":"/data/fields/status"},"parameter":{"type":"string","description":"Query parameter causing the error.\nUsed when the error is related to a query parameter rather than request body.\n","example":"pageCursor"}}},"Error":{"type":"object","description":"Individual error object containing the details and context.\n","required":["code","title","detail"],"properties":{"code":{"type":"string","description":"A unique, machine-readable and stable code that identifies this error.\nMust be consistent across all services and provide clear categorization.\nFormat: `category.subcategory.specificError`\n","examples":["auth.accessDenied","resource.notFound"]},"title":{"type":"string","description":"A short, human-readable summary of the problem that doesn't change\nfrom occurrence to occurrence of the problem. Should provide immediate\nunderstanding of the error type.\n","maxLength":255,"example":"Missing required field"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.\nMay include suggestions for resolution but should not expose sensitive information.\n","maxLength":1000,"example":"Field 'status' is required."},"source":{"$ref":"#/components/schemas/ErrorSource"}}},"ErrorResponse":{"type":"object","description":"Standard error response structure.\n","required":["id","errors"],"properties":{"id":{"type":"string","description":"A unique identifier for this specific occurrence of the problem.\nIt carries unique request/response ID which allows client\nand server to reference the exact instance of the error\nin logs or support communication.\n"},"errors":{"type":"array","description":"Array of error objects, multiple errors can be returned.","items":{"$ref":"#/components/schemas/Error"},"minItems":1}}}},"responses":{"CustomerScoreResponse":{"description":"The aggregated customer score for the entity.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CustomerScore"}}},"examples":{"customerScore":{"summary":"Customer score response","value":{"data":{"id":"123e4567-e89b-12d3-a456-426614174000","type":"customerScore","fields":{"score":27},"links":{"self":"https://api.productboard.com/v2/entities/123e4567-e89b-12d3-a456-426614174000/score"}}}}}}}},"BadRequestResponse":{"description":"Bad Request - Invalid input format or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"schemaInvalid":{"summary":"Request does not satisfy schema","value":{"id":"req-1234567890","errors":[{"code":"request.invalid","title":"Request schema invalid","detail":"The request does not satisfy the required schema. Field 'type' is required but was not provided.","source":{"pointer":"/data/type"}}]}},"fieldInvalid":{"summary":"Invalid field value type","value":{"id":"req-1234567891","errors":[{"code":"request.invalid","title":"Request schema invalid","detail":"Field 'fields/name' must be a string with maximum length of 255 characters, but received a number.","source":{"pointer":"/data/fields/name"}}]}},"malformedJson":{"summary":"Malformed JSON syntax","value":{"id":"req-1234567892","errors":[{"code":"request.malformed","title":"Request malformed","detail":"The request body contains invalid JSON syntax. Expected ',' or '}' at line 5, column 12."}]}},"invalidContentType":{"summary":"Invalid content type","value":{"id":"req-1234567893","errors":[{"code":"request.malformed","title":"Request malformed","detail":"The Content-Type header must be 'application/json'. Received 'text/plain'."}]}}}}}},"UnauthorizedResponse":{"description":"Unauthorized - Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missingCredentials":{"summary":"Missing authentication credentials","value":{"id":"req-2234567890","errors":[{"code":"auth.invalid","title":"Invalid authentication","detail":"Authentication credentials are missing."}]}},"invalidToken":{"summary":"Invalid or expired token","value":{"id":"req-2234567891","errors":[{"code":"auth.invalid","title":"Invalid authentication","detail":"The provided authentication credentials are invalid or have expired. Please obtain new credentials and try again."}]}},"revokedCredentials":{"summary":"Revoked credentials","value":{"id":"req-2234567892","errors":[{"code":"auth.invalid","title":"Invalid authentication","detail":"The authentication credentials have been revoked. Please contact your workspace administrator."}]}}}}}},"ForbiddenResponse":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"Permission denied for resource","value":{"id":"req-3234567890","errors":[{"code":"auth.accessDenied","title":"Access denied","detail":"You do not have permission to perform this operation on the specified resource. Contact your workspace administrator to request access."}]}},"insufficientScope":{"summary":"Insufficient OAuth scopes","value":{"id":"req-3234567891","errors":[{"code":"auth.accessDenied","title":"Access denied","detail":"Your authentication token lacks the required OAuth scopes to perform this operation. Please re-authenticate with the necessary scopes."}]}},"readOnlyRole":{"summary":"Read-only role restriction","value":{"id":"req-3234567892","errors":[{"code":"auth.accessDenied","title":"Access denied","detail":"Your user role does not permit this operation. Please contact your workspace administrator."}]}}}}}},"NotFoundResponse":{"description":"Not Found - The requested resource does not exist or is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"resourceNotFoundById":{"summary":"Resource not found by ID","value":{"id":"req-4234567890","errors":[{"code":"resource.notFound","title":"Resource not found","detail":"The requested resource could not be found or you do not have permission to access it."}]}},"routeNotFound":{"summary":"API route not found","value":{"id":"req-4234567893","errors":[{"code":"route.notFound","title":"Route not found","detail":"The requested URL path does not match any defined API route. Please check the API documentation for valid endpoints."}]}}}}}},"RequestTimeoutResponse":{"description":"Request Timeout - The server did not receive a complete request within the allowed time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"requestTimeout":{"summary":"Request timeout","value":{"id":"req-5234567890","errors":[{"code":"request.timeout","title":"Request timeout","detail":"The request took too long to process and was terminated. Try simplifying your request or try again later."}]}}}}}},"TooManyRequestsResponse":{"description":"Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rateLimitExceeded":{"summary":"Rate limit exceeded","value":{"id":"req-7234567890","errors":[{"code":"rate.limitExceeded","title":"Rate limit exceeded","detail":"You have exceeded the allowed number of API requests. Please wait before making additional requests."}]}}}}}},"InternalServerErrorResponse":{"description":"Internal Server Error - An unexpected error occurred on the server, please retry or contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"internalServerError":{"summary":"Unexpected server error","value":{"id":"req-8234567890","errors":[{"code":"internal.serverError","title":"Internal server error","detail":"An unexpected error occurred while processing your request. Please try again later. If the problem persists, contact support with the correlation ID."}]}}}}}}}},"x-readme":{"samples-languages":["shell","javascript","ruby"]}}