openapi: 3.1.0
info:
description: "# Standards\n\n## Versioning\n\nThis API will be safely versioned using root path versioning, in the format `/v{major}`. For example, `/registry/v0/supplier`.\n\n### Compatibility\n\nWe won't make breaking changes to existing API services or endpoints for API versions higher than `v0`. If breaking changes are necessary, we'll release a new major version.\nWe may deprecate APIs that have been replaced by a newer version. When doing so, we will expect\nintegrated partners to manage a transition to new resources within the deprecation timeline of old ones.\n\nWe will make the following sort of changes we do not consider to be breaking:\n\n- Adding new endpoints\n- Adding optional query parameters to API endpoints\n- Adding new properties to existing API responses\n- Reordering properties in existing API responses\n\nIt is important that clients are built to be robust to these changes.\n\n## Pagination\n\nOur API is based on the [Relay](https://relay.dev/docs/tutorial/connections-pagination/) pagination spec. Paginated endpoints\nwill return a `PaginatedListResource` which contains:\n\n- `page_info` - Containing information regarding pagination cursors and the total number of entities.\n- `nodes` - Each node is a paginated entity.\n- `total_count` - The total size of the list across all pages.\n\n### Pagination Parameters\n\nPaginated endpoints also accepted a standard set of query parameters:\n\n- `last` - An integer number of items to retrieve **before** the item represented by the cursor passed in the `before` parameter. Defaults to 10 with a maximum value of 50.\n- `before` - An opaque cursor representing the first item in the previously requested page to select items ordered before it. Submit the previously requested page's `start_cursor` here when paginated backwards.\n- `first` - An integer number of items to retrieve **after** the item represented by the cursor passed in the `after` parameter. Defaults to 10 with a maximum value of 50.\n- `after` - An opaque cursor representing the last item in the previously requested page to select items ordered after it. Submit the previously requested page's `end_cursor` here when paginated forwards.\n\nFor example, querying `/registry/v0/beneficiaries` will return a `PaginatedListResource` of the first page of 10 items:\n\n```json\n{\n \"page_info\": {\n \"has_previous_page\": false,\n \"start_cursor\": ...,\n \"has_next_page\": true,\n \"end_cursor\": \"mpG5kcuoFBYtlH\",\n },\n \"nodes\": [{\n \"id\": \"org_12345iso678\",\n \"name\": \"My Org\",\n ...\n }],\n \"total_count\": 100\n}\n```\n\nThen querying `/registry/v0/beneficiaries?first=15&after=mpG5kcuoFBYtlH` will return a `PaginatedListResource` of the next 15 items.\n\n## Dates\n\nDatetime fields in the APIs conform to the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time format in UTC. For example: `2024-01-22T11:56:48.520641Z`.\n\n## Country Codes\n\nCountries are identified in the APIs via [ISO 3166-1 Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) codes. For example: `GBR` and `USA`.\n# Authentication\n\nMost API requests will need to authenticate against the Isometric API in two ways simultaneously:\n\n- By passing a **client secret** in the `X-Client-Secret` header to identify the system integrating with the API.\n- By passing an **access token** in the `Authorization` header to authenticate as a specific organization, in order to gain access to its private data.\n\n### Client Authentication\n\nEvery API call to Isometric must include a **client secret** identifying the client application.\n\nThis client secret is tied to a particular environment - sandbox or production.\n\nThe client secret should be submitted on every API request via the `X-Client-Secret` header. For example `X-Client-Secret: uPrO...wxAh`.\n\n### Organization Authentication\n\nIn addition, a large number of API requests will require an **access token** in order for the caller to identify themselves and act as a specific Organization.\n\nTo authenticate as an Organization you will need to submit a JWT bearer access token via the `Authorization` header. For example: `Authorization: Bearer eyJh...sw5c`.\nIf you are going to be acting on behalf of other Organizations, they will need to generate the access token and pass it securely to you.\nAccess tokens should be treated as highly sensitive, kept secret and stored accordingly.\n\nAccess tokens are scoped to a single Organization - so if you are acting on behalf of multiple particular organizations, you will need to submit the appropriate access token on each request.\n\n### Managing Credentials\n\nCredentials can be managed through Certify UI in the [Team settings](https://registry.isometric.com/account/team-settings) section. Access tokens will expire after 1 year from generation. When you are approaching expiry, a new token will need to be generated.\n\nBoth client secrets and access tokens can be created and invalidated through UI.\nClient secrets do not expire and do not need to be rotated.\nIf either secret becomes compromised, it should be invalidated through the UI.\n# Key Certify Concepts\n\nThis page defines concepts used in Certify, and the [Certify API](/api-reference/certify/certify-introduction), which are helpful to understand when submitting information for verification via Certify. For a broader understanding of Isometric's verification processes on the Isometric Registry, please refer to the [Isometric Standard](https://isometric.com/standard).\n\n## Resource visibility\n\n- Until resources are submitted as part of a GHG statement, they are visible only to members of your organization.\n- After statement submission, they are visible to the verifier assigned to the GHG statement.\n- Once credits have been issued, removals are added to the [public registry](https://registry.isometric.com), and associated resources are visible publicly, with the exception of source documents.\n- Sources uploaded in the Certify platform are kept private by default once published on the Isometric registry (file names will be displayed). Contact Isometric to update public source visibility. Sources [added via the API](/api-reference/certify/post-source) can be set `public` on submission.\n\n## Resources\n\nThe main resources used in Certify are sources, datapoints, components and removals.\n\n### Sources\n\n- Sources represent a piece of evidence for a particular datapoint used in carbon accounting calculations.\n- Source documents are private, and only shared with the verifier assigned to a related removal.\n- Other information associated with a source, such as its display name, is visible publicly once the removal is on the public registry.\n- Verifiers are not notified when new sources are added to datapoints in a submitted removal, but they will immediately have access to the source documentation. Please notify the Isometric Registry Operations team when sources are added on a verifier's request so that we can ensure that the verifier is aware.\n\n### Datapoints\n\n- Datapoints represent any value used in carbon accounting calculations.\n- When creating datapoints, sources should be referenced to provide evidence for the value used.\n- A standard deviation should be provided if the datapoint is to be included in the variance propagation method of uncertainty analysis.\n- All datapoints are considered statistically independent for the purpose of variance propagation, although if a datapoint is used twice within a removal calculation, this dependence is captured.\n\n### Components\n\n- Components represent physical activities whose CO₂e flux needs to be accounted for.\n- Components are created from [component blueprints](/user-guides/certify/component-blueprint-library) that contain sets of equations used to calculate a transfer of CO₂e into or out of the atmosphere.\n- A blueprint defines a set of inputs that are the datapoints to be used in the calculation. For instance, a transport emissions blueprints would ask for datapoints representing a distance, mass and carbon intensity.\n- When creating a component from a blueprint, the blueprint must be specified, as well as a list of datapoints for the expected blueprint inputs. Learn more about components in [Identifying Components](/user-guides/certify/identifying-components).\n\n### Removals\n\n- Removals represent a series of activities that result in CO₂e being removed from the atmosphere.\n- The carbon accounting of a removal typically contains sequestrations, counterfactuals and activities (emissions).\n- Removals are structured using a template, [defined in your LCA](/user-guides/certify/lca).\n- Templates are divided into component groups. For instance, a biochar template may contain a `Feedstock sourcing` group.\n- Groups can contain multiple components.\n- Components can also be partially attributed to removals, if the activity the component represents contributed to multiple removals.\n- The final uncertainty discounting is done on the removal level - the API will return the CO₂e removed with and without discounting.\n- See the [Create a removal](/user-guides/certify/removal) guide for more details.\n\n### Feedstock types\n\n- Many carbon removal methods involve a feedstock, for instance biomass feedstock in BiCRS or silicate rock in enhanced weathering.\n- Feedstock types are used to describe the feedstock used in a removal.\n- When creating a removal, a feedstock type can be optionally specified so that Isometric and verifiers can see which removals use which feedstocks.\n- This is important if different feedstocks are used in a single GHG statement.\n- See the [Add feedstock](/user-guides/certify/add-feedstock) guide for more details.\n"
title: Isometric Certify Data Ingestion Beneficiaries Sources API
version: v0
servers:
- description: Sandbox Isometric MRV API
url: https://api.sandbox.isometric.com/mrv/v0
- description: Production Isometric MRV API
url: https://api.isometric.com/mrv/v0
tags:
- name: Sources
paths:
/sources:
get:
description: Lists sources in the Isometric system
operationId: get_sources_sources_get
parameters:
- in: query
name: supplier_reference_id
required: false
schema:
anyOf:
- description: A string that must be unique for all resources created by a specific supplier. It can be used by a client to identify the correct objects in their system.
maxLength: 100
minLength: 1
type: string
- type: 'null'
title: Supplier Reference Id
- in: query
name: project_id
required: false
schema:
anyOf:
- $ref: '#/components/schemas/IsometricIDQueryParam_Project_'
- type: 'null'
title: Project Id
- in: query
name: last
required: false
schema:
default: 10
description: An integer number of items to retrieve before the item represented by the cursor passed in the before parameter. Defaults to 10 with a maximum value of 50.
exclusiveMinimum: 0
maximum: 50
title: Last
type: integer
- in: query
name: before
required: false
schema:
anyOf:
- minLength: 1
type: string
- type: 'null'
description: An opaque cursor representing the first item in the previously requested page to select items ordered before it. Submit the previously requested page’s start_cursor here when paginated backwards.
title: Before
- in: query
name: first
required: false
schema:
default: 10
description: An integer number of items to retrieve after the item represented by the cursor passed in the after parameter. Defaults to 10 with a maximum value of 50.
exclusiveMinimum: 0
maximum: 50
title: First
type: integer
- in: query
name: after
required: false
schema:
anyOf:
- minLength: 1
type: string
- type: 'null'
description: An opaque cursor representing the last item in the previously requested page to select items ordered after it. Submit the previously requested page’s end_cursor here when paginated forwards.
title: After
- description: A secret token identifying the client connecting to the API
in: header
name: x-client-secret
required: true
schema:
description: A secret token identifying the client connecting to the API
examples:
- Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
title: Client secret
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedListResource_Source_'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
summary: Get Sources
tags:
- Sources
post:
description: 'Creates a source in the Isometric system. The client is provided with a presigned
upload URL which must be used to upload the document associated with this source.
Source documents are private, but other fields will be visible publicly once
credits are issued for an associated removal, moving it to the public registry.'
operationId: post_source_sources_post
parameters:
- description: A secret token identifying the client connecting to the API
in: header
name: x-client-secret
required: true
schema:
description: A secret token identifying the client connecting to the API
examples:
- Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
title: Client secret
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDocumentSourceRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSourceResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
summary: Post Source
tags:
- Sources
/sources/{id}:
delete:
description: Deletes a source in the Isometric system. This is irreversible and the source cannot be recovered.
operationId: delete_source_sources__id__delete
parameters:
- in: path
name: id
required: true
schema:
$ref: '#/components/schemas/IsometricIDPathParam_Source_'
- description: A secret token identifying the client connecting to the API
in: header
name: x-client-secret
required: true
schema:
description: A secret token identifying the client connecting to the API
examples:
- Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
title: Client secret
type: string
responses:
'204':
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
summary: Delete Source
tags:
- Sources
get:
description: Get single source
operationId: get_source_sources__id__get
parameters:
- in: path
name: id
required: true
schema:
$ref: '#/components/schemas/IsometricIDPathParam_Source_'
- description: A secret token identifying the client connecting to the API
in: header
name: x-client-secret
required: true
schema:
description: A secret token identifying the client connecting to the API
examples:
- Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
title: Client secret
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Source'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
summary: Get Source
tags:
- Sources
patch:
description: Patches metadata associated with a source in the Isometric system.
operationId: patch_source_sources__id__patch
parameters:
- in: path
name: id
required: true
schema:
$ref: '#/components/schemas/IsometricIDPathParam_Source_'
- description: A secret token identifying the client connecting to the API
in: header
name: x-client-secret
required: true
schema:
description: A secret token identifying the client connecting to the API
examples:
- Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
title: Client secret
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchSourceRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Source'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
summary: Patch Source
tags:
- Sources
/sources/{id}/private_url:
get:
description: 'Returns a short-lived signed URL to download a source document from. This query will fail if
the source does not have a private URL or if the authenticated user does not have
access to it. That''s why you need to first check the `urlInfo` field on the source
object, to ensure that you can safely use this query.'
operationId: get_source_private_url_sources__id__private_url_get
parameters:
- in: path
name: id
required: true
schema:
$ref: '#/components/schemas/IsometricIDPathParam_Source_'
- description: A secret token identifying the client connecting to the API
in: header
name: x-client-secret
required: true
schema:
description: A secret token identifying the client connecting to the API
examples:
- Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
title: Client secret
type: string
responses:
'200':
content:
application/json:
schema:
title: Response Get Source Private Url Sources Id Private Url Get
type: string
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
summary: Get Source Private Url
tags:
- Sources
/sources/{id}/signed_upload_url:
post:
description: 'Recreates a presigned upload URL, which must be used to upload the documentation
associated with this source. If the document is already uploaded, this endpoint will
response with a 409 error.'
operationId: post_signed_upload_url_sources__id__signed_upload_url_post
parameters:
- in: path
name: id
required: true
schema:
$ref: '#/components/schemas/IsometricIDPathParam_Source_'
- description: A secret token identifying the client connecting to the API
in: header
name: x-client-secret
required: true
schema:
description: A secret token identifying the client connecting to the API
examples:
- Syou3EZiO5vuMEgNyBeA8cjEMYOnQDwP
title: Client secret
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SignedUploadUrlRequest'
required: true
responses:
'200':
content:
application/json:
schema:
title: Response Post Signed Upload Url Sources Id Signed Upload Url Post
type: string
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
summary: Post Signed Upload Url
tags:
- Sources
components:
schemas:
Undefined:
additionalProperties: false
description: An explicit representation of an undefined value in the Isometric REST API. Used, for example, to distinguish between explicit null inputs that clear a property, and not provided inputs which leave the property as is.
properties:
__typename:
const: Undefined
default: Undefined
description: Contains the name of the model (formally, OpenAPI Schema Object). Used to determine the type of data, for example when two different types are unioned.
title: Type name
type: string
title: Undefined
type: object
Source:
properties:
display_name:
anyOf:
- type: string
- type: 'null'
title: Display Name
id:
example: src_1EBBF4M7X1S06G1Y
examples:
- src_1EBBF4M7X1S06G1Y
- src_1DW1B17VNSBX37N0
maxLength: 37
minLength: 20
title: Id
type: string
is_public:
description: This field indicates Whether or not this source document will be public on the Registry once Credits are issued referencing it.
title: Is Public
type: boolean
original_filename:
anyOf:
- type: string
- type: 'null'
title: Original Filename
project_id:
anyOf:
- example: prj_1CTWZQGKE1S0VAXA
examples:
- prj_1CTWZQGKE1S0VAXA
- prj_1E0QTWB22SBX34D1
maxLength: 37
minLength: 20
type: string
- type: 'null'
description: The ID of the project that the source is associated with.
title: Project Id
published_at:
anyOf:
- format: date
type: string
- type: 'null'
title: Published At
supplier_reference_id:
anyOf:
- description: A string that must be unique for all resources created by a specific supplier. It can be used by a client to identify the correct objects in their system.
maxLength: 100
minLength: 1
type: string
- type: 'null'
title: Supplier Reference Id
type:
$ref: '#/components/schemas/SourceType'
url_info:
anyOf:
- discriminator:
mapping:
SourcePrivateUrlInfo: '#/components/schemas/SourcePrivateUrlInfo'
SourcePublicUrlInfo: '#/components/schemas/SourcePublicUrlInfo'
propertyName: __typename
oneOf:
- $ref: '#/components/schemas/SourcePublicUrlInfo'
- $ref: '#/components/schemas/SourcePrivateUrlInfo'
- type: 'null'
description: URL info for the source, that varies depending on if it is public or private
title: Url Info
required:
- id
- supplier_reference_id
- display_name
- original_filename
- type
- published_at
- url_info
- is_public
- project_id
title: Source
type: object
SourcePublicUrlInfo:
properties:
__typename:
const: SourcePublicUrlInfo
default: SourcePublicUrlInfo
description: Contains the name of the model (formally, OpenAPI Schema Object). Used to determine the type of data, for example when two different types are unioned.
title: Type name
type: string
url:
title: Url
type: string
required:
- url
title: SourcePublicUrlInfo
type: object
PageInfo:
properties:
end_cursor:
anyOf:
- type: string
- type: 'null'
title: End Cursor
has_next_page:
title: Has Next Page
type: boolean
has_previous_page:
title: Has Previous Page
type: boolean
start_cursor:
anyOf:
- type: string
- type: 'null'
title: Start Cursor
required:
- has_previous_page
- start_cursor
- has_next_page
- end_cursor
title: PageInfo
type: object
IsometricIDRequestParam_Source_:
example: src_1EBBF4M7X1S06G1Y
examples:
- src_1EBBF4M7X1S06G1Y
- src_1DW1B17VNSBX37N0
maxLength: 37
minLength: 20
type: string
ValidationError:
properties:
ctx:
title: Context
type: object
input:
title: Input
loc:
items:
anyOf:
- type: string
- type: integer
title: Location
type: array
msg:
title: Message
type: string
type:
title: Error Type
type: string
required:
- loc
- msg
- type
title: ValidationError
type: object
PaginatedListResource_Source_:
properties:
nodes:
items:
$ref: '#/components/schemas/Source'
title: Nodes
type: array
page_info:
$ref: '#/components/schemas/PageInfo'
total_count:
title: Total Count
type: integer
required:
- nodes
- total_count
- page_info
title: PaginatedListResource[Source]
type: object
CreateDocumentSourceRequest:
properties:
__typename:
const: CreateDocumentSourceRequest
description: Contains the name of the model (formally, OpenAPI Schema Object). Used to determine the type of data, for example when two different types are unioned.
title: Type name
type: string
content_length:
description: The size (in bytes) of the file that will be uploaded. The pre-signed URL will only accept a file of this size.
maximum: 50000000.0
title: Content Length
type: integer
content_type:
description: The content type of the file that will be uploaded. This must also be passed as a `Content-Type` header during the upload. The pre-signed URL will only accept a file of this content-type. See the [list of supported filetypes](/api-reference/certify/uploading-sources#supported-filetypes).
title: Content Type
type: string
display_name:
maxLength: 100
minLength: 1
title: Display Name
type: string
file_name:
description: The full name of the file that will be uploaded, including its file extension
title: File Name
type: string
is_public:
default: false
description: If the source document should be publicly available on the Registry once credits are issued.
title: Is Public
type: boolean
project_id:
description: The ID of the project that the source is associated with.
example: prj_1CTWZQGKE1S0VAXA
examples:
- prj_1CTWZQGKE1S0VAXA
- prj_1E0QTWB22SBX34D1
maxLength: 37
minLength: 20
title: Project Id
type: string
published_at:
description: Date in ISO format (YYYY-MM-DD)
format: date
title: Published At
type: string
supplier_reference_id:
description: A string that must be unique for all resources created by a specific supplier. It can be used by a client to identify the correct objects in their system.
maxLength: 100
minLength: 1
title: Supplier Reference Id
type: string
required:
- supplier_reference_id
- __typename
- display_name
- published_at
- file_name
- content_type
- content_length
- project_id
title: CreateDocumentSourceRequest
type: object
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
SignedUploadUrlRequest:
properties:
content_length:
description: The size (in bytes) of the file that will be uploaded. The pre-signed URL will only accept a file of this size.
maximum: 50000000.0
title: Content Length
type: integer
content_type:
description: The content type of the file that will be uploaded. This must also be passed as a 'content-type' header during the upload. The pre-signed URL will only accept a file of this content-type.
title: Content Type
type: string
required:
- content_type
- content_length
title: SignedUploadUrlRequest
type: object
IsometricIDRequestParam_Project_:
example: prj_1CTWZQGKE1S0VAXA
examples:
- prj_1CTWZQGKE1S0VAXA
- prj_1E0QTWB22SBX34D1
maxLength: 37
minLength: 20
type: string
PatchSourceRequest:
properties:
display_name:
anyOf:
- maxLength: 100
minLength: 1
type: string
- $ref: '#/components/schemas/Undefined'
default:
__typename: Undefined
title: Display Name
is_public:
anyOf:
- type: boolean
- $ref: '#/components/schemas/Undefined'
default:
__typename: Undefined
description: If the source document should be publicly available on the Registry once credits are issued.
title: Is Public
published_at:
anyOf:
- description: Date in ISO format (YYYY-MM-DD)
format: date
type: string
- $ref: '#/components/schemas/Undefined'
default:
__typename: Undefined
title: Published At
supplier_reference_id:
anyOf:
- description: A string that must be unique for all resources created by a specific supplier. It can be used by a client to identify the correct objects in their system.
maxLength: 100
minLength: 1
type: string
- $ref: '#/components/schemas/Undefined'
default:
__typename: Undefined
title: Supplier Reference Id
title: PatchSourceRequest
type: object
IsometricIDQueryParam_Project_:
$ref: '#/components/schemas/IsometricIDRequestParam_Project_'
SourceType:
enum:
- DOCUMENT
- WEBSITE
title: SourceType
type: string
CreateSourceResponse:
properties:
signed_upload_url:
description: A presigned upload URL, which must be used to upload the document associated with this source.
title: Signed Upload Url
type: string
source:
$ref: '#/components/schemas/Source'
required:
- source
- signed_upload_url
title: CreateSourceResponse
type: object
SourcePrivateUrlInfo:
properties:
__typename:
const: SourcePrivateUrlInfo
default:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/isometric/refs/heads/main/openapi/isometric-sources-api-openapi.yml