Znuny REST API – Setup, Endpoints & Examples

Znuny Web Services – REST API

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

Related: 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.

:::tip 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.

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 client: OpenTicketAI znuny

Typed client znuny for TicketCreate, Search, Update. Full guide: OpenTicketAI Znuny Python SDK.

pip install znuny

from znuny import BasicAuth, ClientConfig, TicketOperation, ZnunyClient
from znuny import Article, Ticket, TicketCreate

client = ZnunyClient(
    ClientConfig(
        base_url="https://znuny.example.com",
        webservice_name="MyWebservice",
        operation_url_map={
            TicketOperation.CREATE: "ticket-create",
            TicketOperation.GET: "ticket-get",
            TicketOperation.SEARCH: "ticket-search",
            TicketOperation.UPDATE: "ticket-update",
        },
    )
)
client.login(BasicAuth(user_login="agent", password="secret"))

response = client.create_ticket(
    TicketCreate(
        Ticket=Ticket(
            Title="Server unreachable",
            Queue="Support",
            State="new",
            Priority="3 normal",
            CustomerUser="customer@example.com",
        ),
        Article=Article(
            Subject="Initial report",
            Body="The server has not responded since 08:00.",
            MimeType="text/plain",
        ),
    )
)
print(response.TicketID)

More packages on OpenITSMHub: Python REST API Client, pyznuny.

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 the Python SDK, you integrate Znuny cleanly into your stack and AI strategy.