ev.energy Support Tickets API

openapi: 3.2.0
info:
  title: ev.energy v2 Support Tickets API
  version: '2.0'
  contact:
    email: developers@ev.energy
    url: developers.ev.energy
    name: ev.energy developers
  description: The official API for ev.energy, version 2.
  license:
    name: Proprietary
    url: https://ev.energy
  termsOfService: ''
servers:
- url: https://api.ev.energy/v2
  description: Live API for both production and sandbox requests.
  x-internal: false
- description: Staging server for internal testing only.
  url: https://api-staging.ev.energy/v2
  x-internal: true
security:
- oauth2: []
tags:
- name: Support Tickets
  description: Endpoints for interacting with customer support tickets.
paths:
  /support_tickets:
    get:
      summary: List support tickets
      tags:
      - Support Tickets
      responses:
        '200':
          description: Returns a list of support tickets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupportTicket'
          headers:
            Link:
              $ref: '#/components/headers/link'
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestList'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-support_tickets
      description: 'List all support tickets that the authorization token has access to.


        Access control:

        - User-scoped tokens: Returns only tickets belonging to that user

        - Organization-scoped tokens: Returns only tickets belonging to users in that organization

        - Tokens with access_all_areas: Returns all tickets including those without a user


        Note: Tickets without a user (null user field) are only accessible to applications with access_all_areas permission. These tickets represent inquiries from channels where a user account may not exist (e.g., pre-signup inquiries, web forms).'
      parameters:
      - $ref: '#/components/parameters/previous'
      - $ref: '#/components/parameters/next'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-supportticket'
      - schema:
          type: string
        in: query
        name: external_ticket_id
        description: Filter by external ticket ID from support system
      - schema:
          type: string
        in: query
        name: human_verified_category
        description: Filter by human verified category
      - schema:
          type: string
        in: query
        name: human_verified_subcategory
        description: Filter by human verified subcategory
      - schema:
          type: string
        in: query
        name: ai_generated_category
        description: Filter by AI generated category
      - schema:
          type: string
        in: query
        name: ai_generated_subcategory
        description: Filter by AI generated subcategory
      - schema:
          type: boolean
        in: query
        name: human_verified_category__isnull
        description: Filter for tickets with or without human verified category
      - schema:
          type: boolean
        in: query
        name: human_verified_subcategory__isnull
        description: Filter for tickets with or without human verified subcategory
      - schema:
          type: boolean
        in: query
        name: ai_generated_category__isnull
        description: Filter for tickets with or without AI generated category
      - schema:
          type: boolean
        in: query
        name: ai_generated_subcategory__isnull
        description: Filter for tickets with or without AI generated subcategory
      - schema:
          type: string
        in: query
        name: status
        description: Filter by ticket status (e.g., Open, Resolved, Closed)
      - schema:
          type: string
        in: query
        name: status__in
        description: Filter by multiple status values (comma-separated)
      - schema:
          type: string
        in: query
        name: priority
        description: Filter by ticket priority (e.g., Low, Medium, High, Urgent)
      - schema:
          type: string
        in: query
        name: priority__in
        description: Filter by multiple priority values (comma-separated)
      - schema:
          type: boolean
        in: query
        name: priority__isnull
        description: Filter for tickets with or without priority
      - schema:
          type: string
          format: date-time
        in: query
        name: created_at__gte
        description: Filter tickets created on or after this date
      - schema:
          type: string
          format: date-time
        in: query
        name: created_at__lte
        description: Filter tickets created on or before this date
      - schema:
          type: string
        in: query
        name: created_at__range
        description: Filter tickets created within a date range (comma-separated start and end dates)
      - schema:
          type: string
          format: uri
        in: query
        name: user
        description: Filter tickets by a specific user ID
      - schema:
          type: boolean
        in: query
        name: user__isnull
        description: Filter for tickets with or without an associated user
      - schema:
          type: string
        in: query
        name: tags
        description: Filter by tag (checks if the tag exists in the tags array)
      - schema:
          type: string
        in: query
        name: source
        description: Filter by ticket source (e.g., Email, Phone, Feedback Widget)
      - schema:
          type: string
        in: query
        name: source__in
        description: Filter by multiple sources (comma-separated)
      - schema:
          type: string
          format: date-time
        in: query
        name: resolved_at__gte
        description: Filter tickets resolved on or after this date
      - schema:
          type: string
          format: date-time
        in: query
        name: resolved_at__lte
        description: Filter tickets resolved on or before this date
      - schema:
          type: string
        in: query
        name: resolved_at__range
        description: Filter tickets resolved within a date range (comma-separated start and end dates)
      - schema:
          type: boolean
        in: query
        name: resolved_at__isnull
        description: Filter for unresolved tickets (true) or resolved tickets (false)
      - schema:
          type: string
          format: date-time
        in: query
        name: ticket_updated_at__gte
        description: Filter tickets updated on or after this date
      - schema:
          type: string
          format: date-time
        in: query
        name: ticket_updated_at__lte
        description: Filter tickets updated on or before this date
      - schema:
          type: string
        in: query
        name: ticket_updated_at__range
        description: Filter tickets updated within a date range (comma-separated start and end dates)
      - schema:
          type: boolean
        in: query
        name: ticket_updated_at__isnull
        description: Filter for tickets with or without an update timestamp
      - $ref: '#/components/parameters/user'
      security:
      - oauth2:
        - support:read
  /support_tickets/{support_ticket_id}:
    parameters:
    - $ref: '#/components/parameters/support_ticket_id'
    get:
      summary: Retrieve support ticket
      description: 'Retrieve information about a single, specific support ticket.


        Access control:

        - User-scoped tokens: Can only access tickets belonging to that user

        - Organization-scoped tokens: Can only access tickets belonging to users in that organization

        - Tokens with access_all_areas: Can access all tickets including those without a user


        Note: Tickets without a user (null user field) will return 404 for tokens without access_all_areas permission.'
      tags:
      - Support Tickets
      responses:
        '200':
          description: Returns a single support ticket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportTicket'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-support_tickets-support_ticket_id
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-supportticket'
      security:
      - oauth2:
        - support:read
    patch:
      summary: Update support ticket
      tags:
      - Support Tickets
      responses:
        '200':
          description: Support ticket updated successfully.
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportTicket'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: patch-support_tickets-support_ticket_id
      security:
      - oauth2:
        - support:write
      description: 'Update support ticket categorization.


        Access control follows the same rules as retrieval:

        - User-scoped tokens: Can only update tickets belonging to that user

        - Organization-scoped tokens: Can only update tickets belonging to users in that organization

        - Tokens with access_all_areas: Can update all tickets including those without a user'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupportTicket'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SupportTicket'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SupportTicket'
      parameters:
      - $ref: '#/components/parameters/version-2'
  /support_tickets/{support_ticket_id}/messages:
    parameters:
    - $ref: '#/components/parameters/support_ticket_id'
    get:
      summary: List messages for a support ticket
      description: 'List all messages in a support ticket conversation, ordered by position.


        Access control follows the same rules as the parent support ticket:

        - User-scoped tokens: Can only access messages for tickets belonging to that user

        - Organization-scoped tokens: Can only access messages for tickets belonging to users in that organization

        - Tokens with access_all_areas: Can access messages for all tickets including those without a user'
      tags:
      - Support Tickets
      responses:
        '200':
          description: Returns a list of messages for the specified support ticket.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupportTicketMessage'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestList'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-support_tickets-support_ticket_id-messages
      parameters:
      - $ref: '#/components/parameters/version-2'
      - schema:
          type: string
        in: query
        name: message_type
        description: Filter by message type (e.g., INITIAL_REQUEST, CUSTOMER_RESPONSE, HUMAN_AGENT_RESPONSE, AI_AGENT_RESPONSE)
      - schema:
          type: string
        in: query
        name: message_type__in
        description: Filter by multiple message types (comma-separated)
      - schema:
          type: integer
        in: query
        name: position
        description: Filter by message position in the conversation (0 is first message)
      - schema:
          type: integer
        in: query
        name: position__gte
        description: Filter for messages at or after this position
      - schema:
          type: integer
        in: query
        name: position__lte
        description: Filter for messages at or before this position
      security:
      - oauth2:
        - support:read
  /support_tickets/{support_ticket_id}/messages/{message_id}:
    parameters:
    - $ref: '#/components/parameters/support_ticket_id'
    - $ref: '#/components/parameters/message_id'
    get:
      summary: Retrieve a message for a support ticket
      description: 'Retrieve a single message from a support ticket conversation.


        Access control follows the same rules as the parent support ticket.'
      tags:
      - Support Tickets
      responses:
        '200':
          description: Returns a single support ticket message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportTicketMessage'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-support_tickets-support_ticket_id-messages-message_id
      parameters:
      - $ref: '#/components/parameters/version-2'
      security:
      - oauth2:
        - support:read
  /support_tickets/categories:
    get:
      summary: Get support ticket categories
      tags:
      - Support Tickets
      description: Returns all available support ticket categories and subcategories.
      operationId: get-support_tickets-categories
      responses:
        '200':
          description: Returns all available categories and subcategories.
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    description: List of all available ticket categories. Each category includes the enum value and its human-readable label.
                    items:
                      type: object
                      required:
                      - value
                      - label
                      properties:
                        value:
                          allOf:
                          - $ref: '#/components/schemas/SupportTicketCategoryEnum'
                          description: The enum value (ALL_CAPS format) for programmatic use.
                          example: CHARGER
                        label:
                          type: string
                          description: Human-readable label for display.
                          example: Charger
                  subcategories:
                    type: array
                    description: List of all available ticket subcategories. Each subcategory includes the enum value and its human-readable label.
                    items:
                      type: object
                      required:
                      - value
                      - label
                      properties:
                        value:
                          allOf:
                          - $ref: '#/components/schemas/SupportTicketSubcategoryEnum'
                          description: The enum value (ALL_CAPS format) for programmatic use.
                          example: HARDWARE_ISSUE
                        label:
                          type: string
                          description: Human-readable label for display.
                          example: Hardware Issue
              examples:
                Example:
                  value:
                    categories:
                    - value: ACCOUNT
                      label: Account
                    - value: CHARGER
                      label: Charger
                    - value: CHARGING_SESSION
                      label: Charging Session
                    - value: MOBILE_APP
                      label: Mobile App
                    - value: OTHER
                      label: Other
                    - value: SOLAR
                      label: Solar
                    - value: USABILITY_UX
                      label: Usability/UX
                    - value: VEHICLE
                      label: Vehicle
                    subcategories:
                    - value: ACCESSIBILITY
                      label: Accessibility
                    - value: HARDWARE_ISSUE
                      label: Hardware Issue
                    - value: APP_CRASH_FREEZE
                      label: App crash / freeze
                    - value: TELEMATICS_ISSUE
                      label: Telematics issue
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/version-2'
  /support-ticket-stats/sankey:
    get:
      summary: Get support ticket Sankey diagram data
      tags:
      - Support Tickets
      description: Returns aggregated data for visualizing ticket flow from category to subcategory in a Sankey diagram. Only includes tickets with human-verified categories.
      operationId: get-support_ticket_stats-sankey
      responses:
        '200':
          description: Returns Sankey diagram nodes and links.
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                    description: List of nodes in the Sankey diagram (categories and subcategories).
                    items:
                      type: object
                      required:
                      - id
                      - label
                      properties:
                        id:
                          type: string
                          description: Unique identifier for the node (prefixed with 'category:' or 'subcategory:').
                          example: category:Charger
                        label:
                          type: string
                          description: Human-readable label for display.
                          example: Charger
                  links:
                    type: array
                    description: List of links between nodes representing ticket flows.
                    items:
                      type: object
                      required:
                      - source
                      - target
                      - value
                      properties:
                        source:
                          type: string
                          description: ID of the source node (category).
                          example: category:Charger
                        target:
                          type: string
                          description: ID of the target node (subcategory).
                          example: subcategory:Hardware Issue
                        value:
                          type: integer
                          description: Number of tickets flowing from source to target.
                          example: 42
              examples:
                Example:
                  value:
                    nodes:
                    - id: category:Charger
                      label: Charger
                    - id: subcategory:Hardware Issue
                      label: Hardware Issue
                    links:
                    - source: category:Charger
                      target: subcategory:Hardware Issue
                      value: 42
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/version-2'
  /support-ticket-stats/volume:
    get:
      summary: Get support ticket volume time series
      tags:
      - Support Tickets
      description: Returns time series data showing ticket volume over time. Can be grouped by day, week, or month.
      operationId: get-support_ticket_stats-volume
      responses:
        '200':
          description: Returns time series data for ticket volume.
          content:
            application/json:
              schema:
                type: object
                properties:
                  time_series:
                    type: array
                    description: List of time periods with ticket counts.
                    items:
                      type: object
                      required:
                      - date
                      - count
                      properties:
                        date:
                          type: string
                          format: date
                          description: ISO 8601 date string for the time period.
                          example: '2024-01-15'
                        count:
                          type: integer
                          description: Number of distinct tickets created in this period.
                          example: 23
              examples:
                Example:
                  value:
                    time_series:
                    - date: '2024-01-15'
                      count: 23
                    - date: '2024-01-16'
                      count: 31
                    - date: '2024-01-17'
                      count: 18
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/version-2'
      - name: group_by
        in: query
        description: Time period to group by (day, week, or month). Defaults to day.
        schema:
          type: string
          enum:
          - day
          - week
          - month
          default: day
  /support-ticket-stats/resolution:
    get:
      summary: Get support ticket resolution metrics
      tags:
      - Support Tickets
      description: Returns metrics about ticket resolution including resolution rate, average and median resolution times.
      operationId: get-support_ticket_stats-resolution
      responses:
        '200':
          description: Returns resolution metrics.
          content:
            application/json:
              schema:
                type: object
                required:
                - resolution_rate
                - total_resolved
                - total_unresolved
                properties:
                  resolution_rate:
                    type: number
                    format: float
                    description: Percentage of tickets that have been resolved (0-1).
                    example: 0.85
                  avg_resolution_time_hours:
                    type:
                    - number
                    - 'null'
                    format: float
                    description: Average time to resolve a ticket in hours. Null if no tickets resolved.
                    example: 24.5
                  median_resolution_time_hours:
                    type:
                    - number
                    - 'null'
                    format: float
                    description: Median time to resolve a ticket in hours. Null if no tickets resolved.
                    example: 18.2
                  total_resolved:
                    type: integer
                    description: Total number of resolved tickets.
                    example: 170
                  total_unresolved:
                    type: integer
                    description: Total number of unresolved tickets.
                    example: 30
              examples:
                Example:
                  value:
                    resolution_rate: 0.85
                    avg_resolution_time_hours: 24.5
                    median_resolution_time_hours: 18.2
                    total_resolved: 170
                    total_unresolved: 30
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/version-2'
  /support-ticket-stats/status:
    get:
      summary: Get support ticket status breakdown
      tags:
      - Support Tickets
      description: Returns the distribution of tickets across different status values.
      operationId: get-support_ticket_stats-status
      responses:
        '200':
          description: Returns ticket breakdown by status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  breakdown:
                    type: array
                    description: List of status values with counts and percentages.
                    items:
                      type: object
                      required:
                      - status
                      - count
                      - percentage
                      properties:
                        status:
                          type: string
                          description: Status value.
                          example: open
                        count:
                          type: integer
                          description: Number of distinct tickets with this status.
                          example: 45
                        percentage:
                          type: number
                          format: float
                          description: Percentage of total tickets (0-1).
                          example: 0.45
              examples:
                Example:
                  value:
                    breakdown:
                    - status: open
                      count: 45
                      percentage: 0.45
                    - status: closed
                      count: 55
                      percentage: 0.55
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/version-2'
  /support-ticket-stats/priority:
    get:
      summary: Get support ticket priority breakdown
      tags:
      - Support Tickets
      description: Returns the distribution of tickets across different priority values.
      operationId: get-support_ticket_stats-priority
      responses:
        '200':
          description: Returns ticket breakdown by priority.
          content:
            application/json:
              schema:
                type: object
                properties:
                  breakdown:
                    type: array
                    description: List of priority values with counts and percentages.
                    items:
                      type: object
                      required:
                      - priority
                      - count
                      - percentage
                      properties:
                        priority:
                          type: string
                          description: Priority value.
                          example: high
                        count:
                          type: integer
                          description: Number of distinct t

# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ev-energy/refs/heads/main/openapi/ev-energy-support-tickets-api-openapi.yml