BigCommerce Cart Items API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Cart Items API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Cart Items
paths:
  /carts/{cartId}/items:
    post:
      tags:
      - Cart Items
      summary: BigCommerce Add Cart Line Items
      description: "Adds a line items to the *Cart*.\n\n> #### Notes\n> * Substitute your storefront domain for `yourstore.example.com`. \n> * The Send a Test Request feature is not currently supported for this endpoint.  \n> * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results."
      operationId: addCartLineItem
      parameters:
      - name: cartId
        in: path
        description: This cart's unique ID.
        required: true
        schema:
          type: string
          format: UUID
      - name: include
        in: query
        description: 'To return product options add one of the following include:


          `lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return physical items product options. Can also be used in a /POST to have the extended Cart object return.


          `lineItems.digitalItems.options`:  The Cart returns an abbreviated result. Use this to return digital items product options.  Can also be used in a /POST to have the extended Cart object return.


          `lineItems.digitalItems.options,lineItems.physicalItems.options`:  The Cart returns an abbreviated result. Use this to return digital and physical options. Can also be used in a /POST to have the extended Cart object return.'
        schema:
          type: string
          default: lineItems.digitalItems.options,lineItems.physicalItems.options
          enum:
          - lineItems.physicalItems.options
          - lineItems.digitalItems.options
          - lineItems.digitalItems.options,lineItems.physicalItems.options
      responses:
        '200':
          $ref: '#/components/responses/postCartsItems'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineItemsRequest'
            examples:
              With Option Selections:
                value:
                  lineItems:
                  - quantity: 2
                    productId: 230
                    variantId: 124
                    optionSelections:
                    - optionId: 10
                      optionValue: 117
                    - optionId: 11
                      optionValue: 125
              With Gift Wrapping:
                value:
                  lineItems:
                  - quantity: 2
                    productId: 230
                    variantId: 124
                    giftWrapping:
                      wrapTogether: true
                      wrapDetails:
                      - id: 1
                        message: Happy Birthday
        description: ''
  /carts/{cartId}/items/{itemId}:
    put:
      tags:
      - Cart Items
      summary: BigCommerce Update Cart Line Item
      description: "Updates a *Cart* line item. Updates an existing, single line item quantity and the price of custom items in a cart.\n\nIf a modified product or variant needs to be changed or updated, you can remove and re-add the product to the cart with the correct variants using the [Delete Cart Line Item](/docs/rest-storefront/carts/cart-items#delete-cart-line-item) and the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoints. You can also use carts mutations that are part of the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront).\n\n\n> #### Notes\n> * Substitute your storefront domain for `yourstore.example.com`. \n> * The Send a Test Request feature is not currently supported for this endpoint. \n> * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results."
      operationId: updateCartLineItem
      parameters:
      - name: cartId
        in: path
        description: This cart's unique ID.
        required: true
        schema:
          type: string
          format: UUID
      - name: itemId
        in: path
        description: This item's ID.
        required: true
        schema:
          type: string
          format: number
      - name: include
        in: query
        description: 'To return product options add one of the following include:


          `lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return physical items product options. Can also be used in a /POST to have the extended Cart object return.


          `lineItems.digitalItems.options`:  The Cart returns an abbreviated result. Use this to return digital items product options.  Can also be used in a /POST to have the extended Cart object return.


          `lineItems.digitalItems.options,lineItems.physicalItems.options`:  The Cart returns an abbreviated result. Use this to return digital and physical options. Can also be used in a /POST to have the extended Cart object return.'
        schema:
          type: string
          default: lineItems.digitalItems.options,lineItems.physicalItems.options
          enum:
          - lineItems.physicalItems.options
          - lineItems.digitalItems.options
          - lineItems.digitalItems.options,lineItems.physicalItems.options
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestLineItemPut'
            examples:
              Variant Item:
                value:
                  lineItem:
                    productId: 229
                    variantId: 191
                    quantity: 10
                  locale: en
              Custom Item:
                value:
                  lineItem:
                    productId: 118
                    variantId: 140
                    quantity: 10
                    optionSelections:
                    - optionId: 125
                      optionValue: 127
                  locale: en
              With Gift Wrapping:
                value:
                  lineItem:
                    quantity: 2
                    productId: 230
                    variantId: 124
                    giftWrapping:
                      wrapTogether: true
                      wrapDetails:
                      - id: 1
                        message: Happy Birthday
              With null Gift Wrapping (will delete current gift wrapping):
                value:
                  lineItem:
                    quantity: 2
                    productId: 230
                    variantId: 124
                    giftWrapping: null
        required: true
      responses:
        '200':
          $ref: '#/components/responses/putCartsItems'
      x-codegen-request-body-name: lineItem
    delete:
      tags:
      - Cart Items
      summary: BigCommerce Delete Cart Line Item
      description: "Deletes a *Cart* line item.\n\nRemoving the last `line_item` in the *Cart* deletes the *Cart*.\n\n> #### Note\n> * Substitute your storefront domain for `yourstore.example.com`. \n> * The Send a Test Request feature is not currently supported for this endpoint.  "
      operationId: deleteCartLineItem
      parameters:
      - name: cartId
        in: path
        description: This cart's unique ID.
        required: true
        schema:
          type: string
          format: UUID
      - name: itemId
        in: path
        description: The ID of the item to delete.
        required: true
        schema:
          type: string
          format: number
      - name: include
        in: query
        description: 'To return product options add one of the following include:


          `lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return physical items product options. Can also be used in a /POST to have the extended Cart object return.


          `lineItems.digitalItems.options`:  The Cart returns an abbreviated result. Use this to return digital items product options.  Can also be used in a /POST to have the extended Cart object return.


          `lineItems.digitalItems.options,lineItems.physicalItems.options`:  The Cart returns an abbreviated result. Use this to return digital and physical options. Can also be used in a /POST to have the extended Cart object return.'
        schema:
          type: string
          default: lineItems.digitalItems.options,lineItems.physicalItems.options
          enum:
          - lineItems.physicalItems.options
          - lineItems.digitalItems.options
          - lineItems.digitalItems.options,lineItems.physicalItems.options
      responses:
        '200':
          $ref: '#/components/responses/deleteCartsItems'
components:
  schemas:
    requestLineItemGiftCertificateRecipient:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    responseCartLineItemsPhysicalItemGiftWrapping:
      title: Gift Wrapping
      type: object
      properties:
        amount:
          type: number
          description: Gift-wrapping price per product.
          format: float
        message:
          type: string
        name:
          type: string
          description: Name of the gift-wrapping option.
      nullable: true
      x-internal: false
    responseCartLineItemsDigitalItems:
      title: Item Digital
      allOf:
      - $ref: '#/components/schemas/responseCartLineItemsDigitalItemsAllOf0'
      x-internal: false
    responseCartLineItemsCustomItems:
      title: Item Custom
      type: object
      properties:
        extendedListPrice:
          type: integer
          readOnly: true
        id:
          type: string
          description: ID of the custom item
          readOnly: true
          example: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff
        listPrice:
          type: integer
          description: Price of the item. With or without tax depending on your stores set up.
          readOnly: true
          example: 10
        name:
          type: string
          description: Name of the custom item.
          readOnly: true
          example: Custom Item Name
        quantity:
          type: integer
          readOnly: true
          example: 1
        sku:
          type: string
          description: SKU of the custom item.
          readOnly: true
          example: SM-456
      description: '**Read Only**


        This will return in the Cart Response if the Cart was created using the [REST Management API](/docs/rest-management/carts). A custom item can only be added to a cart using the REST Management API.'
      x-internal: false
    responseCartCurrency:
      title: Currency
      type: object
      properties:
        code:
          type: string
          description: 'ISO-4217 currency code. (See: http://en.wikipedia.org/wiki/ISO_4217.)'
          format: ISO-4217
      description: This will always be the same between cart and checkout.
      x-go-gen-location: models
      x-internal: false
    requestLineItemPut:
      title: requestLineItemPut
      oneOf:
      - properties:
          lineItem:
            $ref: '#/components/schemas/requestCartPostLineItem'
        required:
        - lineItem
        title: Line item
      - properties:
          giftCertificates:
            $ref: '#/components/schemas/requestLineItemGiftCertificate'
        required:
        - giftCertificates
        title: Gift certificate item
      - properties:
          lineItem:
            $ref: '#/components/schemas/requestCartPostLineItem'
          giftCertificates:
            $ref: '#/components/schemas/requestLineItemGiftCertificate'
        required:
        - lineItem
        - giftCertificates
        title: line & gift certificate items
      description: ''
      type: object
      x-internal: false
    LineItemsRequest:
      title: requestLineItems
      oneOf:
      - properties:
          lineItems:
            type: array
            items:
              $ref: '#/components/schemas/requestCartPostLineItem'
        required:
        - lineItems
      - properties:
          giftCertificates:
            type: array
            items:
              $ref: '#/components/schemas/requestLineItemGiftCertificate'
        required:
        - giftCertificates
      - properties:
          lineItems:
            type: array
            items:
              $ref: '#/components/schemas/requestCartPostLineItem'
          giftCertificates:
            $ref: '#/components/schemas/requestLineItemGiftCertificate'
        required:
        - lineItems
        - giftCertificates
      type: object
      description: Cart object used in add items requests.
      x-internal: false
    responseCartLineItemsGiftCertificatesSender:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    responseCartLineItemsItemsPhysicalItemsItems:
      title: Item Physical
      allOf:
      - $ref: '#/components/schemas/responseCartBaseItem'
      - $ref: '#/components/schemas/responseCartLineItemsItemsPhysicalItemsItemsAllOf1'
      x-internal: false
    responseCartCoupons:
      title: Response Cart Coupons
      type: array
      items:
        required:
        - code
        type: object
        properties:
          code:
            type: string
            description: The coupon code.
          couponType:
            type: integer
            description: '|Type `int`|Type Name|

              |-|-|

              |`0`|`per_item_discount`|

              |`1`|`percentage_discount`|

              |`2`|`per_total_discount`|

              |`3`|`shipping_discount`|

              |`4`|`free_shipping`|

              |`5`|`promotion`|'
          discountedAmount:
            type: number
            description: The discounted amount applied within a given context.
            format: float
          id:
            type: string
            description: The coupon ID.
      x-internal: false
    responseCartLineItemsItemsPhysicalItemsItemsAllOf0OptionsItems:
      title: Product Option
      type: object
      properties:
        name:
          type: string
          description: The product option name. For example, Color or Size
        nameId:
          type: number
          description: The product option identifier. It is the same as the `optionId` used in the request.
          example: 125
        value:
          type: string
          description: The product option value. For example, Red or Medium
        valueId:
          type: number
          description: The product option value identifier. It is the same as the `optionValue` used in the request.
          example: 127
      x-internal: false
    responseCartLineItemsItemsPhysicalItemsItemsAllOf1:
      type: object
      properties:
        giftWrapping:
          $ref: '#/components/schemas/responseCartLineItemsPhysicalItemGiftWrapping'
        isShippingRequired:
          type: boolean
          description: Whether this item requires shipping to a physical address.
      x-internal: false
    responseCartBaseItem:
      title: Base Item
      type: object
      properties:
        options:
          type: array
          description: The list of selected options for this product.
          items:
            $ref: '#/components/schemas/responseCartLineItemsItemsPhysicalItemsItemsAllOf0OptionsItems'
        brand:
          type: string
          description: The products brand
        couponAmount:
          type: number
          description: The total value of all coupons applied to this item.
        discountAmount:
          type: number
          description: The total value of all discounts applied to this item (excluding coupon).
          format: float
        discounts:
          $ref: '#/components/schemas/responseCartDiscounts'
        extendedListPrice:
          type: number
          description: Item's list price multiplied by the quantity.
        extendedSalePrice:
          type: number
          description: Item's sale price multiplied by the quantity.
        id:
          type: string
          description: The line-item ID.
          example: '4'
        imageUrl:
          type: string
          description: URL of an image of this item, accessible on the internet.
          format: uri
        isTaxable:
          type: boolean
          description: Whether the item is taxable.
        listPrice:
          type: number
          description: The net item price before discounts and coupons. BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel.
        originalPrice:
          type: number
          description: An item’s original price is the same as the product default price in the admin panel.
        name:
          type: string
          description: The item's product name.
        parentId:
          type: number
          description: The product is part of a bundle such as a product pick list, then the parentId or the main product id will populate.
          example: 6
        productId:
          type: number
          description: ID of the product.
        quantity:
          type: number
          description: Quantity of this item.
        salePrice:
          type: number
          description: Item's price after all discounts are applied. (The final price before tax calculation.)
        sku:
          type: string
          description: SKU of the variant.
        url:
          type: string
          description: The product URL.
          format: uri
        variantId:
          type: number
          description: ID of the variant.
          example: 7
      required:
      - quantity
      x-internal: false
    responseCartLineItemsDigitalItemsAllOf0DiscountsItems:
      title: Applied Discount
      type: object
      properties:
        discountedAmount:
          type: number
          description: The discounted amount applied within a given context.
          format: float
        id:
          type: number
          description: ID of the applied discount.
      x-internal: false
    requestPostOrPutGiftWrapping:
      title: Gift Wrapping Request Data
      required:
      - wrapTogether
      - wrapDetails
      type: object
      nullable: true
      description: if passing null, it will remove the current gift wrapping for the item
      properties:
        wrapTogether:
          type: boolean
          description: Boolean value that specifies whether items whether items should be wrapped together or wrapped individually.
          example: true
        wrapDetails:
          type: array
          description: "Details for the gift wrapping option selected. This can be specified for each line item or together based on wrapTogether value.\nIf wrapTogether is false, each element in the wrapDetails array determines each item's specific wrapping. \n(e.g if this line item has 6 quantity, you can pass at maximum 6 elements for the array to spefified each one's wrapping)  \nIf wrapTogether is true, we will only use 1st element in the wrapDetails array to determine what to be wrapped"
          items:
            type: object
            required:
            - id
            properties:
              id:
                type: integer
                description: Identifier of the gift wrapping option selected.
                example: 0
              message:
                type: string
                description: Custom gift message.
                example: Happy Birthday
    responseCartLineItems:
      title: Response Line Items Object
      type: object
      properties:
        customItems:
          type: array
          items:
            $ref: '#/components/schemas/responseCartLineItemsCustomItems'
        digitalItems:
          type: array
          description: Array of `ItemDigital` objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsDigitalItems'
        giftCertificates:
          type: array
          description: Array of `ItemGiftCertificate` objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsGiftCertificates'
        physicalItems:
          type: array
          description: Array of `ItemPhysical` objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsItemsPhysicalItemsItems'
      x-internal: false
    responseCartLineItemsGiftCertificates:
      title: Item Gift Certificate
      required:
      - amount
      - recipient
      - sender
      - theme
      type: object
      properties:
        amount:
          type: number
          description: Value must be between 1.00 and 1,000.00 in the storeʼs default currency.
        id:
          type: string
          description: ID of this gift certificate.
        isTaxable:
          type: boolean
          description: Whether or not the gift certificate is taxable.
        message:
          type: string
          description: Message that will be sent to the gift certificate's recipient. Limited to 200 characters.
        name:
          type: string
          description: GiftCertificate-provided name that will appear in the control panel.
        recipient:
          $ref: '#/components/schemas/responseCartLineItemsGiftCertificatesRecipient'
        sender:
          $ref: '#/components/schemas/responseCartLineItemsGiftCertificatesSender'
        theme:
          type: string
          description: Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.
      x-internal: false
    responseCartLineItemsGiftCertificatesRecipient:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    requestCartPostLineItem:
      title: Line Item Request Data
      anyOf:
      - properties:
          productId:
            type: number
            description: ID of the product.
          quantity:
            type: number
            description: Quantity of this item.
          giftWrapping:
            $ref: '#/components/schemas/requestPostOrPutGiftWrapping'
        required:
        - productId
        - quantity
        title: Simple product
      - properties:
          productId:
            type: number
            description: ID of the product.
          quantity:
            type: number
            description: Quantity of this item.
          variantId:
            type: number
            description: ID of the variant.
          giftWrapping:
            $ref: '#/components/schemas/requestPostOrPutGiftWrapping'
        required:
        - productId
        - quantity
        - variantId
        title: Product with a variant
      x-examples:
        example-1:
          productId: 0
          quantity: 0
      x-internal: false
      type: object
    responseCartDiscounts:
      title: responseCartDiscounts
      type: array
      items:
        type: object
        properties:
          discountedAmount:
            type: number
            description: The discounted amount applied within a given context.
            format: float
          id:
            type: string
            description: ID of the applied discount.
      x-internal: false
    requestLineItemGiftCertificateSender:
      title: Contact Entity
      type: object
      properties:
        email:
          type: string
          description: Contact's email address.
          format: email
        name:
          type: string
          description: Contact's name.
      x-internal: false
    requestLineItemGiftCertificate:
      title: Line Item Gift Certificate Request Data
      required:
      - amount
      - name
      - quantity
      - recipient
      - sender
      - theme
      type: object
      properties:
        amount:
          maximum: 1000
          minimum: 1
          type: number
          description: Gift-certificate amount.
        message:
          type: string
          description: Message shown to recipient, as provided by sender.
        name:
          type: string
          description: Name assigned to this gift-certificate line item.
        quantity:
          minimum: 1
          type: integer
          description: Quantity of this item.
        recipient:
          $ref: '#/components/schemas/requestLineItemGiftCertificateRecipient'
        sender:
          $ref: '#/components/schemas/requestLineItemGiftCertificateSender'
        theme:
          type: string
          description: Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.
      x-internal: false
    responseCartLineItemsDigitalItemsAllOf0OptionsItems:
      title: Product Option
      type: object
      properties:
        name:
          type: string
          description: The product option name. For example, Color or Size
        nameId:
          type: number
          description: 'The product option identifier. It is the same as the `optionId` used in the request. '
          example: 125
        value:
          type: string
          description: The product option value. For example, Red or Medium
        valueId:
          type: number
          description: The product option value identifier. It is the same as the `optionValue` used in the request.
          example: 127
      x-internal: false
    responseCartLineItemsDigitalItemsAllOf0:
      title: Base Item
      required:
      - quantity
      type: object
      properties:
        options:
          type: array
          description: The list of selected options for this product.
          items:
            $ref: '#/components/schemas/responseCartLineItemsDigitalItemsAllOf0OptionsItems'
        brand:
          type: string
          description: The products brand
        couponAmount:
          type: number
          description: The total value of all coupons applied to this item.
        discountAmount:
          type: number
          description: The total value of all discounts applied to this item (excluding coupon).
          format: float
        discounts:
          type: array
          description: List of discounts applied to this item, as an array of AppliedDiscount objects.
          items:
            $ref: '#/components/schemas/responseCartLineItemsDigitalItemsAllOf0DiscountsItems'
        extendedListPrice:
          type: number
          description: Item's list price multiplied by the quantity.
        extendedSalePrice:
          type: number
          description: Item's sale price multiplied by the quantity.
        id:
          type: string
          description: The line-item ID.
          example: '4'
        imageUrl:
          type: string
          description: URL of an image of this item, accessible on the internet.
          format: uri
        isTaxable:
          type: boolean
          description: Whether the item is taxable.
        listPrice:
          type: number
          description: The net item price before discounts and coupons. BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel.
        originalPrice:
          type: number
          description: An item’s original price is the same as the product default price in the admin panel.
        name:
          type: string
          description: The item's product name.
        parentId:
          type: string
          description: The product is part of a bundle such as a product pick list, then the parentId or the main product id will populate.
          example: '6'
        productId:
          type: number
          description: ID of the product.
        quantity:
          type: number
          description: Quantity of this item.
        salePrice:
          type: number
          description: Item's price after all discounts are applied. (The final price before tax calculation.)
        sku:
          type: string
          description: SKU of the variant.
        url:
          type: string
          description: The product URL.
          format: uri
        variantId:
          type: number
          description: ID of the variant.
          example: 7
      x-internal: false
    responseCart:
      description: Cart object used in REST Storefront API cart responses.
      title: Cart Read
      type: object
      properties:
        id:
          type: string
          description: Cart ID, provided after creating a cart with a POST.
          format: UUID
        customerId:
          type: integer
          description: ID of the customer to which the cart belongs.
        email:
          type: string
          description: The cart's email. This is the same email that is used in the billing address
        currency:
          $ref: '#/components/schemas/responseCartCurrency'
        isTaxIncluded:
          type: boolean
          description: Whether this item is taxable.
        baseAmount:
          type: number
          description: Cost of cart’s contents, before applying discounts.
        discountAmount:
          type: number
          description: Order based discounted amount only - Coupon discounts and product based discounts are excluded.
          format: float
        cartAmount:
          type: number
          description: Sum of line-items amounts, minus cart-level discounts and coupons. This amount includes taxes (where applicable).
        coupons:
          $ref: '#/components/schemas/responseCartCoupons'
        discounts:
          $ref: '#/components/schemas/responseCartDiscounts'
        lineItems:
          $ref: '#/components/schemas/responseCartLineItems'
        createdTime:
          type: string
          description: Time when the cart was created.
          format: ISO-8601
        updatedTime:
          type: string
          description: Time when the cart was last updated.
          format: ISO-8601
        locale:
          type: string
          description: Locale of the cart.
      x-internal: false
  responses:
    deleteCartsItems:
      description: 'NOTE: Discounted line items are re-evaluated on cart actions and may be automatically added back to your cart with a new line item ID to satisfy promotional requirements.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/responseCart'
          examples:
            Example:
              value:
                id: string
                customerId: 0
                email: string
                currency:
                  code: string
                isTaxIncluded: true
                baseAmount: 0
                discountAmount: 0
                cartAmount: 0
                coupons:
                - code: string
                  couponType: 0
                  discountedAmount: 0
                  id: string
                discounts:
                - discountedAmount: 0
                  id: string
                lineItems:
                  customItems: []
                  digitalItems:
                  - options:
                    - name: string
                      nameId: 0
                      value: string
                      valueId: 0
                    brand: string
                    couponAmount: 0
                    discountAmount: 0
                    discounts:
                    - discountedAmount: 0
                      id: 0
                    extendedListPrice: 0
                    extendedSalePrice: 0
               

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-cart-items-api-openapi.yml