<commit_before>Introduction
************

Zammad is a web based open source helpdesk/ticket system with many features
to manage customer communication via several channels like telephone, facebook,
twitter, chat and e-mails.

This chapter describes the Zammad API v1.

The API
=======

Zammad provides a REST/JSON API. Its endpoints are documented with the HTTP method for the request and a partial resource::

   GET /api/v1/users

The full URL looks like::

   https://your_zammad/api/v1/users

Curly braces {} indicate values you have to supply for the URL::

   GET /api/v1/users/{id}


Authentication
==============

Zammad supports three different authentication methods for API.


HTTP Basic Authentication (username/password)
---------------------------------------------

The username/password must be provided as HTTP header in the HTTP call. The Zammad admin can enable/disable the authentication method in the admin interface. Read more about `HTTP basic authentication on Wikipedia <https://en.wikipedia.org/wiki/Basic_access_authentication>`_.

.. code-block:: sh

   $ curl -u {username}:{password} https://your_zammad/api/v1/users


HTTP Token Authentication (access token)
----------------------------------------

The access token must be provided as HTTP header in the HTTP call. Each user needs to create its own access token in the user preferences. The Zammad admin can enable/disable the authentication method in the admin interface.

.. code-block:: sh

   $ curl -H "Authorization: Token token={your_token}" https://your_zammad/api/v1/users


OAuth2 (token access)
---------------------

The Zammad API supports OAuth2 authorization. In order to create OAuth2 tokens for an external application, the Zammad user needs to create an application in the admin interface. The access token then has to be given within the HTTP header:

.. code-block:: sh

   $ curl -H "Authorization: Bearer {your_token}" https://your_zammad/api/v1/users


Request Format
==============

Zammad uses JSON for its API, so you need to set a "Content-Type: application/json" in each HTTP call. Otherwise the response will be text/html.

::

   POST /api/v1/users/{id} HTTP/1.1
   Content-Type: application/json

   {
     "name":"<NAME>",
     "organization_id": 123,
     "note":"some note"
   }

Example CURL Requests
=====================

.. code-block:: sh

   # Get information
   $ curl -u <EMAIL>:test123 https://xxx.zammad.com/api/v1/tickets/3

   # Put information
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X PUT -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3

   # Post information
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3


Example CURL Requests (for tickets and users)
=============================================

.. code-block:: sh

   # Create a new ticket
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{"title":"Help me!","group": "Users","article":{"subject":"some subject","body":"some message","type":"note","internal":false},"customer":"<EMAIL>","note": "some note"}' https://xxx.zammad.com/api/v1/tickets

   # Search for tickets (with contains "some message")::
   $ curl -u <EMAIL>:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=some+message&limit=10&expand=true'

   # Search for tickets (for tickets with state new and open )::
   $ curl -u <EMAIL>:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=state:new%20OR%20state:open&limit=10&expand=true'

   # Create a new user
   curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"<EMAIL>","roles":["Customer"],"password":"<PASSWORD>"}' https://xxx.zammad.com/api/v1/users

   # Create a new user (with welcome email)
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"<EMAIL>","roles":["Customer"],"password":"<PASSWORD>","invite":true}' https://xxx.zammad.com/api/v1/users

   # Search for users
   $ curl -u <EMAIL>:test123 'https://xxx.zammad.com/api/v1/users/search?query=smith&limit=10&expand=true'

.. hint:: For more search examples regarding searching, please see `this page <https://user-docs.zammad.org/en/latest/advanced/search.html>`_ .

Example CURL Request on behalf of a different user<commit_msg> Applyed Zammad 4.0 changes in curl example.<commit_after>Introduction
************

Zammad is a web based open source helpdesk/ticket system with many features
to manage customer communication via several channels like telephone, facebook,
twitter, chat and e-mails.

This chapter describes the Zammad API v1.

The API
=======

Zammad provides a REST/JSON API. Its endpoints are documented with the HTTP method for the request and a partial resource::

   GET /api/v1/users

The full URL looks like::

   https://your_zammad/api/v1/users

Curly braces {} indicate values you have to supply for the URL::

   GET /api/v1/users/{id}


Authentication
==============

Zammad supports three different authentication methods for API.


HTTP Basic Authentication (username/password)
---------------------------------------------

The username/password must be provided as HTTP header in the HTTP call. The Zammad admin can enable/disable the authentication method in the admin interface. Read more about `HTTP basic authentication on Wikipedia <https://en.wikipedia.org/wiki/Basic_access_authentication>`_.

.. code-block:: sh

   $ curl -u {username}:{password} https://your_zammad/api/v1/users


HTTP Token Authentication (access token)
----------------------------------------

The access token must be provided as HTTP header in the HTTP call. Each user needs to create its own access token in the user preferences. The Zammad admin can enable/disable the authentication method in the admin interface.

.. code-block:: sh

   $ curl -H "Authorization: Token token={your_token}" https://your_zammad/api/v1/users


OAuth2 (token access)
---------------------

The Zammad API supports OAuth2 authorization. In order to create OAuth2 tokens for an external application, the Zammad user needs to create an application in the admin interface. The access token then has to be given within the HTTP header:

.. code-block:: sh

   $ curl -H "Authorization: Bearer {your_token}" https://your_zammad/api/v1/users


Request Format
==============

Zammad uses JSON for its API, so you need to set a "Content-Type: application/json" in each HTTP call. Otherwise the response will be text/html.

::

   POST /api/v1/users/{id} HTTP/1.1
   Content-Type: application/json

   {
     "name":"some name",
     "organization_id": 123,
     "note":"some note"
   }

Example CURL Requests
=====================

.. code-block:: sh

   # Get information
   $ curl -u <EMAIL>:test123 https://xxx.zammad.com/api/v1/tickets/3

   # Put information
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X PUT -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3

   # Post information
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{ json: "data" }' https://xxx.zammad.com/api/v1/tickets/3


Example CURL Requests (for tickets and users)
=============================================

.. code-block:: sh

   # Create a new ticket
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{"title":"Help me!","group": "Users","article":{"subject":"some subject","body":"some message","type":"note","internal":false},"customer":"<EMAIL>","note": "some note"}' https://xxx.zammad.com/api/v1/tickets

   # Search for tickets (with contains "some message")::
   $ curl -u <EMAIL>:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=some+message&limit=10&expand=true'

   # Search for tickets (for tickets with state new and open )::
   $ curl -u <EMAIL>:test123 'https://xxx.zammad.com/api/v1/tickets/search?query=state.name:new%20OR%20state.name:open&limit=10&expand=true'

   # Create a new user
   curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"<EMAIL>","roles":["Customer"],"password":"<PASSWORD>"}' https://xxx.zammad.com/api/v1/users

   # Create a new user (with welcome email)
   $ curl -u <EMAIL>:test123 -H "Content-Type: application/json" -X POST -d '{"firstname":"Bob","lastname":"Smith","email":"<EMAIL>","roles":["Customer"],"password":"<PASSWORD>","invite":true}' https://xxx.zammad.com/api/v1/users

   # Search for users
   $ curl -u <EMAIL>:test123 'https://xxx.zammad.com/api/v1/users/search?query=smith&limit=10&expand=true'

.. hint:: For more search examples regarding searching, please see `this page <https://user-docs.zammad.org/en/latest/advanced/search.html>`_ .

Example CURL Request on behalf of a different user
{'fraction_non_alphanumeric': 0.1760595130748422, 'fraction_numerical': 0.014878268710550046, 'mean_word_length': 3.7936250675310643, 'pattern_counts': {'":': 46, '<': 36, '<?xml version=': 0, '>': 36, 'https://': 30, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6147587', 'n_tokens_mistral': 2787, 'n_tokens_neox': 2584, 'n_words': 851}