{
  "openapi": "3.1.0",
  "info": {
    "title": "Oncra Registry API",
    "version": "1.0.0",
    "summary": "Read access to the projects, ledgers and certificates of the Oncra Registry.",
    "description": "The Oncra Registry publishes every project, every ledger entry and every certificate. This API returns the same data the registry website shows, as JSON.\n\nConventions:\n- Quantities of CO2e are in **kilograms**; divide by 1000 for tonnes.\n- Dates are Unix time in **milliseconds**, UTC.\n- Prices are in **euro cents**.\n- Responses are JSON, UTF-8. Public endpoints need no key.\n- Use /projects.json to see which projects changed since your last call, and only fetch those.",
    "contact": {
      "name": "Oncra",
      "url": "https://oncra.org",
      "email": "info@oncra.org"
    }
  },
  "servers": [
    {
      "url": "https://registry.oncra.org",
      "description": "Oncra Registry"
    }
  ],
  "externalDocs": {
    "description": "Human-readable guide",
    "url": "https://registry.oncra.org/developers"
  },
  "tags": [
    {
      "name": "Projects",
      "description": "Registered carbon removal projects."
    },
    {
      "name": "Ledger",
      "description": "Every issuance, transfer, retirement and reversal per project."
    },
    {
      "name": "Certificates",
      "description": "Certificates issued to buyers."
    },
    {
      "name": "Account",
      "description": "Your own holdings. Needs a personal API token."
    }
  ],
  "paths": {
    "/projects.json": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "listProjectChanges",
        "summary": "List all public projects with their last update time",
        "description": "Lightweight change feed. Compare last_updated_at_millis with your copy and fetch only the projects that changed.",
        "responses": {
          "200": {
            "description": "All public project ids with a change timestamp.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "logged_in": {
                      "type": "boolean"
                    },
                    "notes": {
                      "type": "string"
                    },
                    "projects": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProjectChange"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}/details.json": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getProjectDetails",
        "summary": "Project details",
        "description": "Project metadata (remover, pathway, methods, location, area, certification status, labels) and the public project and remover descriptions as HTML.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric project id. Resolve a public project number (e.g. BBL-L-001) with /api/projects/by-nr/{nr}.",
            "schema": {
              "type": "integer"
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "Project details.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "logged_in": {
                      "type": "boolean"
                    },
                    "notes": {
                      "type": "string"
                    },
                    "project": {
                      "$ref": "#/components/schemas/Project"
                    },
                    "details_html": {
                      "type": "string"
                    },
                    "remover_html": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown or non-public project."
          }
        }
      }
    },
    "/projects/{id}/ledger.json": {
      "get": {
        "tags": [
          "Ledger"
        ],
        "operationId": "getProjectLedger",
        "summary": "Project ledger",
        "description": "The full transaction history of a project. Each row is a transaction; sub_rows are its booking lines and sum up to the row. Certificate numbers appear on the row only. tfoot holds the project totals.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric project id. Resolve a public project number (e.g. BBL-L-001) with /api/projects/by-nr/{nr}.",
            "schema": {
              "type": "integer"
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "Ledger table.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "logged_in": {
                      "type": "boolean"
                    },
                    "notes": {
                      "type": "string"
                    },
                    "table": {
                      "type": "object",
                      "properties": {
                        "tbody": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/LedgerRow"
                          }
                        },
                        "tfoot": {
                          "$ref": "#/components/schemas/LedgerTotals"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown or non-public project."
          }
        }
      }
    },
    "/api/projects": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "searchProjects",
        "summary": "Search and filter projects (paged)",
        "description": "The project list as shown on the registry home page, 12 per page, with registry-wide totals in stat.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Zero-based page number."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Text search on project name, project number and remover name."
          },
          {
            "name": "f_pathway",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Pathway ids separated by | (1 construction, 2 land, 3 ocean, 4 rock).",
            "example": "2|3"
          },
          {
            "name": "f_loc",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only projects whose location contains this text."
          },
          {
            "name": "f_vintage",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1971
            },
            "description": "Only projects whose vintage range includes this year."
          },
          {
            "name": "label_icvcm",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Only projects carrying the ICVCM label."
          },
          {
            "name": "label_crcf",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Only projects carrying the CRCF label."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "created",
                "random"
              ],
              "default": "random"
            }
          },
          {
            "name": "reverse",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Reverse the sort order."
          }
        ],
        "responses": {
          "200": {
            "description": "One page of projects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProjectCard"
                      }
                    },
                    "list_of_removers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "has_next": {
                      "type": "boolean"
                    },
                    "totalPages": {
                      "type": "integer"
                    },
                    "stat": {
                      "$ref": "#/components/schemas/Stat"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/projects/map": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "listProjectLocations",
        "summary": "All public projects with coordinates",
        "responses": {
          "200": {
            "description": "Projects with latitude and longitude.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProjectLocation"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/projects/by-nr/{nr}": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "resolveProjectNr",
        "summary": "Resolve a project number to its id",
        "parameters": [
          {
            "name": "nr",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "BBL-L-001"
          }
        ],
        "responses": {
          "200": {
            "description": "The project id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "nr": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "id": 2,
                  "nr": "BBL-L-001"
                }
              }
            }
          },
          "404": {
            "description": "No project with this number."
          }
        }
      }
    },
    "/api/certificate/{nr}/": {
      "get": {
        "tags": [
          "Certificates"
        ],
        "operationId": "getCertificate",
        "summary": "Verify a certificate",
        "description": "Returns who the certificate was presented to, for which project, how much CO2e and its current status, plus a link to the PDF. The certificate number is printed on every certificate and appears in the project ledger.",
        "parameters": [
          {
            "name": "nr",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "ARB-O-001-1-1"
          }
        ],
        "responses": {
          "200": {
            "description": "Certificate data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Certificate"
                }
              }
            }
          },
          "404": {
            "description": "Unknown or non-public certificate."
          }
        }
      }
    },
    "/account/wallet.json": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getMyWallet",
        "summary": "Your holdings",
        "description": "Units held by the account that owns the token. Vintage 0 means no specific vintage.",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet tables.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          }
        }
      }
    },
    "/api/users/me": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getMe",
        "summary": "The account behind the token",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Personal API token. Create one when signed in under Account → API tokens, and send it as 'Authorization: Bearer <token>'."
      }
    },
    "schemas": {
      "ProjectChange": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "last_updated_at_millis": {
            "type": "integer",
            "description": "Unix ms, UTC."
          }
        }
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "nr": {
            "type": "string",
            "description": "Public project number, e.g. BBL-L-001."
          },
          "name": {
            "type": "string"
          },
          "remover": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "pathway_id": {
            "type": "integer",
            "enum": [
              1,
              2,
              3,
              4
            ]
          },
          "pathway": {
            "type": "string"
          },
          "methods": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "area": {
            "type": "number"
          },
          "area_unit": {
            "type": "string",
            "description": "ha, m2 or m3."
          },
          "location": {
            "type": "string"
          },
          "country_code": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2."
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "start_date": {
            "type": "integer",
            "description": "Start year."
          },
          "certification_status": {
            "type": "string",
            "enum": [
              "pre_validated",
              "validated",
              "verified"
            ]
          },
          "label_icvcm": {
            "type": "boolean"
          },
          "label_crcf": {
            "type": "boolean"
          },
          "images": {
            "type": "string",
            "description": "JSON-encoded array of image ids."
          }
        }
      },
      "ProjectCard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "nr": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "pathway_id": {
            "type": "integer"
          },
          "pathway": {
            "type": "string"
          },
          "methods": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "area": {
            "type": "number"
          },
          "area_unit": {
            "type": "string"
          },
          "label_icvcm": {
            "type": "boolean"
          },
          "label_crcf": {
            "type": "boolean"
          }
        }
      },
      "ProjectLocation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "nr": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "pathway_id": {
            "type": "integer"
          },
          "pathway": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "methods": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "LedgerEntry": {
        "type": "object",
        "properties": {
          "transfer_id": {
            "type": "string",
            "description": "Unique, immutable transfer id."
          },
          "date": {
            "type": "integer",
            "description": "Unix ms, UTC."
          },
          "vintage": {
            "type": "integer",
            "description": "Vintage year; 0 when not vintage-specific."
          },
          "code": {
            "type": "integer",
            "enum": [
              100,
              101,
              102,
              103,
              104,
              110,
              111,
              112,
              113,
              114,
              120,
              121,
              130,
              132
            ],
            "description": "100 = Concept, 101 = Holding, 102 = PendingCommonHolding, 103 = Issue, 104 = CommonHoldingIn, 110 = Broker, 111 = BrokerPurchase, 112 = Purchase, 113 = PurchaseRetire, 114 = Reserve, 120 = Void, 121 = Revert, 130 = Deliver, 132 = CommonHoldingOut"
          },
          "holding": {
            "type": "integer",
            "description": "kg CO2e"
          },
          "potential": {
            "type": "integer",
            "description": "kg CO2e"
          },
          "available": {
            "type": "integer",
            "description": "kg CO2e"
          },
          "purchased": {
            "type": "integer",
            "description": "kg CO2e"
          },
          "delivered": {
            "type": "integer",
            "description": "kg CO2e"
          },
          "retired": {
            "type": "integer",
            "description": "kg CO2e"
          },
          "certificate": {
            "type": "string",
            "description": "Certificate number, on the row only."
          },
          "certificate_amount": {
            "type": "integer",
            "description": "kg CO2e"
          },
          "certificate_status": {
            "type": "string"
          },
          "to": {
            "type": "object",
            "description": "Receiving account; private accounts are not named.",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "private": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "LedgerRow": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "row": {
            "$ref": "#/components/schemas/LedgerEntry"
          },
          "sub_rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LedgerEntry"
            }
          }
        }
      },
      "LedgerTotals": {
        "type": "object",
        "properties": {
          "project_total": {
            "type": "object",
            "description": "Totals per account status, kg CO2e.",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "vintage_totals": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Stat": {
        "type": "object",
        "description": "Registry-wide totals, kg CO2e.",
        "additionalProperties": {
          "type": "number"
        }
      },
      "Certificate": {
        "type": "object",
        "properties": {
          "certificate_nr": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "DD/MM/YYYY"
          },
          "presented_to": {
            "type": "string"
          },
          "project_id": {
            "type": "integer"
          },
          "project_nr": {
            "type": "string"
          },
          "project_name": {
            "type": "string"
          },
          "remover_name": {
            "type": "string"
          },
          "oncra_protocol": {
            "type": "string"
          },
          "transaction_id": {
            "type": "string",
            "description": "Matches transfer_id in the project ledger."
          },
          "total_co2_kg": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          },
          "certificate_pdf_url": {
            "type": "string"
          }
        }
      }
    }
  }
}