Znuny REST API – Setup, Endpoints & Examples

In this guide: Activate and use the Znuny REST API (Generic Interface) for automation, monitoring, self-service, and AI platforms like OpenTicketAI.

Related: Extend the Generic Interface · Web Services · Znuny Docker · Add-ons & plugins · OpenTicketAI for Znuny

The Znuny REST API is part of the Generic Interface — the main integration layer for automation, monitoring hooks, portals, and on-premise AI such as OpenTicketAI. Traffic uses HTTP(S) and JSON.

AI automation instead of manual REST coding?

To classify and route tickets automatically, use the OpenTicketAI Runtime — Docker on-premise, connected via the same REST API. See section 7 below.

1. Architecture & basics

Znuny exposes the Generic Interface via REST and SOAP. The REST API supports:

• Ticket operations — create, read, update, delete
• Articles — posts and attachments
• History & search — ticket history and filtered search

Note: A fresh install has no pre-configured web services. Create them under Processes & Automation → Web Services in the admin area.

2. Configuration

2.1 Enable the Generic Interface

1. SysConfig → GenericInterface.Transport → select REST (HTTP).
2. Under AdminGenericInterfaceTransportHTTPREST, set timeouts, host header, and debug level.
3. In GenericInterface.Operation, define operations (e.g. TicketCreate, TicketSearch, TicketGet, TicketUpdate, TicketDelete, TicketHistoryGet) and activate them.

2.2 Base URL & authentication

• Base URL (adjust path for your install):

  https://YOUR-SERVER/znuny/nph-genericinterface.pl/Webservice/<YourServiceName>/

  Some installs use /otrs/ instead of /znuny/ — verify in the web service configuration.

• Authentication

  • Znuny session (SessionID) or UserLogin + Password
  • API keys / tokens (via SysConfig and requester setup)
  • Always use HTTPS in production

2.3 Create a web service (short workflow)

1. Admin → Web Services → Add Web Service
2. Define REST provider with the operations you need
3. Optionally configure a requester for outbound calls
4. Save and use the debugger when troubleshooting

More on the Generic Interface: Web Services.

3. Endpoints & HTTP methods

URLs follow /Webservice/<ServiceName>/<OperationName>. Parameters and responses are typically under a JSON Data object.

3.1 TicketCreate (POST)

URL: /Webservice/<ServiceName>/TicketCreate · Method: POST

Creates a ticket and the first article.

Parameter	Type	Required	Description
SessionID	Integer	Yes¹	Session ID or UserLogin+Password
UserLogin	String	Yes²	Agent login
Password	String	Yes²	Password
Ticket.Title	String	Yes	Subject
Ticket.Queue	String	Yes	Queue name or ID
Ticket.State	String	Yes	e.g. new
Ticket.Priority	String	Yes	e.g. 3 normal
Ticket.CustomerUser	String	Yes	Customer email or login
Article.Subject	String	Yes	First article subject
Article.Body	String	Yes	Body text
Article.MimeType	String	Yes	text/plain or text/html

¹ SessionID or UserLogin+Password. ² When no SessionID.

Example request:

POST /znuny/nph-genericinterface.pl/Webservice/MyConnectorREST/TicketCreate HTTP/1.1
Host: znuny.example.com
Content-Type: application/json

{
  "UserLogin": "agent",
  "Password": "secret",
  "Ticket": {
    "Title": "Server unreachable",
    "Queue": "Support",
    "State": "new",
    "Priority": "3 normal",
    "CustomerUser": "customer@example.com"
  },
  "Article": {
    "Subject": "Initial report",
    "Body": "The server has not responded since 08:00.",
    "MimeType": "text/plain"
  }
}

Example response:

{
  "TicketID": "12345",
  "ArticleID": "67890",
  "Error": {
    "ErrorCode": "",
    "ErrorMessage": ""
  }
}

3.2 TicketSearch (GET)

URL: /Webservice/<ServiceName>/TicketSearch · Method: GET or POST (depends on mapping)

Parameter	Type	Required	Description
UserLogin	String	Yes¹	With Password or SessionID
Password	String	Yes¹
SessionID	Integer	Yes¹
Title	String	No	Wildcard, e.g. %Server%
QueueIDs	Integer[]	No	Queue IDs
States	String[]	No	new, open, …
Limit	Integer	No	Max results

Example request (GET, URL-encoded):

GET /znuny/nph-genericinterface.pl/Webservice/MyConnectorREST/TicketSearch?UserLogin=agent&Password=secret&Title=%Server% HTTP/1.1
Host: znuny.example.com

Example response:

{
  "TicketID": ["12345", "12346"],
  "Error": {
    "ErrorCode": "",
    "ErrorMessage": ""
  }
}

3.3 TicketGet (GET)

URL: /Webservice/<ServiceName>/TicketGet

Returns ticket details including articles and optional dynamic fields. Key parameters: TicketID, AllArticles, Attachments, DynamicFields.

3.4 TicketUpdate (PUT)

URL: /Webservice/<ServiceName>/TicketUpdate

Updates ticket fields and can add a new article. Parameters: TicketID, Ticket.State, Ticket.Queue, Article.Body, dynamic fields.

3.5 TicketDelete (DELETE)

URL: /Webservice/<ServiceName>/TicketDelete

Permanently deletes ticket(s). Parameter: TicketID (string or array).

3.6 TicketHistoryGet (GET)

URL: /Webservice/<ServiceName>/TicketHistoryGet

History for one or more TicketID values.

Need an endpoint that Znuny does not provide?

Read Extend the Znuny REST API with custom Generic Interface operations for the complete development path: Perl backend, SysConfig registration, REST routing, package lifecycle, security, and testing.

4. Errors & debugging

• Responses often include Error.ErrorCode and Error.ErrorMessage
• Set Debug-Level to Debug in the web service debugger for database log entries
• On 401/403: check credentials, requester mapping, and HTTPS

5. Use cases

Scenario	Description
Monitoring	Tickets from Nagios, Zabbix, Prometheus
CRM sync	Fields and state from external CRM
Self-service	Customer portal creates tickets via REST
AI routing	OpenTicketAI reads and writes via REST

6. Python SDK: otai-ts-connector

The current open-source client is otai-ts-connector (Apache-2.0) — unified for Znuny, OTOBO, Zammad, and KIX. It replaces the former PyPI packages znuny and otobo.

pip install git+https://github.com/Softoft-Orga/otai-ts-connector.git

import asyncio

from otai_ts_connector import (
    BuildTicketSystemParams,
    TicketSystemProvider,
    build_ticket_system,
)


async def main() -> None:
    service = build_ticket_system(
        BuildTicketSystemParams(
            kind=TicketSystemProvider.ZNUNY,
            base_url="https://znuny.example.com/znuny/nph-genericinterface.pl",
            username="open_ticket_ai",
            password="…",
            webservice_name="OpenTicketAI",
        ),
    )
    await service.test_connection()
    ticket = await service.get_ticket("12345")
    print(ticket.subject)


asyncio.run(main())

HTTP reference and OpenAPI: OpenTicketAI routes (/ticket-create, /queue-list, …) are the same for Znuny — only the path prefix is /znuny/nph-genericinterface.pl/…. HTTP examples and the OpenAPI 3.1 spec: OTOBO REST API — OpenTicketAI webservice and /openapi-openticketai.yaml.

Provider docs in the repository: OTOBO / Znuny.

7. OpenTicketAI Runtime & Znuny connector

To automate the Znuny REST API with AI, use the OpenTicketAI Runtime — on-premise classification, prioritization, and routing.

  Incoming mail / REST  ──►  Znuny (Generic Interface)
                                    │
                                    ▼
                          OpenTicketAI Runtime (Docker)
                                    │
                                    ▼
                          TicketUpdate / routing via REST

Install:

pip install open-ticket-ai otai-hf-local otai-znuny-znuny

Package	Role
open-ticket-ai	Orchestration, pipelines
otai-hf-local	Local AI models
otai-znuny-znuny	Znuny REST connector

Example config.yaml:

connector:
  type: znuny
  url: https://znuny.example.com
  username: otai-bot
  password: '${ZNUNY_PASSWORD}'

model:
  provider: hf-local
  model_name: softoft/ticket-classifier-de

routing:
  default_queue: 'Unclassified'
  rules:
    - category: 'Network'
      queue: 'IT-Infrastructure'
      priority: '4 high'

Feature	Manual REST	OpenTicketAI + connector
Classification	Manual	Fully automatic (AI)
Data protection	Local	100% on-premise
Setup effort	High	YAML config

Learn more: openticketai.com/solutions/znuny/ · OpenTicketAI docs · Softoft demo

Conclusion

The Znuny REST API is flexible and extensible via the Generic Interface. With proper web services, HTTPS, and optionally OpenTicketAI or otai-ts-connector, you integrate Znuny cleanly into your stack and AI strategy.

Znuny automation & custom integrations

Integrate Znuny seamlessly with your IT landscape: We implement web services, business process workflows, and REST integrations.

Discuss automation

Frequently asked questions

How do I set up the Znuny REST API for the first time?

To activate and use the Znuny REST API, which is part of the Generic Interface, you need to perform a few configuration steps as a fresh Znuny installation does not include pre-configured web services. First, navigate to SysConfig in the admin area, then to GenericInterface.Transport, and select REST (HTTP). You can also adjust specific settings like timeouts and debug levels under AdminGenericInterfaceTransportHTTPREST. Next, you must define and activate the specific operations you need, such as TicketCreate or TicketSearch, within GenericInterface.Operation. After enabling the interface, proceed to Admin → Web Services to Add Web Service. Here, you'll define a REST provider that specifies the operations available through this web service. Optionally, you can also configure a requester for outbound calls if Znuny needs to integrate with external systems. Always save your configuration and use the built-in debugger for troubleshooting during setup.

Quellen / Sources:

• Znuny REST API – Setup, Endpoints & Examples
• Znuny Web Services - REST API

What are the authentication methods for the Znuny REST API, and what are the best practices?

Authenticating against the Znuny REST API can be done using several methods, with best practices emphasizing security, especially in production environments. The primary methods include using a Znuny SessionID or providing a UserLogin combined with a Password. For enhanced security and flexibility, API keys or tokens can also be configured via SysConfig and the requester setup within the Generic Interface. It is a critical best practice to always use HTTPS in production to encrypt all communication and protect sensitive credentials from interception. The base URL for your API calls will typically follow the format https://YOUR-SERVER/znuny/nph-genericinterface.pl/Webservice/<YourServiceName>/, though some installations might use /otrs/ instead of /znuny/, which should be verified in your web service configuration.

Quellen / Sources:

• Znuny REST API – Setup, Endpoints & Examples
• API — Znuny documentation

What are the main operations available through the Znuny REST API, and how are they structured?

The Znuny REST API, built on the Generic Interface, supports a range of operations primarily focused on ticket management, articles, history, and search functionalities. The URLs for these operations follow a consistent structure: /Webservice/<ServiceName>/<OperationName>. Parameters and responses are typically encapsulated within a JSON Data object. Key operations include TicketCreate (using POST to create new tickets and their first article), TicketSearch (using GET or POST to find tickets based on various criteria like title, queue, or state), TicketGet (using GET to retrieve detailed ticket information, including articles and dynamic fields), TicketUpdate (using PUT to modify ticket attributes or add new articles), TicketDelete (using DELETE to permanently remove tickets), and TicketHistoryGet (using GET to fetch the history of one or more tickets). Each operation has specific required and optional parameters detailed in the web service configuration.

Quellen / Sources:

• Znuny REST API – Setup, Endpoints & Examples
• Znuny Web Services - REST API

Can you provide an example of how to create a ticket using the Znuny REST API?

To create a ticket using the Znuny REST API, you would typically use the TicketCreate operation with an HTTP POST request. This operation allows you to simultaneously create a new ticket and its initial article. The request body must be in JSON format and include essential parameters for both the ticket and the article. For authentication, you'll need either a SessionID or a UserLogin and Password. Key ticket parameters include Ticket.Title, Ticket.Queue, Ticket.State (e.g., new), Ticket.Priority (e.g., 3 normal), and Ticket.CustomerUser (customer's email or login). For the article, you'll need Article.Subject, Article.Body, and Article.MimeType (e.g., text/plain). A successful response will typically return the TicketID and ArticleID of the newly created entries. For instance, a request might look like: POST /znuny/nph-genericinterface.pl/Webservice/MyConnectorREST/TicketCreate with a JSON payload containing these details.

Quellen / Sources:

• Znuny REST API – Setup, Endpoints & Examples
• GenericTicketConnectorREST - Znuny Documentation

How can I search for tickets using the Znuny REST API?

Searching for tickets via the Znuny REST API is commonly performed using the TicketSearch operation, which can be configured to accept either GET or POST requests depending on your web service mapping. When using GET, parameters are typically URL-encoded. You'll need to authenticate with UserLogin and Password or a SessionID. The TicketSearch operation supports various parameters to filter results, such as Title (which can use wildcards like %Server%), QueueIDs (an array of integer IDs), States (an array of strings like new, open), and Limit to control the maximum number of results returned. For example, a GET request to find tickets with "Server" in their title might be: GET /znuny/nph-genericinterface.pl/Webservice/MyConnectorREST/TicketSearch?UserLogin=agent&Password=secret&Title=%Server%. The API will then return an array of TicketID values matching your criteria.

Quellen / Sources:

• Znuny REST API – Setup, Endpoints & Examples
• Znuny Web Services - REST API

What should I do if a required REST API endpoint is not available in Znuny?

If you find that the standard Znuny REST API does not provide a specific endpoint or operation you require for your integration needs, you have the flexibility to extend it with custom Generic Interface operations. This process involves a full development path, starting with creating the necessary Perl backend modules to implement your desired logic. After developing the backend, you must register these new operations within SysConfig, making them available to the Generic Interface. Subsequently, you configure the REST routing within your web service definition to map a specific URL path to your custom operation. This allows external systems to call your new endpoint. The extension process also covers aspects like package lifecycle management, ensuring proper security, and thorough testing to guarantee functionality and stability. This advanced capability allows Znuny to be highly adaptable to unique automation and integration scenarios.

Quellen / Sources:

• Znuny REST API – Setup, Endpoints & Examples
• Extend the Generic Interface