openapi: 3.1.0
info:
  title: Freshdesk REST Agents Time Entries API
  description: The Freshdesk REST API (v2) provides programmatic access to helpdesk data and operations within Freshdesk, a customer support platform by Freshworks. It exposes endpoints for managing tickets, contacts, companies, agents, groups, conversations, products, email configurations, SLA policies, business hours, time entries, satisfaction ratings, solution categories, solution folders, solution articles, and more. The API uses JSON for request and response payloads, supports API key-based authentication, and follows RESTful conventions for CRUD operations.
  version: '2.0'
  contact:
    name: Freshdesk Support
    url: https://support.freshdesk.com/
  termsOfService: https://www.freshworks.com/terms/
servers:
- url: https://{domain}.freshdesk.com/api/v2
  description: Freshdesk Production Server
  variables:
    domain:
      default: yourdomain
      description: Your Freshdesk subdomain, e.g. if your helpdesk URL is acme.freshdesk.com, use acme.
security:
- basicAuth: []
tags:
- name: Time Entries
  description: Track time spent on tickets by agents.
paths:
  /tickets/{ticket_id}/time_entries:
    get:
      operationId: listTicketTimeEntries
      summary: List time entries for a ticket
      description: Retrieves all time entries associated with the specified ticket.
      tags:
      - Time Entries
      parameters:
      - $ref: '#/components/parameters/ticketId'
      responses:
        '200':
          description: Successfully retrieved time entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createTimeEntry
      summary: Create a time entry
      description: Adds a new time entry to the specified ticket to track agent effort.
      tags:
      - Time Entries
      parameters:
      - $ref: '#/components/parameters/ticketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeEntryCreate'
      responses:
        '201':
          description: Time entry created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /time_entries:
    get:
      operationId: listAllTimeEntries
      summary: List all time entries
      description: Retrieves all time entries across all tickets, with optional filters.
      tags:
      - Time Entries
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Successfully retrieved time entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /time_entries/{time_entry_id}:
    put:
      operationId: updateTimeEntry
      summary: Update a time entry
      description: Updates the properties of an existing time entry.
      tags:
      - Time Entries
      parameters:
      - $ref: '#/components/parameters/timeEntryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeEntryCreate'
      responses:
        '200':
          description: Time entry updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteTimeEntry
      summary: Delete a time entry
      description: Deletes a time entry from a ticket.
      tags:
      - Time Entries
      parameters:
      - $ref: '#/components/parameters/timeEntryId'
      responses:
        '204':
          description: Time entry deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /time_entries/{time_entry_id}/toggle_timer:
    put:
      operationId: toggleTimer
      summary: Toggle a timer
      description: Starts or stops the timer on a time entry.
      tags:
      - Time Entries
      parameters:
      - $ref: '#/components/parameters/timeEntryId'
      responses:
        '200':
          description: Timer toggled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Authentication failed or credentials were not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    TimeEntryCreate:
      type: object
      properties:
        agent_id:
          type: integer
          format: int64
          description: ID of the agent who performed the work.
        billable:
          type: boolean
          description: Whether the time entry is billable.
        note:
          type: string
          description: Notes about the work performed.
        time_spent:
          type: string
          description: Time spent in hh:mm format.
        executed_at:
          type: string
          format: date-time
          description: Date when the work was performed.
    TimeEntry:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the time entry.
        agent_id:
          type: integer
          format: int64
          description: ID of the agent who logged the time.
        ticket_id:
          type: integer
          format: int64
          description: ID of the ticket the time entry is for.
        billable:
          type: boolean
          description: Whether the time entry is billable.
        note:
          type: string
          nullable: true
          description: Notes about the time entry.
        time_spent:
          type: string
          description: Time spent in hh:mm format.
        timer_running:
          type: boolean
          description: Whether a timer is currently running on this entry.
        executed_at:
          type: string
          format: date-time
          description: Date when the work was performed.
        start_time:
          type: string
          format: date-time
          nullable: true
          description: Start time of the timer if running.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the time entry was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the time entry was last updated.
    Error:
      type: object
      properties:
        description:
          type: string
          description: Human-readable error description.
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error.
              message:
                type: string
                description: Error message for the field.
              code:
                type: string
                description: Error code.
  parameters:
    perPage:
      name: per_page
      in: query
      description: Number of results per page (max 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    ticketId:
      name: ticket_id
      in: path
      required: true
      description: Unique identifier of the ticket.
      schema:
        type: integer
        format: int64
    timeEntryId:
      name: time_entry_id
      in: path
      required: true
      description: Unique identifier of the time entry.
      schema:
        type: integer
        format: int64
    page:
      name: page
      in: query
      description: Page number for paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Freshdesk uses API key-based authentication. Pass your API key as the username with any string (e.g. X) as the password using HTTP Basic Authentication.
externalDocs:
  description: Freshdesk API Documentation
  url: https://developers.freshdesk.com/api/