{"openapi":"3.1.0","info":{"title":"LiveAgent API","description":"This page contains complete API documentation for LiveAgent software. To display additional info and examples for specific API method, just click on the method name in the list below.\n\nTo be able to make API requests you need to generate an API key in your admin panel first. [See this article for detailed info.](https:\/\/support.liveagent.com\/741982-API-key)\n\nIf you have any question or doubts regarding this API, please do not hesitate to contact our support team.","version":"4.0.0","contact":{"name":"Support","url":"https:\/\/www.liveagent.com\/about\/contact\/","email":"support@ladesk.com"}},"servers":[{"url":"\/api\/v4"}],"paths":{"\/agents\/{agentId}\/activity":{"get":{"tags":["agents"],"operationId":"getAgentActivity","summary":"Get ticket activity history for an agent","description":"Returns the history of all ticket participation for a specific agent. Each record represents an activity session (view, solve, ring) with start and end times. Results are limited to 1000 records; use date range filters to narrow large result sets.\n","parameters":[{"$ref":"#\/components\/parameters\/agentId"},{"name":"ticketId","in":"query","required":false,"description":"Filter by ticket ID(s). Multiple values narrow results to matching tickets.","schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/TicketId"}}},{"$ref":"#\/components\/parameters\/activityType"},{"$ref":"#\/components\/parameters\/activityFromStart"},{"$ref":"#\/components\/parameters\/activityFromEnd"},{"$ref":"#\/components\/parameters\/sortOrder"}],"responses":{"200":{"description":"Ticket activity records for the agent","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentActivityList"}}}},"400":{"$ref":"#\/components\/responses\/Error"},"500":{"$ref":"#\/components\/responses\/Error"}}}},"\/agents\/{agentId}\/worktime":{"get":{"tags":["agent-worktime"],"operationId":"getAgentWorktime","summary":"Get agent online status history","description":"Returns agent online status transitions (online, paused) within a date range. Offline time is represented as gaps between records. Mobile statuses are excluded. Results are limited to 1000 records. If more exist, the response indicates truncation and the date range filter should be narrowed.\n","parameters":[{"$ref":"#\/components\/parameters\/agentId"},{"name":"dateFrom","in":"query","required":false,"description":"Start of the date range (inclusive), as an ISO 8601 date-time. An explicit timezone offset (for example Z or +02:00) is honored; UTC is assumed when omitted.","schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","required":false,"description":"End of the date range (inclusive), as an ISO 8601 date-time. An explicit timezone offset (for example Z or +02:00) is honored; UTC is assumed when omitted.","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"description":"Filter by status.","schema":{"type":"string","enum":["online","paused"]}},{"name":"sortDir","in":"query","required":false,"description":"Sort direction by status start time (default DESC).","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}}],"responses":{"200":{"description":"Agent worktime history","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentWorktimeResponse"}}}},"400":{"$ref":"#\/components\/responses\/Error"},"403":{"$ref":"#\/components\/responses\/Error"},"500":{"$ref":"#\/components\/responses\/Error"}}}},"\/agents\/availability":{"get":{"tags":["agent-availability"],"operationId":"getAgentsAvailability","summary":"Retrieve agent availability history","description":"Returns a paginated list of agent availability history records per department and service type. Each record represents a time period when an agent was available for a specific service (to_solve, chat, or call) in a specific department. Use the `cursor` parameter for pagination.\n","parameters":[{"name":"agentId","in":"query","required":false,"description":"Filter by agent ID. Supports comma-separated values for multiple agents.","schema":{"type":"string"},"example":"abc12345"},{"name":"departmentId","in":"query","required":false,"description":"Filter by department ID. Supports comma-separated values for multiple departments.","schema":{"type":"string"},"example":"dep67890"},{"name":"serviceType","in":"query","required":false,"description":"Filter by service type. Supports comma-separated values.","schema":{"type":"string","enum":["to_solve","chat","call"]}},{"name":"availableFrom","in":"query","required":false,"description":"Filter records active after this date-time (inclusive). RFC 3339 date-time; an explicit timezone offset (e.g. Z or +02:00) is honored, UTC is assumed when omitted.","schema":{"type":"string","format":"date-time","example":"2025-01-01T00:00:00Z"}},{"name":"availableTo","in":"query","required":false,"description":"Filter records active before this date-time (inclusive). RFC 3339 date-time; an explicit timezone offset (e.g. Z or +02:00) is honored, UTC is assumed when omitted.","schema":{"type":"string","format":"date-time","example":"2025-12-31T23:59:59Z"}},{"name":"sortDir","in":"query","required":false,"description":"Sort direction for available_from field. Default is DESC (newest first).","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of records to return (1-1000). Default is 1000.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":1000,"default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor token for paginated results. Use the value returned in the previous response to fetch the next page.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"A paginated list of agent availability records.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentAvailabilityList"}}}},"400":{"$ref":"#\/components\/responses\/Error"},"500":{"$ref":"#\/components\/responses\/Error"}}}},"\/department\/rename\/{departmentId}":{"post":{"tags":["department"],"operationId":"rename","summary":"Rename a department","parameters":[{"$ref":"#\/components\/parameters\/departmentId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"newName":{"$ref":"#\/components\/schemas\/DepartmentName"}}}}}},"responses":{"200":{"$ref":"#\/components\/responses\/Ok"},"400":{"$ref":"#\/components\/responses\/Error"},"404":{"$ref":"#\/components\/responses\/Error"},"500":{"$ref":"#\/components\/responses\/Error"}}}},"\/department\/{departmentId}":{"get":{"tags":["department"],"operationId":"getDepartment","summary":"Return a department by ID","parameters":[{"$ref":"#\/components\/parameters\/departmentId"}],"responses":{"200":{"description":"A department object","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Department"}}}},"400":{"$ref":"#\/components\/responses\/Error"},"404":{"$ref":"#\/components\/responses\/Error"},"500":{"$ref":"#\/components\/responses\/Error"}}}},"\/ticket-field-definitions\/":{"get":{"tags":["ticket-field-definitions"],"operationId":"listTicketFieldDefinitions","summary":"List ticket field definitions","description":"Returns ticket field definitions ordered by name. Admin configuration is not paged: the whole list is returned up to a server-side cap of 1000, and meta.hasMore reports whether the cap truncated the result. Archived definitions are excluded unless includeArchived is set.","parameters":[{"name":"includeArchived","in":"query","required":false,"description":"Include archived definitions in the result.","schema":{"type":"boolean","default":false}},{"name":"filter","in":"query","required":false,"description":"Case-insensitive substring matched against the definition name.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of ticket field definitions","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketFieldDefinitionListResponse"}}}},"400":{"$ref":"#\/components\/responses\/Problem"},"403":{"$ref":"#\/components\/responses\/Problem"},"500":{"$ref":"#\/components\/responses\/Problem"}}}},"\/ticket-field-definitions\/{id}":{"get":{"tags":["ticket-field-definitions"],"operationId":"getTicketFieldDefinition","summary":"Get a ticket field definition by ID","parameters":[{"$ref":"#\/components\/parameters\/id"}],"responses":{"200":{"description":"A ticket field definition","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketFieldDefinitionResponse"}}}},"400":{"$ref":"#\/components\/responses\/Problem"},"403":{"$ref":"#\/components\/responses\/Problem"},"404":{"$ref":"#\/components\/responses\/Problem"},"500":{"$ref":"#\/components\/responses\/Problem"}}}},"\/tickets\/{ticketId}\/activity":{"get":{"tags":["tickets"],"operationId":"getTicketActivity","summary":"Get agent activity history for a ticket","description":"Returns the history of all agent participation in a specific ticket. Each record represents an activity session (view, solve, ring) with start and end times. Results are limited to 1000 records; use date range filters to narrow large result sets.\n","parameters":[{"$ref":"#\/components\/parameters\/ticketId"},{"name":"agentId","in":"query","required":false,"description":"Filter by agent ID(s). Multiple values narrow results to matching agents.","schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/AgentId"}}},{"$ref":"#\/components\/parameters\/activityType"},{"$ref":"#\/components\/parameters\/activityFromStart"},{"$ref":"#\/components\/parameters\/activityFromEnd"},{"$ref":"#\/components\/parameters\/sortOrder"}],"responses":{"200":{"description":"Agent activity records for the ticket","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketActivityList"}}}},"400":{"$ref":"#\/components\/responses\/Error"},"500":{"$ref":"#\/components\/responses\/Error"}}}}},"components":{"responses":{"Error":{"description":"Error response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorMessage"}}}},"Ok":{"description":"Ok response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Ok"}}}},"Problem":{"description":"Error response following the RFC 7807 problem+json convention.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Problem"}}}}},"parameters":{"agentId":{"in":"path","required":true,"name":"agentId","allowEmptyValue":false,"description":"Unique agent identifier","schema":{"$ref":"#\/components\/schemas\/AgentId"}},"activityType":{"in":"query","required":false,"name":"activityType","description":"Filter by activity type(s)","schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/ActivityType"}}},"activityFromStart":{"in":"query","required":false,"name":"activityFromStart","description":"Filter activities starting from this date-time (inclusive), ISO 8601 UTC","schema":{"type":"string","format":"date-time"}},"activityFromEnd":{"in":"query","required":false,"name":"activityFromEnd","description":"Filter activities starting before this date-time (inclusive), ISO 8601 UTC","schema":{"type":"string","format":"date-time"}},"sortOrder":{"in":"query","required":false,"name":"sortOrder","description":"Sort direction for activityFrom (default desc)","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},"departmentId":{"in":"path","required":true,"name":"departmentId","allowEmptyValue":false,"schema":{"$ref":"#\/components\/schemas\/DepartmentId"}},"id":{"in":"path","required":true,"name":"id","allowEmptyValue":false,"schema":{"type":"integer","format":"int64","minimum":1}},"ticketId":{"in":"path","required":true,"name":"ticketId","allowEmptyValue":false,"description":"Unique ticket identifier","schema":{"$ref":"#\/components\/schemas\/TicketId"}}},"schemas":{"ErrorMessage":{"type":"object","properties":{"error":{"type":"string"}}},"AgentId":{"type":"string","minLength":8,"maxLength":8,"pattern":"^[a-z0-9]+$"},"DepartmentId":{"type":"string","minLength":1,"maxLength":8,"pattern":"^[a-z0-9]+$"},"TicketId":{"type":"string","minLength":1,"maxLength":8,"pattern":"^[a-z0-9]+$"},"ActivityType":{"type":"string","enum":["solve","view","ring_chat","ring_call","ring_invite"]},"AgentActivityRecord":{"type":"object","required":["ticketId","activityType","activityFrom"],"properties":{"ticketId":{"$ref":"#\/components\/schemas\/TicketId"},"activityType":{"$ref":"#\/components\/schemas\/ActivityType"},"activityFrom":{"type":"string","format":"date-time","description":"When the activity started, as an RFC 3339 date-time in UTC."},"activityTo":{"type":["string","null"],"format":"date-time","description":"When the activity ended, as an RFC 3339 date-time in UTC. Null if still active."}}},"AgentActivityList":{"type":"object","required":["results","truncated"],"properties":{"results":{"type":"array","items":{"$ref":"#\/components\/schemas\/AgentActivityRecord"}},"truncated":{"type":"boolean","description":"True if more than 1000 results exist. Narrow the date range to retrieve all data."}}},"AgentWorktimeResponse":{"type":"object","description":"Agent worktime history response with truncation flag.","properties":{"truncated":{"type":"boolean","description":"True if more than 1000 records match and results are truncated."},"data":{"type":"array","description":"List of agent status history records.","items":{"$ref":"#\/components\/schemas\/AgentWorktimeRecord"}}}},"AgentWorktimeRecord":{"type":"object","description":"A single agent online status history record.","properties":{"statusFrom":{"type":"string","format":"date-time","description":"When the status started, as an RFC 3339 date-time in UTC."},"statusTo":{"type":["string","null"],"format":"date-time","description":"When the status ended, as an RFC 3339 date-time in UTC. Null for the current active state."},"status":{"type":"string","enum":["online","paused"],"description":"Agent status type."}}},"AgentAvailabilityList":{"type":"object","description":"Paginated response for agent availability history.","properties":{"cursor":{"type":["string","null"],"description":"Cursor for the next page of results. Null when no more results."},"items":{"type":"array","description":"List of agent availability records.","items":{"$ref":"#\/components\/schemas\/AgentAvailabilityRecord"}}}},"AgentAvailabilityRecord":{"type":"object","description":"A record of an agent's availability for a service in a department.","properties":{"id":{"type":"integer","description":"Unique identifier of the availability record."},"agentId":{"$ref":"#\/components\/schemas\/AgentId"},"departmentId":{"$ref":"#\/components\/schemas\/DepartmentId"},"serviceTypes":{"type":"array","items":{"type":"string","enum":["to_solve","chat","call"]},"description":"The services the agent was available for during this interval. Multiple values when the underlying record covers several services simultaneously."},"availableFrom":{"type":"string","format":"date-time","description":"When the agent became available, as an RFC 3339 date-time in UTC."},"availableTo":{"type":["string","null"],"format":"date-time","description":"When the agent became unavailable, as an RFC 3339 date-time in UTC. Null means currently available."}}},"Ok":{"type":"object"},"Department":{"type":"object","properties":{"id":{"$ref":"#\/components\/schemas\/DepartmentId"},"name":{"$ref":"#\/components\/schemas\/DepartmentName"},"mailAccountId":{"type":"string","minLength":8,"maxLength":8,"pattern":"^[a-z0-9]+$"},"onlineForMessages":{"type":"boolean"},"onlineForChats":{"type":"boolean"},"onlineForPhones":{"type":"boolean"},"agentCount":{"type":"integer","format":"int32","minimum":0},"agentIds":{"type":"array","items":{"$ref":"#\/components\/schemas\/AgentId"}}}},"DepartmentName":{"type":"string","minLength":1,"maxLength":191},"Problem":{"type":"object","description":"Error detail following the RFC 7807 \"problem+json\" convention. Describes a single problem that occurred while processing the request.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}}},"ListMeta":{"type":"object","description":"Metadata describing a list response envelope. Admin-configuration lists are returned in full up to a server-side cap rather than paged, so the envelope reports how many items were returned and whether the cap hid any of them.","required":["count","hasMore"],"properties":{"count":{"type":"integer","format":"int32","minimum":0,"description":"Number of items returned in the data array."},"hasMore":{"type":"boolean","description":"True when the server-side cap truncated the result and further items exist that this response does not contain. Narrow the request with filter to see them."}}},"TicketFieldDefinitionType":{"type":"string","description":"The kind of value stored by the field.","enum":["Boolean","String","PostalAddress","ListSingleValued","ListMultiValued"]},"TicketFieldDefinition":{"type":"object","required":["id","code","name","type","description","isAlwaysVisible","isArchived"],"properties":{"id":{"type":"integer","format":"int64","minimum":1,"description":"Numeric identifier of the field definition."},"code":{"type":"string","description":"Stable string code of the field definition."},"name":{"type":"string","description":"Human-readable display name."},"type":{"$ref":"#\/components\/schemas\/TicketFieldDefinitionType"},"description":{"type":"string","description":"Help text shown to users; may be empty."},"isAlwaysVisible":{"type":"boolean","description":"Whether the field is always shown regardless of value."},"isArchived":{"type":"boolean","description":"Whether the definition has been archived."},"checkboxDescription":{"type":"string","description":"Label shown next to the checkbox; present for Boolean fields."},"stringValidator":{"type":"string","description":"Regular expression the value must match; present for String fields that use a validator, absent for unconstrained text. Predefined validators (e-mail, URL, phone, ...) are exposed as the pattern they stand for."},"availableValues":{"type":"array","description":"Selectable options; present for list fields.","items":{"type":"string"}}}},"TicketFieldDefinitionListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/TicketFieldDefinition"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"}}},"TicketFieldDefinitionResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#\/components\/schemas\/TicketFieldDefinition"}}},"TicketActivityRecord":{"type":"object","required":["agentId","activityType","activityFrom"],"properties":{"agentId":{"$ref":"#\/components\/schemas\/AgentId"},"activityType":{"$ref":"#\/components\/schemas\/ActivityType"},"activityFrom":{"type":"string","format":"date-time","description":"When the activity started, as an RFC 3339 date-time in UTC."},"activityTo":{"type":["string","null"],"format":"date-time","description":"When the activity ended, as an RFC 3339 date-time in UTC. Null if still active."}}},"TicketActivityList":{"type":"object","required":["results","truncated"],"properties":{"results":{"type":"array","items":{"$ref":"#\/components\/schemas\/TicketActivityRecord"}},"truncated":{"type":"boolean","description":"True if more than 1000 results exist. Narrow the date range to retrieve all data."}}}},"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","name":"apikey","in":"header"}}},"security":[{"ApiKeyHeader":[]}],"tags":[{"name":"agents","description":"Agent resources and their ticket activity history"},{"name":"agent-worktime","description":"Agent online status and worktime history"},{"name":"agent-availability","description":"Agent availability history for departments and services"},{"name":"department","description":"Manage departments in the system."},{"name":"ticket-field-definitions","description":"Read ticket field definitions."},{"name":"tickets","description":"Ticket resources and their agent activity history"}]}