openapi: 3.0.3
info:
  title: Patch Carbon API
  version: '2'
  description: |
    The Patch API lets developers browse verified carbon projects, generate
    emissions estimates, and place orders for carbon credits and removals.
    Reconstructed from the publicly published patch-python, patch-node, and
    patch-ruby SDKs (auto-generated by openapi-generator from the official
    Patch OpenAPI document).
  contact:
    name: Patch Engineering
    email: engineering@usepatch.com
    url: https://docs.patch.io/
  license:
    name: Proprietary
    url: https://www.patch.io/terms
servers:
  - url: https://api.patch.io
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: Browse and retrieve verified carbon projects across removal and avoidance categories.
  - name: Orders
    description: Place, retrieve, place, and cancel carbon credit and removal orders.
  - name: Order Line Items
    description: Manage individual line items inside a multi-line carbon credit order.
  - name: Technology Types
    description: List the technology and parent technology types backing Patch's carbon project taxonomy.
paths:
  /v1/projects:
    get:
      tags: [Projects]
      operationId: retrieveProjects
      summary: List Projects
      description: Returns a paginated list of verified carbon projects available for purchase through Patch.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: country
          in: query
          schema: { type: string }
          description: ISO 3166-1 alpha-2 country code filter.
        - name: type
          in: query
          schema: { type: string }
          description: Filter by project type slug (for example biomass, dac, mineralization, redd_plus).
        - name: minimum_available_mass
          in: query
          schema: { type: integer }
          description: Minimum available mass (in grams) the project must have in inventory.
      responses:
        '200':
          description: Project list response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProjectListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/projects/{id}:
    get:
      tags: [Projects]
      operationId: retrieveProject
      summary: Retrieve A Project
      description: Returns a single verified carbon project by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Project response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProjectResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/projects/technology_types:
    get:
      tags: [Technology Types]
      operationId: retrieveTechnologyTypes
      summary: List Technology Types
      description: Returns the full taxonomy of project technology types (and parent technology types) used to classify Patch projects.
      responses:
        '200':
          description: Technology type list response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TechnologyTypeListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/orders:
    get:
      tags: [Orders]
      operationId: retrieveOrders
      summary: List Orders
      description: Returns a paginated list of carbon credit and removal orders for the authenticated organization.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: metadata
          in: query
          schema: { type: object, additionalProperties: { type: string } }
          description: Filter orders by metadata key/value pairs set when the order was created.
        - name: state
          in: query
          schema: { type: string, enum: [draft, placed, processing, complete, cancelled] }
      responses:
        '200':
          description: Order list response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Orders]
      operationId: createOrder
      summary: Create An Order
      description: Creates a new carbon credit or removal order. Orders may be created in draft and placed later, or placed inline.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateOrderRequest' }
      responses:
        '200':
          description: Order response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/orders/{id}:
    get:
      tags: [Orders]
      operationId: retrieveOrder
      summary: Retrieve An Order
      description: Returns a single carbon credit or removal order by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Order response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/orders/{uid}:
    delete:
      tags: [Orders]
      operationId: deleteOrder
      summary: Delete An Order
      description: Deletes a draft order. Placed and completed orders cannot be deleted; use the cancel endpoint instead.
      parameters:
        - name: uid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Delete order response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DeleteOrderResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/orders/{id}/place:
    patch:
      tags: [Orders]
      operationId: placeOrder
      summary: Place An Order
      description: Transitions a draft order to placed, committing the credits to the buyer.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Order response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/orders/{id}/cancel:
    patch:
      tags: [Orders]
      operationId: cancelOrder
      summary: Cancel An Order
      description: Cancels a previously placed order where the project allows cancellation.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Order response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/orders/{order_id}/line_items:
    post:
      tags: [Order Line Items]
      operationId: createOrderLineItem
      summary: Create An Order Line Item
      description: Adds a new line item to a draft order tying a specific project, vintage, and quantity to the order.
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateOrderLineItemRequest' }
      responses:
        '200':
          description: Order line item response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderLineItemResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/orders/{order_id}/line_items/{serial_number}:
    patch:
      tags: [Order Line Items]
      operationId: updateOrderLineItem
      summary: Update An Order Line Item
      description: Updates an existing line item on a draft order.
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
        - name: serial_number
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateOrderLineItemRequest' }
      responses:
        '200':
          description: Order line item response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderLineItemResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Order Line Items]
      operationId: deleteOrderLineItem
      summary: Delete An Order Line Item
      description: Removes a line item from a draft order.
      parameters:
        - name: order_id
          in: path
          required: true
          schema: { type: string }
        - name: serial_number
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Order line item response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderLineItemResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key bearer token issued from the Patch dashboard. Sandbox and live keys are separated.
  parameters:
    PageParam:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
      description: 1-indexed page number for paginated responses.
  responses:
    BadRequest:
      description: Request was malformed or failed validation.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Unauthorized:
      description: API key missing, malformed, or invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
  schemas:
    Meta:
      type: object
      description: Pagination and response metadata block returned on list endpoints.
      properties:
        prev_page: { type: integer, nullable: true }
        next_page: { type: integer, nullable: true }
    ErrorResponse:
      type: object
      properties:
        success: { type: boolean, example: false }
        error:
          type: object
          properties:
            code: { type: integer }
            message: { type: string }
        data: { nullable: true }
        meta:
          type: object
          properties:
            patch_version: { type: integer }
    Photo:
      type: object
      properties:
        id: { type: string }
        url: { type: string, format: uri }
    Sdg:
      type: object
      description: UN Sustainable Development Goal alignment.
      properties:
        number: { type: integer }
        title: { type: string }
        description: { type: string }
    Standard:
      type: object
      description: Carbon registry / standard the project is certified under (Verra, Gold Standard, Puro, ACR, CAR, etc.).
      properties:
        type: { type: string }
        acronym: { type: string }
    Highlight:
      type: object
      properties:
        headline: { type: string }
        details: { type: string }
    Inventory:
      type: object
      description: Available inventory broken out by vintage and price.
      properties:
        vintage_year: { type: integer, nullable: true }
        vintage_start_year: { type: integer, nullable: true }
        vintage_end_year: { type: integer, nullable: true }
        amount_available: { type: integer, description: "Available mass in grams." }
        price: { type: integer, description: "Per-tonne price in minor currency units." }
        currency: { type: string, example: USD }
    Disclaimer:
      type: object
      properties:
        title: { type: string }
        body: { type: string }
    ParentTechnologyType:
      type: object
      properties:
        slug: { type: string }
        name: { type: string }
    TechnologyType:
      type: object
      properties:
        slug: { type: string, example: dac }
        name: { type: string, example: Direct Air Capture }
        parent_technology_type: { $ref: '#/components/schemas/ParentTechnologyType' }
    Project:
      type: object
      description: A verified carbon project listed on Patch.
      properties:
        id: { type: string }
        production: { type: boolean }
        name: { type: string }
        description: { type: string }
        mechanism: { type: string, description: "Removal or avoidance." }
        country: { type: string }
        state: { type: string }
        issuance_type: { type: string }
        latitude: { type: number, format: float }
        longitude: { type: number, format: float }
        project_partner: { type: string }
        photos: { type: array, items: { $ref: '#/components/schemas/Photo' } }
        verifier: { type: string }
        standard: { $ref: '#/components/schemas/Standard' }
        sdgs: { type: array, items: { $ref: '#/components/schemas/Sdg' } }
        tagline: { type: string }
        technology_type: { $ref: '#/components/schemas/TechnologyType' }
        highlights: { type: array, items: { $ref: '#/components/schemas/Highlight' } }
        inventory: { type: array, items: { $ref: '#/components/schemas/Inventory' } }
        disclaimers: { type: array, items: { $ref: '#/components/schemas/Disclaimer' } }
    ProjectListResponse:
      type: object
      properties:
        success: { type: boolean }
        error: { nullable: true }
        data: { type: array, items: { $ref: '#/components/schemas/Project' } }
        meta: { $ref: '#/components/schemas/Meta' }
    ProjectResponse:
      type: object
      properties:
        success: { type: boolean }
        error: { nullable: true }
        data: { $ref: '#/components/schemas/Project' }
        meta: { $ref: '#/components/schemas/Meta' }
    OrderIssuedTo:
      type: object
      description: End beneficiary that credits should be issued and attributed to.
      properties:
        name: { type: string }
        email: { type: string, format: email }
    OrderLineItemProject:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
    OrderLineItem:
      type: object
      properties:
        id: { type: string }
        project: { $ref: '#/components/schemas/OrderLineItemProject' }
        vintage_year: { type: integer, nullable: true }
        vintage_start_year: { type: integer, nullable: true }
        vintage_end_year: { type: integer, nullable: true }
        amount: { type: integer, description: "Mass in grams." }
        unit: { type: string, example: g }
        price: { type: integer }
        currency: { type: string, example: USD }
    Order:
      type: object
      properties:
        id: { type: string }
        created_at: { type: string, format: date-time }
        production: { type: boolean }
        state: { type: string, enum: [draft, placed, processing, complete, cancelled] }
        amount: { type: integer, description: "Total mass in grams." }
        unit: { type: string, example: g }
        price: { type: integer, description: "Subtotal in minor currency units." }
        patch_fee: { type: integer }
        currency: { type: string, example: USD }
        registry_url: { type: string, format: uri, nullable: true }
        metadata: { type: object, additionalProperties: true }
        line_items: { type: array, items: { $ref: '#/components/schemas/OrderLineItem' } }
        issued_to: { $ref: '#/components/schemas/OrderIssuedTo' }
    CreateOrderRequest:
      type: object
      properties:
        project_id: { type: string }
        metadata: { type: object, additionalProperties: true }
        state: { type: string, enum: [draft, placed] }
        vintage_year: { type: integer }
        vintage_start_year: { type: integer }
        vintage_end_year: { type: integer }
        total_price: { type: integer }
        currency: { type: string, example: USD }
        amount: { type: integer }
        unit: { type: string, example: g }
        issued_to: { $ref: '#/components/schemas/OrderIssuedTo' }
    CreateOrderLineItemRequest:
      type: object
      required: [project_id]
      properties:
        project_id: { type: string }
        vintage_year: { type: integer }
        vintage_start_year: { type: integer }
        vintage_end_year: { type: integer }
        price: { type: integer }
        currency: { type: string, example: USD }
        amount: { type: integer }
        unit: { type: string, example: g }
    UpdateOrderLineItemRequest:
      type: object
      properties:
        vintage_year: { type: integer }
        vintage_start_year: { type: integer }
        vintage_end_year: { type: integer }
        price: { type: integer }
        currency: { type: string, example: USD }
        amount: { type: integer }
        unit: { type: string, example: g }
    OrderResponse:
      type: object
      properties:
        success: { type: boolean }
        error: { nullable: true }
        data: { $ref: '#/components/schemas/Order' }
        meta: { $ref: '#/components/schemas/Meta' }
    OrderListResponse:
      type: object
      properties:
        success: { type: boolean }
        error: { nullable: true }
        data: { type: array, items: { $ref: '#/components/schemas/Order' } }
        meta: { $ref: '#/components/schemas/Meta' }
    OrderLineItemResponse:
      type: object
      properties:
        success: { type: boolean }
        error: { nullable: true }
        data: { $ref: '#/components/schemas/OrderLineItem' }
        meta: { $ref: '#/components/schemas/Meta' }
    DeleteOrderResponse:
      type: object
      properties:
        success: { type: boolean }
        error: { nullable: true }
        data: { nullable: true }
        meta: { $ref: '#/components/schemas/Meta' }
    TechnologyTypeListResponse:
      type: object
      properties:
        success: { type: boolean }
        error: { nullable: true }
        data: { type: array, items: { $ref: '#/components/schemas/TechnologyType' } }
        meta: { $ref: '#/components/schemas/Meta' }