KeySavvy Marketplace Management API

openapi: 3.2.0
info:
  title: KeySavvy Partner Marketplace Management API
  version: 1.0.0
  description: API for KeySavvy Partner integration
  contact:
    name: KeySavvy API Support Team
    email: api-support@keysavvy.com
servers:
- url: https://api.keysavvy.com/v1
  description: KeySavvy Production API
- url: https://api.keysavvy.dev/v1
  description: KeySavvy Non-Production API
security:
- apiKey: []
tags:
- name: Marketplace Management
  description: Operations related to marketplace themes.
paths:
  /marketplace:
    post:
      tags:
      - Marketplace Management
      summary: Create a new marketplace
      description: Creates a new marketplace and its associated theme information (excluding logo images). This can be referenced when creating new deals, vehicles, and users.
      operationId: createMarketplace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarketplaceCreateRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/MarketplaceDetailsResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
  /marketplace/{referenceId}:
    get:
      tags:
      - Marketplace Management
      summary: Gets current information about a given marketplace
      description: Returns marketplace information if the provided referenceId exists
      operationId: getMarketplace
      parameters:
      - name: referenceId
        in: path
        description: Reference ID of the marketplace.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/MarketplaceDetailsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
    patch:
      tags:
      - Marketplace Management
      summary: Update marketplace information
      description: Updates information for the given marketplace if it exists.
      operationId: updateMarketplace
      parameters:
      - name: referenceId
        in: path
        description: Reference ID of the marketplace.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarketplaceUpdateRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/MarketplaceDetailsResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /marketplace/{referenceId}/logo:
    post:
      tags:
      - Marketplace Management
      summary: Uploads a new logo for the provided marketplace
      description: Creates or replaces and existing logo for the given marketplace. The maximum file size for a logo is 1 MB.
      operationId: uploadMarketplaceLogo
      parameters:
      - name: referenceId
        in: path
        description: Reference ID of the marketplace.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarketplaceLogoUploadRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/MarketplaceDetailsResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '413':
          $ref: '#/components/responses/ErrorResponse'
components:
  responses:
    MarketplaceDetailsResponse:
      description: Marketplace information
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MarketplaceDetailsResponseBody'
    UnauthorizedResponse:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    ErrorResponse:
      description: The request failed. `error` and `message` describe why.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
  schemas:
    ErrorResponseBody:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    PartnerMarketplaceLinkConfig:
      type: object
      description: 'Configuration so that KeySavvy can create URLs that link a vehicle or deal in our system back out to your marketplace.

        '
      required:
      - baseUrl
      - dealPathPattern
      - vehiclePathPattern
      properties:
        baseUrl:
          type: string
          format: uri
          maxLength: 512
          description: 'Base URL KeySavvy can use to link a user back to the vehicle or deal in your marketplace. This must be

            fully qualified, HTTPS, and should not include path or query params.


            Example: https://www.keysavvy.com

            '
        dealPathPattern:
          type: string
          maxLength: 512
          description: "A [path-to-regexp](https://github.com/pillarjs/path-to-regexp?tab=readme-ov-file#compile-reverse-path-to-regexp)\npattern used in combination with baseUrl to create a link to a specific deal in your marketplace.\n\nThe following the following path parameters are supported:\n\n  * `dealReferenceId` - The vehicle reference ID provided at the time of vehicle / deal creation.\n\nExample - /deal/:dealReferenceId\n"
        vehiclePathPattern:
          type:
          - string
          - 'null'
          maxLength: 512
          description: "A [path-to-regexp](https://github.com/pillarjs/path-to-regexp?tab=readme-ov-file#compile-reverse-path-to-regexp)\npattern used in combination with baseUrl to create a link to a specific vehicle page in your marketplace.\n\nThe following the following path parameters are supported:\n\n  * `vehicleReferenceId` - The vehicle reference ID provided at the time of vehicle / deal creation.\n\nExample - /vehicle/:vehicleReferenceId\n"
    MarketplaceCreateRequestBody:
      type: object
      required:
      - referenceId
      - name
      properties:
        referenceId:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          description: A stable, unique, case-sensitive partner-supplied ID for this marketplace. This is how you will associate vehicles & deals with a marketplace.
        name:
          type: string
          description: The user facing name of this marketplace. This value is displayed in various places throughout the UI & emails.
        color:
          type:
          - string
          - 'null'
          pattern: ^#[A-F0-9]{6}$
          description: 'Optional hex color (e.g. #FF99CC) to be used as the primary accent color. If not provided, your default theme color will be used.'
        mobileLogo:
          type:
          - string
          - 'null'
          description: Displayed in the header at mobile breakpoints. When not set, your platform's logo is used. This image will be aspect scaled to fit 220px x 40px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..."
        desktopLogo:
          type:
          - string
          - 'null'
          description: Displayed in the header at desktop breakpoints. When not set, the mobile logo is used, then your platform's logo. This image will be aspect scaled to fit 250px x 100px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..."
        emailLogo:
          type:
          - string
          - 'null'
          description: Displayed in the header of transactional emails. When not set, the desktop logo is used, then the mobile logo, then your platform's logo. This image will be aspect scaled to fit 400px x 200px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..."
        homePageUrl:
          type:
          - string
          - 'null'
          format: uri
          maxLength: 1024
          description: URL to the marketplace website home page. Must be fully qualified and HTTPS. E.g. https://www.keysavvy.com
        linkConfig:
          oneOf:
          - $ref: '#/components/schemas/PartnerMarketplaceLinkConfig'
          - type: 'null'
    MarketplaceDetailsResponseBody:
      type: object
      required:
      - referenceId
      - homePageUrl
      - linkConfig
      - commonName
      - mobileLogoUrl
      - desktopLogoUrl
      - emailLogoUrl
      - color
      properties:
        referenceId:
          type: string
        commonName:
          type: string
        mobileLogoUrl:
          type:
          - string
          - 'null'
          description: URL of the logo to be displayed in the header at mobile breakpoints. If this is missing, your default logo is used.
        desktopLogoUrl:
          type:
          - string
          - 'null'
          description: URL of the logo to be displayed in the header at desktop breakpoints. If this is missing, the mobileLogoUrl is used, then your default logo.
        emailLogoUrl:
          type:
          - string
          - 'null'
          description: URL of the logo to be displayed in the header of transactional emails. If this is missing, the desktopLogoUrl is used, then the mobileLogoUrl, then your default logo.
        color:
          type:
          - string
          - 'null'
        homePageUrl:
          type:
          - string
          - 'null'
        linkConfig:
          oneOf:
          - $ref: '#/components/schemas/PartnerMarketplaceLinkConfig'
          - type: 'null'
    MarketplaceLogoUploadRequestBody:
      type: object
      required:
      - type
      - file
      properties:
        type:
          type: string
          description: "The type of logo being uploaded.\nTypes:\n * `mobile` - Displayed in the header at mobile breakpoints. This will be aspect scaled to fit within 40px x 230px bounds.\n * `desktop` - Displayed in the header at desktop breakpoints. This will be aspect scaled to fit within 50px x 250px bounds.\n * `email` - Displayed at the top of emails. This will be aspect scaled to fit within 400px x 200px bounds.\n"
          enum:
          - mobile
          - desktop
          - email
        file:
          type: string
          format: binary
          description: The logo file being uploaded. This file must be an image (image/* mime-type).
    MarketplaceUpdateRequestBody:
      type: object
      properties:
        name:
          type: string
          description: The user facing name of this marketplace. This value is displayed in various places throughout the UI & emails.
        color:
          type: string
          pattern: ^#[A-F0-9]{6}$
          description: 'Hex color (e.g. #FF99CC) to be used as the primary accent color. If this is null, your default theme color will be used.'
        mobileLogo:
          type: string
          description: Displayed in the header at mobile breakpoints. When not set, your platform's logo is used. This image will be aspect scaled to fit 220px x 40px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..."
        desktopLogo:
          type: string
          description: Displayed in the header at desktop breakpoints. When not set, the mobile logo is used, then your platform's logo. This image will be aspect scaled to fit 250px x 100px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..."
        emailLogo:
          type: string
          description: Displayed in the header of transactional emails. When not set, the desktop logo is used, then the mobile logo, then your platform's logo. This image will be aspect scaled to fit 400px x 200px. May be provided as base64 image data, or an absolute URL to the image. E.g. "data:image/png;base64,..." or "https://..."
        homePageUrl:
          type: string
          format: uri
          maxLength: 1024
          description: URL to the marketplace website home page. Must be fully qualified and HTTPS. E.g. https://www.keysavvy.com
        linkConfig:
          oneOf:
          - $ref: '#/components/schemas/PartnerMarketplaceLinkConfig'
          - type: 'null'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: keysavvy-api