Filter Industry EPDs Categories
POST
v3/datasets/{datasetId}/industry-epds/categories:filter
Retrieves a filtered list of industry EPD categories available for the specified dataset based on the provided filter criteria.
Resource Information
| Method and URI | POST https://developer.api.autodesk.com/sustainability/v3/datasets/{datasetId}/industry-epds/categories:filter |
| Authentication Context | User context required |
| Required OAuth Scopes | data:read |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is a three-legged access token obtained via an Authorization Code flow or a Secure Service Account (SSA) flow.
The SSA flow is designed for headless server-to-server operations. While it functions like a two-legged flow (no user interaction), it is classified as three-legged because it preserves user context. |
| Content-Type* string | Must be application/json |
* Required
Request
URI Parameters
| datasetId string | Unique identifier for the dataset. Use this value as the datasetId URI parameter in API requests to access that dataset’s data. |
Request
Query String Parameters
| limit int | The maximum number of results to return in a single response. This controls the page size for pagination and helps manage response times and memory usage. The actual number of results may be fewer due to filtering, data availability, or server constraints. |
| offset int | The number of results to skip from the beginning of the collection before returning results. This allows pagination through large datasets by specifying which result to start from. Default value is 0 (start from the beginning). |
Request
Body Structure
Filter criteria to narrow down industry EPDs categories within the specified dataset
Expand all
| filters* object | Map of filter id to filter clause. Keys are filter identifiers; values are { op, value } objects. An empty object applies no filtering. Omit optional known filters rather than sending null as the clause value. |
| ** object | A well-formed filter clause. Each key under filters in the request body must map to an object with op and value. Sending explicit null as the clause (instead of { op, value }) is invalid. The value field may be null as a primitive when the operator allows it. |
| op* enum:string | Filter operator. Must be one of the supported operators.
Possible values: EQ, NEQ, IN, NOT_IN, LT, LTE, GT, GTE, CONTAINS, BETWEEN |
| value* one of | Filter value. For scalar operators (EQ, NEQ, LT, LTE, GT, GTE, CONTAINS), supply a single primitive (string, number, boolean, or null). For array operators (IN, NOT_IN), supply an array of primitives. For BETWEEN, supply a 2-element array representing the inclusive range bounds. |
| 0* string | |
| 1* number | |
| 2* boolean | |
| 3* array | |
| oneOf* array:oneOf | |
| 0* string | |
| 1* number | |
| 2* boolean |
* Required
Response
HTTP Status Code Summary
| 200 OK | A list of industry EPDs categories was successfully retrieved. |
| 400 Bad Request | The request could not be processed due to invalid or malformed data. Check the request parameters, body format, and required fields before retrying. |
| 401 Unauthorized | The supplied authorization header was invalid or the token scope was not acceptable. Verify your authentication credentials and try again. |
| 403 Forbidden | The request was valid but lacked the necessary permissions. Verify your credentials and permissions before sending the request again. |
| 404 Not Found | The requested resource could not be found on the server. Review the request and try again. |
| 422 Unprocessable Entity | The dataset does not declare the data type required by this route in supportedDataTypes. Use GET /v3/datasets to inspect supportedDataTypes for the dataset. |
| 424 | The request could not be completed because the data provider failed or does not support this operation. Inspect the response body’s type, title, and detail fields to determine the cause: NOT_FOUND means the operation is unsupported for this dataset; AUTH_ERROR means the provider could not authenticate the request due to invalid credentials or token; RESOURCE_NOT_FOUND means the requested resource could not be found; REQUEST_LIMIT_EXCEEDED means the data provider has reached its request limit. Please reach out to them; UNKNOWN means the provider encountered an unexpected error. |
Response
Body Structure (200)
Expand all
| results array: object | Array of category items available in the dataset. |
| id string | Unique identifier for the category within its classification system. Categories with the same characteristics in different classification systems must not share the same identifier. |
| system string | Classification system used for this category. Examples: none, masterformat, unspc, uniformat, omniclass, etc. |
| code string | Category code within the classification system. Format varies by system (e.g., “03 30 00” for MasterFormat, “311” for UNSPC). |
| name string | Human-readable name of the category. |
| parentId string | Identifier of the parent category in hierarchical classification systems.
This should be null for top-level categories or non-hierarchical systems. |
| pagination object | Contains pagination metadata for navigating through large result sets. |
| offset int | The number of results skipped from the beginning of the collection to retrieve the current set of results. This value will be the value supplied in the request. |
| limit int | Determines maximum number of objects that may be returned in the current set of results. A request may return fewer objects due to filtering and other reasons. This value will be the value used by the server in the response. This may be different from the request. |
| totalResults int | The total number of results that match the request irrespective of the limit. Can be null if the total number of results is not known. |
| nextUrl string | Link that will return the next set of results. This value may be null which indicates that the consumer has reached the last set of results and should stop paging. |
| appliedFilters object | Present on every successful :filter response; may be an empty object. Maps filter ids the client sent that were used for this action to { requested, applied, warnings? } entries. |
| * object | An applied filter entry showing the requested and applied filter values. |
| requested object | The filter value as requested by the client. |
| op enum:string | The filter operator.
Possible values: EQ, NEQ, IN, NOT_IN, LT, LTE, GT, GTE, CONTAINS, BETWEEN |
| value one of | The filter value. Can be a single string, number, boolean, an array of strings, an array of numbers, or null. |
| 0 string | |
| 1 number | |
| 2 boolean | |
| 3 array: string | |
| 4 array: number | |
| applied object | The filter value as actually applied. |
| op enum:string | The filter operator.
Possible values: EQ, NEQ, IN, NOT_IN, LT, LTE, GT, GTE, CONTAINS, BETWEEN |
| value one of | The filter value. Can be a single string, number, boolean, an array of strings, an array of numbers, or null. |
| 0 string | |
| 1 number | |
| 2 boolean | |
| 3 array: string | |
| 4 array: number | |
| warnings array: string | Optional warnings about the applied filter. |
| ignoredFilters object | Present on every successful :filter response; may be an empty object. Maps filter ids the client sent that are not supported for this action (per filter discovery for that resource and action) to { reason } entries. Keys must match the client’s filter ids exactly. Every filter entry in the request must be a valid { op, value } clause (see the filter request schema) or the request fails with 400. |
| * object | An ignored filter entry with the reason it was ignored. |
| reason string | The reason the filter was ignored. For filter ids not supported on this action, the response uses the fixed string Filter is not supported by this connector. |
| warnings array: string | Optional top-level warnings when one or more list items from the data provider failed validation and were excluded from results. Omitted when no items were stripped. |
Example
A list of industry EPDs categories was successfully retrieved.
Request
curl -v 'https://developer.api.autodesk.com/sustainability/v3/datasets/f81d4fae-7dec-11d0-a765-00a0c91e6bf6/industry-epds/categories:filter?limit=100' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"filters": {
"jurisdictions": {
"op": "IN",
"value": [
"US",
"CA"
]
}
}
}'
Show More
Response
{
"results": [
{
"id": "cat-masterformat-030000",
"system": "masterformat",
"code": "03 30 00",
"name": "Cast-in-Place Concrete",
"parentId": "abc123-parent-id"
}
],
"pagination": {
"offset": 0,
"limit": 25,
"nextUrl": "https://developer.api.autodesk.com/sustainability/v3/datasets/f81d4fae-7dec-11d0-a765-00a0c91e6bf6/epds/categories?offset=25&limit=25",
"totalResults": 150
},
"appliedFilters": {
"categoryId": {
"requested": {
"op": "EQ",
"value": "cat-masterformat-033000"
},
"applied": {
"op": "EQ",
"value": "cat-masterformat-033000"
}
},
"jurisdictions": {
"requested": {
"op": "IN",
"value": [
"US",
"CA"
]
},
"applied": {
"op": "IN",
"value": [
"US"
]
},
"warnings": [
"Value 'CA' is not supported for jurisdictions and was ignored."
]
}
},
"ignoredFilters": {
"unknown_filter": {
"reason": "Filter is not supported by this connector."
}
},
"warnings": [
"The number of results returned differs from pagination.totalResults because 1 record from the data provider failed validation and were omitted. Please contact your data provider for assistance. Example record ID: bad-record-1."
]
}
Show More