Skip to main content

API Endpoints Reference

This document provides a comprehensive reference for all API endpoints organized by service category.

Core Services (/co2trust-services/v1/)​

Authentication​

Authenticate User​

  • POST /co2trust-services/v1/users/auth
  • Description: Authenticate a user and receive an access token
  • Auth Required: Backend secret key (X-Backend-Secret-Key header)
  • Response: Access token and user information

Products​

List Products​

  • GET /co2trust-services/v1/products
  • Description: List all products with pagination and filtering
  • Auth Required: No (for public products)
  • Query Parameters:
    • page: Page number
    • size: Items per page
    • order: Sort direction (asc/desc)
    • Additional filters available

Get Product​

  • GET /co2trust-services/v1/products/{product_id}
  • Description: Get a single product by ID
  • Auth Required: No (for public products)

Orders​

List Orders​

  • GET /co2trust-services/v1/orders
  • Description: List all orders with pagination
  • Auth Required: Yes
  • Query Parameters:
    • page, size, order: Pagination parameters
    • supplier_id: Filter by supplier
    • product_type: Filter by product type
    • is_public: Filter by public status

Get Order​

  • GET /co2trust-services/v1/orders/{order_id}
  • Description: Get a single order by ID
  • Auth Required: Yes

Create Order​

  • POST /co2trust-services/v1/orders
  • Description: Create a new order
  • Auth Required: Yes
  • Request Body: Order creation data

Get User Orders​

  • GET /co2trust-services/v1/orders/user
  • Description: Get orders for the authenticated user
  • Auth Required: Yes

Get User Purchased Orders​

  • GET /co2trust-services/v1/orders/user/purchased
  • Description: Get orders purchased by the authenticated user
  • Auth Required: Yes

NFTs​

List NFTs​

  • GET /co2trust-services/v1/nfts
  • Description: List all NFTs with pagination
  • Auth Required: No (for public NFTs)
  • Query Parameters: page, size, order

List Mintable NFTs​

  • GET /co2trust-services/v1/nfts/mint
  • Description: List NFTs that are available for minting
  • Auth Required: No
  • Query Parameters: page, size, order

Get User NFTs​

  • GET /co2trust-services/v1/nfts/user
  • Description: Get NFTs owned by the authenticated user
  • Auth Required: Yes
  • Query Parameters:
    • page, size, order
    • available_only: Filter by available balance

Get NFT​

  • GET /co2trust-services/v1/nfts/{nft_id}
  • Description: Get a single NFT by ID
  • Auth Required: No (for public NFTs)

Suppliers​

List Suppliers​

  • GET /co2trust-services/v1/suppliers
  • Description: List all suppliers with pagination
  • Auth Required: No (for public suppliers)
  • Query Parameters:
    • page, size, order
    • featured: Filter featured suppliers
    • country_code: Filter by country
    • methodology_code: Filter by methodology

Get Supplier​

  • GET /co2trust-services/v1/suppliers/{supplier_id}
  • Description: Get a single supplier by ID with full details
  • Auth Required: No (for public suppliers)

Get Supplier IDs​

  • GET /co2trust-services/v1/suppliers/supplier_ids
  • Description: Get a list of all supplier IDs and names
  • Auth Required: No

Traders​

List Traders​

  • GET /co2trust-services/v1/traders
  • Description: List all traders with pagination
  • Auth Required: No
  • Query Parameters:
    • page, size, order
    • supplier_id: Filter by supplier

Get Trader​

  • GET /co2trust-services/v1/traders/{trader_id}
  • Description: Get a single trader by ID
  • Auth Required: No

Impact Partners​

List Impact Partners​

  • GET /co2trust-services/v1/impact-partners
  • Description: List all impact partners with pagination
  • Auth Required: No
  • Query Parameters: page, size, order

Get Impact Partner​

  • GET /co2trust-services/v1/impact-partners/{partner_id}
  • Description: Get a single impact partner by ID
  • Auth Required: No

Bundle Orders​

List Bundle Orders​

  • GET /co2trust-services/v1/bundle-orders
  • Description: List all bundle orders with pagination
  • Auth Required: No
  • Query Parameters:
    • page, size, order
    • available_only: Filter by availability

Create Bundle Order​

  • POST /co2trust-services/v1/bundle-orders
  • Description: Create a new bundle order
  • Auth Required: Yes
  • Request Body: Bundle order creation data

Get Bundle Order​

  • GET /co2trust-services/v1/bundle-orders/{bundle_order_id}
  • Description: Get a single bundle order by ID
  • Auth Required: No

Product Orders​

List Product Orders​

  • GET /co2trust-services/v1/product-orders
  • Description: List product-order relationships
  • Auth Required: No
  • Query Parameters: page, size, order

Get Product Order​

  • GET /co2trust-services/v1/product-orders/{product_order_id}
  • Description: Get a single product-order relationship
  • Auth Required: No

Sync​

Sync Order​

  • POST /co2trust-services/v1/sync/{order_hash}
  • Description: Synchronize an order with blockchain data
  • Auth Required: Yes
  • Path Parameter: order_hash - Blockchain order hash

Upsert​

Create Model​

  • POST /co2trust-services/v1/upsert/{model}
  • Description: Generic create endpoint for various models
  • Auth Required: Yes
  • Path Parameter: model - Model type (e.g., "product", "supplier")
  • Request Body: Model-specific data

Update Model​

  • PUT /co2trust-services/v1/upsert/{model}/{model_id}
  • Description: Generic update endpoint for various models
  • Auth Required: Yes
  • Path Parameters: model, model_id
  • Request Body: Model-specific update data

Get Dropdown Products​

  • GET /co2trust-services/v1/dropdown/products
  • Description: Get dropdown options for products
  • Auth Required: No
  • Query Parameter: product_type - Product type filter

Mailing List​

List Mailing List Entries​

  • GET /co2trust-services/v1/mailing-list
  • Description: List mailing list entries (admin only)
  • Auth Required: Yes (admin)
  • Query Parameters: page, size

Add to Mailing List​

  • POST /co2trust-services/v1/mailing-list
  • Description: Add an email to the mailing list
  • Auth Required: No
  • Request Body: Email address

Payment Services (/co2trust-payments/v1/)​

Payment Stats​

Get All Stats​

  • GET /co2trust-payments/v1/payment-stats
  • Description: Get all payment statistics including global and quarterly stats
  • Auth Required: No

Get Global Stats​

  • GET /co2trust-payments/v1/payment-stats/global
  • Description: Get global payment statistics
  • Auth Required: No

Get Quarterly Stats​

  • GET /co2trust-payments/v1/payment-stats/quarterly
  • Description: Get quarterly payment statistics
  • Auth Required: No

Payment Transactions​

List Payment Transactions​

  • GET /co2trust-payments/v1/payment-transactions
  • Description: List all payment transactions with pagination
  • Auth Required: No
  • Query Parameters:
    • page, size, order
    • payment_transaction_type: Filter by type (all, order, supplier, nft)
    • payment_transaction_type_id: Filter by specific ID

Get User Payment Transactions​

  • GET /co2trust-payments/v1/payment-transactions/user
  • Description: Get payment transactions for the authenticated user
  • Auth Required: Yes
  • Query Parameters: page, size, order

Bank Accounts​

List Bank Accounts​

  • GET /co2trust-payments/v1/bank-accounts
  • Description: List bank accounts for the authenticated user
  • Auth Required: Yes
  • Query Parameters: page, size, order

Create Bank Account​

  • POST /co2trust-payments/v1/bank-accounts
  • Description: Create a new bank account
  • Auth Required: Yes
  • Request Body: Bank account data

Transfers​

List Transfers​

  • GET /co2trust-payments/v1/transfers
  • Description: List transfers with pagination
  • Auth Required: Yes
  • Query Parameters: page, size, order

Create Transfer​

  • POST /co2trust-payments/v1/transfers
  • Description: Create a new transfer
  • Auth Required: Yes
  • Request Body: Transfer data

Puro Integration​

Inventory​

List Inventory​

  • GET /puro/inventory
  • Description: List carbon credit inventory from Puro registry
  • Auth Required: No
  • Query Parameters:
    • order_by: Sort field
    • credit_type_code: Filter by credit type
    • country_code: Filter by country
    • production_facility_id: Filter by facility
    • issuance_id: Filter by issuance
    • vintage: Filter by vintage
    • page, size

Retirement​

List Retirements​

  • GET /puro/retirement
  • Description: List retirement transactions from Puro registry
  • Auth Required: No
  • Query Parameters: page, size

Sales Channel Services​

Get Credit Types​

  • GET /puro/sales-channel-services/v1/credit-types
  • Description: Get available credit types from Puro
  • Auth Required: No

System Endpoints​

Health Check​

  • GET /health
  • Description: Check API health status
  • Auth Required: No
  • Response: Health status including database and RabbitMQ status

Root​

  • GET /
  • Description: API information and documentation links
  • Auth Required: No

Response Codes​

  • 200 OK: Successful request
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or invalid
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server error

Next Steps​