greencalculus-com Account API

openapi: 3.2.0
info:
  title: GreenCalculus Account API
  version: v1
  description: 'Sourced greenhouse-gas emission factors and audit-traced carbon calculations. Every value returns with its exact source reference and data version — reproducible and citable. Free key at https://greencalculus.com/developers/.


    SCOPE: this document describes every endpoint we publish a callable example for — the data, calculation, discovery and watch endpoints. It deliberately excludes the control plane behind greencalculus.com (billing, sign-in, key management, admin), which is not a customer contract and is free to change, and /v1/account/webhook, whose configuration is session-only by design and therefore cannot be exercised with the bearer token this document describes. Those exclusions are enumerated and enforced by scripts/check-openapi-drift.mjs, so an endpoint is absent here because it was excluded, never because it was forgotten.'
  contact:
    name: GreenCalculus
    url: https://greencalculus.com/developers/
    email: jeremiah@greencalculus.com
  license:
    name: Attribution required except on Enterprise
    url: https://greencalculus.com/developers/docs/#attribution
servers:
- url: https://api.greencalculus.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Account
  description: Watchlists and the reporting-period diff — the alerting half of the API
paths:
  /v1/account/watch:
    get:
      tags:
      - Account
      summary: The factor keys this account is alerted on
      description: Bearer key or signed-in session.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The current watchlist and its cap
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchList'
        '401':
          description: No valid key or session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1AccountWatch
      x-operation-id-source: derived
    post:
      tags:
      - Account
      summary: Watch a factor key
      description: A release that touches the key emails old to new with the versioned verify link. A key that is not in the corpus is REFUSED with 422 rather than accepted as an alert that could never fire.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              properties:
                key:
                  type: string
                  description: A canonical factor key.
                  example: grid.gbr.electricity.location_based
            example:
              key: grid.gbr.electricity.location_based
      responses:
        '200':
          description: The watchlist after the addition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchMutation'
        '400':
          description: No key in the body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No valid key or session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The key is not in the corpus, so watching it would never alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1AccountWatch
      x-operation-id-source: derived
  /v1/account/watch/remove:
    post:
      tags:
      - Account
      summary: Stop watching a factor key
      description: 'POST rather than DELETE: credentialed CORS on this API allows GET and POST only.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              properties:
                key:
                  type: string
                  example: grid.gbr.electricity.location_based
            example:
              key: grid.gbr.electricity.location_based
      responses:
        '200':
          description: The watchlist after the removal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchMutation'
        '400':
          description: No key in the body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No valid key or session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1AccountWatchRemove
      x-operation-id-source: derived
  /v1/account/watch/diff:
    get:
      tags:
      - Account
      summary: What changed for your watched keys between two dates
      description: 'The reporting-period question, answered directly: per key, the value at each boundary, whether it moved, the versions that touched it, and a proof link per side — the evidence a restatement decision needs. A `from` older than the change record clamps to the archive watershed and the response says so.'
      security:
      - bearerAuth: []
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date
        example: '2026-01-01'
      - name: to
        in: query
        schema:
          type: string
          format: date
        description: Defaults to today.
        example: '2026-12-31'
      responses:
        '200':
          description: Per-key boundary values and proof links
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchDiff'
        '400':
          description: Missing or malformed from/to
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No valid key or session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1AccountWatchDiff
      x-operation-id-source: derived
  /v1/account/watch/digest:
    get:
      tags:
      - Account
      summary: Read the summary cadence
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The current cadence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Digest'
        '401':
          description: No valid key or session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1AccountWatchDigest
      x-operation-id-source: derived
    post:
      tags:
      - Account
      summary: Set the summary cadence
      description: 'Off by default. Each edition covers exactly the period since the last one — anchored to itself, so it fits any financial year with no configuration. Quiet periods still send: "your saved figures stand" is the answer a reporting team needs.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cadence
              properties:
                cadence:
                  type: string
                  enum:
                  - 'off'
                  - monthly
                  - quarterly
            example:
              cadence: monthly
      responses:
        '200':
          description: The cadence after the change
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Digest'
        '400':
          description: cadence must be off, monthly or quarterly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No valid key or session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1AccountWatchDigest
      x-operation-id-source: derived
components:
  schemas:
    WatchMutation:
      type: object
      description: The watchlist after the change, and which key moved.
      additionalProperties: true
      properties:
        keys:
          type: array
          items:
            type: string
        added:
          type: string
        removed:
          type: string
    Error:
      type: object
      description: The single error envelope, on every non-2xx response from every endpoint. Stated on /developers/docs and enforced at the gateway for origin-raised errors too — read the code from error.code.
      required:
      - error
      additionalProperties: true
      properties:
        error:
          type: object
          required:
          - code
          - message
          additionalProperties: true
          properties:
            code:
              type: string
              description: 'Stable machine-readable code. Transport-level: unauthorized, forbidden_tier, not_found, rate_limited, quota_exceeded, overage_cap_reached, busy, origin_unavailable, invalid_request. Validation codes are namespaced gc_* and named per endpoint (gc_unknown_param, gc_limit_too_large, gc_offset_invalid, gc_cursor_invalid, gc_section_conflict, and the per-engine gc_<engine>_* set).'
              example: gc_unknown_param
            message:
              type: string
              description: Human-readable and specific — a 4xx names the offending parameter and lists the accepted set.
              example: 'Unknown query parameter: bogus. This endpoint accepts: offset, cursor, limit, section, key_prefix, family, search. Free-text lookup is ?search=.'
            docs:
              type: string
              format: uri
              example: https://greencalculus.com/developers/docs/#errors
            details:
              type: object
              additionalProperties: true
              description: Present only when the failing endpoint attached structured detail beyond the HTTP status.
    WatchDiff:
      type: object
      description: What changed for the watched keys between two dates — the value at each boundary, whether it moved, and a proof link per side. Dates resolve to data versions through the change record; a `from` older than the record clamps to the archive watershed and says so.
      additionalProperties: true
      properties:
        from:
          type: string
        to:
          type: string
        note:
          type: string
          description: Present when there is nothing to diff, or when a boundary was clamped.
        keys:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              key:
                type: string
              from:
                type: object
                additionalProperties: true
                properties:
                  version:
                    type: string
                  value:
                    type:
                    - number
                    - 'null'
                  unit:
                    type:
                    - string
                    - 'null'
                  held:
                    type: boolean
              to:
                type: object
                additionalProperties: true
                properties:
                  version:
                    type: string
                  value:
                    type:
                    - number
                    - 'null'
                  unit:
                    type:
                    - string
                    - 'null'
                  held:
                    type: boolean
              changed:
                type: boolean
              versions_touching:
                type: array
                items:
                  type: string
              proof:
                type: object
                additionalProperties: true
                properties:
                  from:
                    type: string
                  to:
                    type: string
    WatchList:
      type: object
      description: The factor keys this account is alerted on when a release touches them.
      additionalProperties: true
      properties:
        keys:
          type: array
          items:
            type: string
        cap:
          type: integer
          description: Maximum keys per account.
        updated_at:
          type:
          - string
          - 'null'
    Digest:
      type: object
      description: The summary cadence for this account. Off by default. Each edition covers exactly the period since the last one, so it fits any financial year without configuration.
      additionalProperties: true
      properties:
        cadence:
          type: string
          enum:
          - 'off'
          - monthly
          - quarterly
        last_sent:
          type:
          - string
          - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key, e.g. "Bearer gc_live_…". Get one free at https://greencalculus.com/developers/.
externalDocs:
  description: The factor citation specification — the line that travels with every number
  url: https://greencalculus.com/developers/citation/