Read and write the ESG data core of the Measurabl platform: portfolios, buildings, spaces, funds, energy and water meters and their readings and bills, waste meters and readings, green building certifications and certification types, and ratings (including space-level certifications and ratings). JSON:API over OAuth 2.0 client credentials; 57 operations across 32 paths.
openapi: 3.0.1
info:
title: Measurabl Core API
version: v0
description: '## Quick Start Guide
1. Authorize using your client credentials (key and secret).
2. Make a `GET /core/v0/portfolios` request (under the Portfolios section) to get a list of available portfolios.
3. Obtain the proper portfolio_id (id) in which you need to get/create data for.
4. This `portfolio_id` will be required for all other reoccurring requests.
* [Authentication](https://support.measurabl.com/hc/en-us/articles/15889532915085-How-do-I-authenticate-with-Measurabl-s-Core-API-)
* [Release Notes](https://api.measurabl.com/release_notes)
* [Usage/Rate Limits](https://support.measurabl.com/hc/en-us/articles/15889355100429-Core-API-Usage-Rate-Limits)
* [Pagination & Filtering](https://support.measurabl.com/hc/en-us/articles/15889550313101-Core-API-Pagination-Filtering-Requests)
* [Code Examples](https://github.com/Measurabl/measurabl_api_code_samples)
### Response Format
Each endpoint response complies with the [JSON-API Specification](https://jsonapi.org/) which has many available [client
libraries](https://jsonapi.org/implementations/#client-libraries).
'
components:
schemas:
json_api:
oneOf:
- $ref: '#/components/schemas/success'
- $ref: '#/components/schemas/failure'
- $ref: '#/components/schemas/info'
success:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/data'
included:
description: To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources
along with the requested primary resources. Such responses are called 'compound documents'.
type: array
items:
$ref: '#/components/schemas/resource'
uniqueItems: true
meta:
$ref: '#/components/schemas/meta'
links:
description: Link members related to the primary data.
allOf:
- $ref: '#/components/schemas/links'
- $ref: '#/components/schemas/pagination'
jsonapi:
$ref: '#/components/schemas/jsonapi'
additionalProperties: false
failure:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/error'
uniqueItems: true
meta:
$ref: '#/components/schemas/meta'
jsonapi:
$ref: '#/components/schemas/jsonapi'
links:
$ref: '#/components/schemas/links'
additionalProperties: false
info:
type: object
required:
- meta
properties:
meta:
$ref: '#/components/schemas/meta'
links:
$ref: '#/components/schemas/links'
jsonapi:
$ref: '#/components/schemas/jsonapi'
additionalProperties: false
meta:
description: Non-standard meta-information that can not be represented as an attribute or relationship.
type: object
additionalProperties: true
data:
description: The document's 'primary data' is a representation of the resource or collection of resources targeted by
a request.
anyOf:
- $ref: '#/components/schemas/resource'
- description: An array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests
that target resource collections.
type: array
items:
$ref: '#/components/schemas/resource'
uniqueItems: true
- description: null if the request is one that might correspond to a single resource, but doesn't currently.
nullable: true
resource:
description: '''Resource objects'' appear in a JSON:API document to represent resources.'
type: object
required:
- type
- id
properties:
type:
type: string
id:
type: string
attributes:
$ref: '#/components/schemas/attributes'
relationships:
$ref: '#/components/schemas/relationships'
links:
$ref: '#/components/schemas/links'
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
relationshipLinks:
description: A resource object **MAY** contain references to other resource objects ('relationships'). Relationships
may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.
type: object
properties:
self:
$ref: '#/components/schemas/link'
related:
$ref: '#/components/schemas/link'
additionalProperties: true
links:
type: object
additionalProperties:
$ref: '#/components/schemas/link'
link:
description: 'A link **MUST** be represented as either: a string containing the link''s URL or a link object.'
oneOf:
- description: A string containing the link's URL.
type: string
format: uri-reference
nullable: true
- type: object
required:
- href
properties:
href:
description: A string containing the link's URL.
type: string
format: uri-reference
meta:
$ref: '#/components/schemas/meta'
attributes:
description: Members of the attributes object ('attributes') represent information about the resource object in which
it's defined.
type: object
additionalProperties: true
relationships:
description: Members of the relationships object ('relationships') represent references from the resource object in
which it's defined to other resource objects.
type: object
properties:
links:
$ref: '#/components/schemas/relationshipLinks'
data:
description: Member, whose value represents 'resource linkage'.
oneOf:
- $ref: '#/components/schemas/relationshipToOne'
- $ref: '#/components/schemas/relationshipToMany'
meta:
$ref: '#/components/schemas/meta'
additionalProperties: true
relationshipToOne:
description: References to other resource objects in a to-one ('relationship'). Relationships can be specified by including
a member in a resource's links object.
anyOf:
- $ref: '#/components/schemas/empty'
- $ref: '#/components/schemas/linkage'
relationshipToMany:
description: An array of objects each containing 'type' and 'id' members for to-many relationships.
type: array
items:
$ref: '#/components/schemas/linkage'
uniqueItems: true
empty:
description: Describes an empty to-one relationship.
nullable: true
linkage:
description: The 'type' and 'id' to non-empty members.
type: object
required:
- type
- id
properties:
type:
type: string
id:
type: string
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
pagination:
type: object
properties:
first:
description: The first page of data
type: string
format: uri-reference
x-nullable: true
last:
description: The last page of data
type: string
format: uri-reference
x-nullable: true
prev:
description: The previous page of data
type: string
format: uri-reference
x-nullable: true
next:
description: The next page of data
type: string
format: uri-reference
x-nullable: true
jsonapi:
description: An object describing the server's implementation
type: object
properties:
version:
type: string
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
error:
type: object
properties:
id:
description: A unique identifier for this particular occurrence of the problem.
type: string
links:
$ref: '#/components/schemas/links'
status:
description: The HTTP status code applicable to this problem, expressed as a string value.
type: string
code:
description: An application-specific error code, expressed as a string value.
type: string
title:
description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence
of the problem, except for purposes of localization.
type: string
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
source:
type: object
properties:
pointer:
description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. '/data' for a primary
data object, or '/data/attributes/title' for a specific attribute].
type: string
parameter:
description: A string indicating which query parameter caused the error.
type: string
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.measurabl.com/token
scopes: {}
paths:
/core/v0/portfolios/{portfolio_id}/buildings:
post:
summary: Adds a building to a specified portfolio
tags:
- Buildings
security:
- OAuth2: []
parameters:
- name: portfolio_id
in: path
description: 'Example: <em>bb97d075-a826-4001-b4bb-2dbab87e2b72</em>'
required: true
schema:
type: string
responses:
'200':
description: Creates a portfolio specific building
content:
application/vnd.api+json:
example:
data:
id: 99b0e527-a662-4121-b2bf-dc59f2ad9a28
type: buildings
attributes:
estarId: null
name: Test Building
addressLine1: 900 Spear Avenue
addressLine2: ''
addressCity: San Francisco
addressState: CA
addressProvince: null
addressZip: '94105'
addressCountry: United States
yearBuilt: null
buildingClass: C
primaryPropertyType: Data Center
floorAreaSqFt: 20000
customId: null
boughtDate: '2026-01-16'
soldDate: null
isSingleTenant: false
percentOwned: 80.0
isActive: false
updatedAt: '2026-04-01 00:00:00'
links:
self: /portfolios/74468b82-3bb8-4f8e-a4a8-8dd69efeb4cc/buildings/99b0e527-a662-4121-b2bf-dc59f2ad9a28
schema:
$ref: '#/components/schemas/json_api'
'404':
description: Not Found
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Could not find building 0a86c55e-18eb-4ba0-80fe-3fa949e22303 in portfolio 818c909b-f251-4666-a428-28c7b865cba3
schema:
$ref: '#/components/schemas/json_api'
'401':
description: Unauthorized Request
content:
application/vnd.api+json:
example:
errors:
- status: '401'
title: Unauthorized
detail: Unauthorized Request
schema:
$ref: '#/components/schemas/json_api'
'400':
description: Bad Request
content:
application/vnd.api+json:
example:
errors:
- status: '400'
title: Bad Request
detail: An invalid UUID parameter was submitted with the request (portfolio_id)
schema:
$ref: '#/components/schemas/json_api'
'502':
description: Internal Error
content:
application/vnd.api+json:
example:
errors:
- status: '502'
title: Bad Gateway
detail: A Measurabl Server is down, please try again later
schema:
$ref: '#/components/schemas/json_api'
'500':
description: Internal Error
content:
application/vnd.api+json:
example:
errors:
- status: '500'
title: Internal Server Error
detail: An error occurred with the request
schema:
$ref: '#/components/schemas/json_api'
'503':
description: Service Unavailable
content:
application/vnd.api+json:
example:
errors:
- status: '503'
title: Service Unavailable
detail: A Measurabl Server is currently unavailable, please try again later
schema:
$ref: '#/components/schemas/json_api'
'408':
description: Request Timeout
content:
application/vnd.api+json:
example:
errors:
- status: '408'
title: Request Timeout
detail: The request you made has timed out
schema:
$ref: '#/components/schemas/json_api'
'429':
description: Too many requests
content:
application/vnd.api+json:
example:
errors:
- status: '429'
title: Too Many Requests
detail: Rate Limit Exceeded
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: object
properties:
type:
type: string
attributes:
type: object
properties:
name:
type: string
addressLine1:
type: string
addressLine2:
type: string
addressCity:
type: string
addressState:
type: string
addressProvince:
type: string
addressZip:
type: string
addressCountry:
type: string
yearBuilt:
type: integer
buildingClass:
type: string
primaryPropertyType:
type: string
floorAreaSqFt:
type: integer
customId:
type: string
boughtDate:
type: string
soldDate:
type: string
isSingleTenant:
type: boolean
percentOwned:
type: float
isActive:
type: boolean
required:
- name
- addressLine1
- addressCity
- addressState
- addressZip
- addressCountry
- primaryPropertyType
- floorAreaSqFt
example:
data:
type: buildings
attributes:
name: API Test Building
addressLine1: 900 Spear Avenue
addressLine2: ''
addressCity: San Francisco
addressState: CA
addressProvince: null
addressZip: '94105'
addressCountry: United States
yearBuilt: 1980
buildingClass: C
primaryPropertyType: Data Center
floorAreaSqFt: 20000.0
customId: null
boughtDate: '2026-03-29'
soldDate: null
isSingleTenant: false
percentOwned: 80.0
isActive: false
required: true
description: Request body used to create a building associated with a portfolio
get:
summary: Returns a paginated list of buildings for a specified portfolio or fund
tags:
- Buildings
security:
- OAuth2: []
parameters:
- name: portfolio_id
in: path
description: "UUID of either the parent portfolio or fund<br>\n Example: <em>73755608-a99d-40d9-94df-09d8ff67e7cd</em>"
required: true
- name: filter
in: query
description: "Filter by any attribute available via the endpoint.\n <ul>\n <li>updatedAt=ge=2022-11-01T00:00\
\ will query for buildings that were updated at or after the set date and UTC time.</li>\n <li>yearbuilt==1969\
\ will query for buildings that have a year built specifically in 1969.</li>\n </ul>"
schema:
type: string
- name: page
in: query
default: 1
schema:
type: integer
- name: size
in: query
description: The max page size is limited to 200 returned results
default: 25
schema:
type: integer
responses:
'200':
description: portfolio or fund with buildings found
content:
application/vnd.api+json:
example:
data:
- id: 4008cd95-4aeb-4019-b387-c0a7377fa58e
type: buildings
attributes:
estarId: 34137899
name: Bug Test
addressLine1: 123 Bug St
addressLine2: ''
addressCity: San Diego
addressState: CA
addressProvince: null
addressZip: '92104'
addressCountry: United States
yearBuilt: 1969
buildingClass: null
primaryPropertyType: Movie Theater
floorAreaSqFt: 25000
customId: null
boughtDate: '2025-09-01'
soldDate: null
isSingleTenant: true
percentOwned: 100.0
isActive: true
updatedAt: '2026-05-16 00:00:00'
links:
self: /portfolios/8472cd20-dfca-498e-8d1e-95efc92f56c9/buildings/4008cd95-4aeb-4019-b387-c0a7377fa58e
- id: 4f05c66f-ab07-455d-8c06-91b099b6e486
type: buildings
attributes:
estarId: 33212337
name: Parent Building 3
addressLine1: 1007 1st St St
addressLine2: ''
addressCity: Stilwater
addressState: MN
addressProvince: null
addressZip: '55082'
addressCountry: United States
yearBuilt: 1869
buildingClass: null
primaryPropertyType: Financial Office
floorAreaSqFt: 750
customId: null
boughtDate: '2026-07-02'
soldDate: null
isSingleTenant: false
percentOwned: 50.0
isActive: true
updatedAt: '2026-01-16 00:00:00'
links:
self: /portfolios/8472cd20-dfca-498e-8d1e-95efc92f56c9/buildings/4f05c66f-ab07-455d-8c06-91b099b6e486
- id: 7813777b-addb-449d-8117-1ed2c8578a72
type: buildings
attributes:
estarId: 25849582
name: Meter Test 1zzz
addressLine1: 111 Meter St
addressLine2: ''
addressCity: San Diego
addressState: CA
addressProvince: null
addressZip: '92111'
addressCountry: United States
yearBuilt: 1969
buildingClass: null
primaryPropertyType: Office
floorAreaSqFt: 0
customId: null
boughtDate: '2026-02-23'
soldDate: null
isSingleTenant: true
percentOwned: 100.0
isActive: false
updatedAt: '2026-07-11 00:00:00'
links:
self: /portfolios/8472cd20-dfca-498e-8d1e-95efc92f56c9/buildings/7813777b-addb-449d-8117-1ed2c8578a72
- id: c150197f-2890-4b64-9020-c75be80b4f92
type: buildings
attributes:
estarId: 37741951
name: A Cool Building
addressLine1: 123 Meter Blvd
addressLine2: ''
addressCity: San Diego
addressState: ''
addressProvince: Uhh
addressZip: '92120'
addressCountry: Japan
yearBuilt: 1969
buildingClass: null
primaryPropertyType: Senior Care Community
floorAreaSqFt: 16531
customId: null
boughtDate: '2025-07-16'
soldDate: null
isSingleTenant: false
percentOwned: 70.5
isActive: true
updatedAt: '2026-01-20 00:00:00'
links:
self: /portfolios/8472cd20-dfca-498e-8d1e-95efc92f56c9/buildings/c150197f-2890-4b64-9020-c75be80b4f92
- id: 0f560852-e88d-4ecf-87c2-cf8c9e13c8d5
type: buildings
attributes:
estarId: 82538285
name: Warehouse Distribution Center
addressLine1: 123 Warehouse Dr
addressLine2: ''
addressCity: San Diego
addressState: CA
addressProvince: null
addressZip: '92120'
addressCountry: United States
yearBuilt: 1969
buildingClass: null
primaryPropertyType: Distribution Center
floorAreaSqFt: 1111
customId: null
boughtDate: '2026-03-20'
soldDate: null
isSingleTenant: true
percentOwned: 100.0
isActive: true
updatedAt: '2026-02-02 00:00:00'
links:
self: /portfolios/8472cd20-dfca-498e-8d1e-95efc92f56c9/buildings/0f560852-e88d-4ecf-87c2-cf8c9e13c8d5
links:
self: /portfolios/8472cd20-dfca-498e-8d1e-95efc92f56c9/buildings
meta:
page:
number: 1
size: 100
totalPages: 7
totalElements: 654
schema:
$ref: '#/components/schemas/json_api'
'404':
description: Not Found
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'Unknown portfolio UUID: a38f4ec4-c303-4deb-ac02-dcdd586cbdf2'
schema:
$ref: '#/components/schemas/json_api'
'401':
description: Unauthorized Request
content:
application/vnd.api+json:
example:
errors:
- status: '401'
title: Unauthorized
detail: Unauthorized Request
schema:
$ref: '#/components/schemas/json_api'
'400':
description: Bad Request
content:
application/vnd.api+json:
example:
errors:
- status: '400'
title: Bad Request
detail: An invalid UUID parameter was submitted with the request (portfolio_id)
schema:
$ref: '#/components/schemas/json_api'
'502':
description: Internal Error
content:
application/vnd.api+json:
example:
errors:
- status: '502'
title: Bad Gateway
detail: A Measurabl Server is down, please try again later
schema:
$ref: '#/components/schemas/json_api'
'500':
description: Internal Error
content:
application/vnd.api+json:
example:
errors:
- status: '500'
title: Internal Server Error
detail: An error occurred with the request
schema:
$ref: '#/components/schemas/json_api'
'503':
description: Service Unavailable
content:
application/vnd.api+json:
example:
errors:
- status: '503'
title: Service Unavailable
detail: A Measurabl Server is currently unavailable, please try again later
schema:
$ref: '#/components/schemas/json_api'
'408':
description: Request Timeout
content:
application/vnd.api+json:
example:
errors:
- status: '408'
title: Request Timeout
detail: The request you made has timed out
schema:
$ref: '#/components/schemas/json_api'
'429':
description: Too many requests
content:
application/vnd.api+json:
example:
errors:
- status: '429'
title: Too Many Requests
detail: Rate Limit Exceeded
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/core/v0/portfolios/{portfolio_id}/buildings/{building_id}:
delete:
summary: Removes a building from a specified portfolio
tags:
- Buildings
security:
- OAuth2: []
parameters:
- name: portfolio_id
in: path
description: 'Example: <em>a6e32f0e-5f5f-4497-b024-11f9d6f200ca</em>'
required: true
schema:
type: string
- name: building_id
in: path
description: 'Example: <em>01327933-9400-4c64-81be-2e5af129d495</em>'
required: true
schema:
type: string
responses:
'204':
description: Building Deleted Successfully
content:
application/vnd.api+json:
example: ''
'404':
description: Not Found
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Could not find building 07603756-06de-445c-ac8d-45d65a70f91a in portfolio cfb2bfe0-ce8d-44ab-8897-21c573c220a8
schema:
$ref: '#/components/schemas/json_api'
'401':
description: Unauthorized Request
content:
application/vnd.api+json:
example:
errors:
- status: '401'
title: Unauthorized
detail: Unauthorized Request
schema:
$ref: '#/components/schemas/json_api'
'400':
description: Bad Request
content:
application/vnd.api+json:
example:
errors:
- status: '400'
title: Bad Request
detail: An invalid UUID parameter was submitted with the request (portfolio_id)
schema:
$ref: '#/components/schemas/json_api'
'502':
description: Internal Error
content:
application/vnd.api+json:
example:
errors:
- status: '502'
title: Bad Gateway
detail: A Measurabl Server is down, please try again later
schema:
$ref: '#/components/schemas/json_api'
'500':
description: Internal Error
content:
application/vnd.api+json:
example:
errors:
- status: '500'
title: Internal Server Error
detail: An error occurred with the request
schema:
$ref: '#/components/schemas/json_api'
'503':
description: Service Unavailable
content:
application/vnd.api+json:
example:
errors:
- status: '503'
title: Service Unavailable
detail: A Measurabl Server is currently unavailable, please try again later
schema:
$ref: '#/components/schemas/json_api'
'408':
description: Request Timeout
content:
application/vnd.api+json:
example:
errors:
- status: '408'
title: Request Timeout
detail: The request you made has timed out
schema:
$ref: '#/components/schemas/json_api'
'429':
description: Too many requests
content:
application/vnd.api+json:
example:
errors:
- status: '429'
title: Too Many Requests
detail: Rate Limit Exceeded
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
# --- truncated at 32 KB (400 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/measurabl/refs/heads/main/openapi/measurabl-core-openapi.yml