> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isometric.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Project Documents
> A paginated list of all project documents for the given project.
Returned list of documents will be sorted alphabetically by document name.
## OpenAPI
````yaml get /projects/{id}/documents
openapi: 3.1.0
info:
description: >
# Standards
## Versioning
This API will be safely versioned using root path versioning, in the format
`/v{major}`. For example, `/registry/v0/supplier`.
### Compatibility
We 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.
We may deprecate APIs that have been replaced by a newer version. When doing
so, we will expect
integrated partners to manage a transition to new resources within the
deprecation timeline of old ones.
We will make the following sort of changes we do not consider to be
breaking:
- Adding new endpoints
- Adding optional query parameters to API endpoints
- Adding new properties to existing API responses
- Reordering properties in existing API responses
It is important that clients are built to be robust to these changes.
## Pagination
Our API is based on the
[Relay](https://relay.dev/docs/tutorial/connections-pagination/) pagination
spec. Paginated endpoints
will return a `PaginatedListResource` which contains:
- `page_info` - Containing information regarding pagination cursors and the
total number of entities.
- `nodes` - Each node is a paginated entity.
- `total_count` - The total size of the list across all pages.
### Pagination Parameters
Paginated endpoints also accepted a standard set of query parameters:
- `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.
- `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.
- `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.
- `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.
For example, querying `/registry/v0/beneficiaries` will return a
`PaginatedListResource` of the first page of 10 items:
```json
{
"page_info": {
"has_previous_page": false,
"start_cursor": ...,
"has_next_page": true,
"end_cursor": "mpG5kcuoFBYtlH",
},
"nodes": [{
"id": "org_12345iso678",
"name": "My Org",
...
}],
"total_count": 100
}
```
Then querying `/registry/v0/beneficiaries?first=15&after=mpG5kcuoFBYtlH`
will return a `PaginatedListResource` of the next 15 items.
## Dates
Datetime 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`.
## Country Codes
Countries 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`.
# Authentication
Most API requests will need to authenticate against the Isometric API in two
ways simultaneously:
- By passing a **client secret** in the `X-Client-Secret` header to identify
the system integrating with the API.
- By passing an **access token** in the `Authorization` header to
authenticate as a specific organization, in order to gain access to its
private data.
### Client Authentication
Every API call to Isometric must include a **client secret** identifying the
client application.
This client secret is tied to a particular environment - sandbox or
production.
The client secret should be submitted on every API request via the
`X-Client-Secret` header. For example `X-Client-Secret: uPrO...wxAh`.
### Organization Authentication
In 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.
To authenticate as an Organization you will need to submit a JWT bearer
access token via the `Authorization` header. For example: `Authorization:
Bearer eyJh...sw5c`.
If 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.
Access tokens should be treated as highly sensitive, kept secret and stored
accordingly.
Access 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.
### Managing Credentials
Credentials 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.
Both client secrets and access tokens can be created and invalidated through
UI.
Client secrets do not expire and do not need to be rotated.
If either secret becomes compromised, it should be invalidated through the
UI.
# Key Registry Concepts
## Introduction
This page defines concepts found in the Isometric Registry, and used in the
[Registry API](/api-reference/registry/registry-introduction).
For a broader understanding of the requirements and processes governing the
Isometric Registry, please refer to the [Isometric
Standard](https://isometric.com/standard).
## Key Concepts
### Entities
#### Supplier
An entity that removes carbon dioxide from the atmosphere so that it can be
stored durably and sells this service to Buyers.
#### Project
An activity, process or group of activities or processes that alter the
condition of a Baseline, resulting in
[Removals](/user-guides/certify/key-certify-concepts#removals).
#### Buyer
An entity (usually a corporation, but can also be an individual or a
government entity) that purchases CDR, often with the purpose of retiring
CDR credits to make a carbon neutral or net-negative claim.
#### Beneficiary
An organization benefiting from the Removal claim afforded by a Credit. This
may be the current holder of the Credit at the time of Retirement, or an
organization specified by the Credit account holder during the Retirement
procedure.
### Credits
A credit is a publicly visible, uniquely identifiable Credit Certificate
Issued by a Registry that gives the owner of the Credit the right to account
for one net metric tonne of Verified CO₂e Removal.
In the case of the Isometric Standard, the net tonne of CO₂e Removal comes
from a Project validated against a certified Protocol.
#### Order
A set number of tonnes that a buyer purchases from a supplier in a given
contract. An order is logged in the Isometric registry once a buyer has also
agreed a verification fee with Isometric.
#### Issuance
Once a Verified Removal has taken place, Isometric issues credits to the
account of a Supplier, enabling them to deliver credits to their buyers with
pending orders.
#### Delivery
The outcome of a supplier apportioning removals into orders to fulfill their
buyers' purchases. A removal can only be delivered after it has been
verified.
#### Retirement
Retirement is a mechanism where a Credit's state is finalized in order to
make a public claim. On retirement, Isometric issues a retirement
certificate and the credit can no longer be updated. This ensures that once
the net tonne of CO₂e represented by the retired Credit is used towards an
accounting activity, it is not double counted.
Credit batches will have the status `RETIRED` after retirement.
#### Buffer Pool
The Buffer Pool is a pool of credits that are held in an account matched to
a Supplier to manage reversal risk. Buffer pool credits may be cancelled in
the case of a reversal.
#### Credit Vintage
The Credit Vintage is the calendar year in which the underlying carbon
removal or climate impact associated with a Credit occurred, as determined
by the end date of the relevant removal or reduction. This will commonly,
but not necessarily, correspond to the year of Credit issuance, as issuance
may occur at a later date due to reporting or verification timelines.
Where a method supports granular reporting data, or growth or process
modelling, across a multi-year reporting period, Credits may be split across
multiple vintage years to reflect the calendar year in which each portion of
removal or climate impact occurred. Where removals or climate impact cannot
be robustly attributed to individual calendar years, the vintage is assigned
based on the end date of that reporting period.
### Credit Batches
A Credit Batch is a grouping of 1 or more credit units, where each credit
unit represents 1kg of CO₂e removed.
When credits are initially Issued, they will be batched together with status
`ACTIVE`. When subsequent transactions are made using these credits,
including deliveries, retirements and transfers, a batch might be split to
make this possible.
All credits in batch will always have the same initial Supplier, Project and
Issuance.
#### Credit Batch Splitting
If the quantity of credits in a transaction request (delivery, transfer or
retirement) does not match the full size of the submitted credit batches,
the batches submitted will be split in order to transact the exact credit
amount requested.
When a credit batch is split, its status will be updated to `SPLIT` and it
can no longer be interacted with.
Two _child_ batches representing the two halves of the split are created
with an `ACTIVE` status.
For API users, child batches will have a `parent_id` set pointing at the
originally split batch.
From the parent split batch, you can find its two children via the
`left_child_id` and `right_child_id` fields.
See the [Credit Batch endpoint](/api-reference/registry/credit-batch) for
more details.
title: Isometric Registry API
version: v0
servers:
- description: Sandbox Isometric Registry API
url: https://api.sandbox.isometric.com/registry/v0
- description: Production Isometric Registry API
url: https://api.isometric.com/registry/v0
security: []
paths:
/projects/{id}/documents:
get:
summary: Project Documents
description: >-
A paginated list of all project documents for the given project.
Returned list of documents will be sorted alphabetically by document
name.
operationId: project_documents_projects__id__documents_get
parameters:
- in: path
name: id
required: true
schema:
$ref: '#/components/schemas/IsometricIDPathParam_Project_'
- 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_ProjectDocument_'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
security:
- HTTPBearer: []
components:
schemas:
IsometricIDPathParam_Project_:
$ref: '#/components/schemas/IsometricIDRequestParam_Project_'
PaginatedListResource_ProjectDocument_:
properties:
nodes:
items:
$ref: '#/components/schemas/ProjectDocument'
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[ProjectDocument]
type: object
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
IsometricIDRequestParam_Project_:
example: prj_1CTWZQGKE1S0VAXA
examples:
- prj_1CTWZQGKE1S0VAXA
- prj_1E0QTWB22SBX34D1
maxLength: 37
minLength: 20
type: string
ProjectDocument:
properties:
display_name:
title: Display Name
type: string
id:
example: pjd_1ESC3V76T1S0S6J3
examples:
- pjd_1ESC3V76T1S0S6J3
- pjd_1E0AZYQ9ESBX2569
maxLength: 37
minLength: 20
title: Id
type: string
project_id:
example: prj_1CTWZQGKE1S0VAXA
examples:
- prj_1CTWZQGKE1S0VAXA
- prj_1E0QTWB22SBX34D1
maxLength: 37
minLength: 20
title: Project Id
type: string
url:
title: Url
type: string
required:
- id
- display_name
- project_id
- url
title: ProjectDocument
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
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
securitySchemes:
HTTPBearer:
bearerFormat: JWT
description: >-
A JWT Bearer token header for authentication and authorization, in the
format `Authorization: Bearer `
scheme: bearer
type: http
````