Skip to main content
POST
Create a material pool

Authorizations

Authorization
string
header
required

OAuth 2.0 client credentials. Exchange your client_id and client_secret for an access token scoped to the organisation that provides data access.

Headers

Cula-Organisation-Id
string
required

ID of the organisation the request operates on behalf of (e.g. org_...). Must be an organisation the API client has access to.

Example:

"org_01k83mfmhgchya944v86ryvhpq"

Body

application/json
site
object
required

The site owning the pool. Reference it either by its ID or by its external ID, but not both.

materials
object[]
required

Materials the pool holds balances for. Water is excluded automatically.

Minimum array length: 1
name
string

Human-readable name for the pool.

Maximum string length: 100
Example:

"Woodchips pile north"

type
enum<string>

Defaults to the owning site's default.

Available options:
pile,
tank
transaction_strategy
enum<string>

Defaults to the site's configured default. Cannot be changed after creation.

Available options:
queue,
stack
external_id
string

A optional custom ID that can be set to an internal ID from your system. This ID must be unique within all objects of the organisation you operate in. You can later use this external ID to reference and query this object. Be aware that you can update this ID later. If you need an immutable ID, use the object ID returned when creating the object.

Required string length: 1 - 100
Pattern: ^[A-Za-z0-9\-_]+$
Example:

"POOL-EXT-0001"

Response

Material pool created.

id
string
required

Unique identifier of the material pool.

Example:

"mpl_01k2xytkbr0pxazkxbj4j5gr0y"

external_id
string | null
required

The external ID you assigned to this pool, if any.

Example:

"POOL-EXT-0001"

name
string | null
required

User-given name of the pool, if any.

Example:

"Woodchips pile north"

type
enum<string>
required

Physical form of the pool: a solid pile or a liquid tank.

Available options:
pile,
tank
Example:

"pile"

transaction_strategy
enum<string>
required

How mixed material is attributed to its sources during carbon accounting: queue consumes contributions oldest-first (FIFO), stack newest-first (LIFO). Fixed at creation.

Available options:
queue,
stack
Example:

"stack"

is_archived
boolean
required

Archived pools are excluded from inventory views and are never auto-selected as a transaction target.

Example:

false

site
object
required

The site owning this pool.

contents
object[]
required

Current per-material balances.

created_at
string<date-time>
required

Time the pool was created.

Example:

"2025-10-10T21:03:58Z"