en	# 20 API

en	### Overview The Zabbix API allows you to programmatically retrieve and modify configuration of Zabbix and provides access to historical data. It is widely used to: - create new applications to work with Zabbix; - integrate Zabbix into a third-party software; - automate routine tasks. The Zabbix API is an HTTP-based API, and it is shipped as a part of the web frontend. It uses the JSON-RPC 2.0 protocol, which means two things: - the API consists of a set of separate methods; - requests and responses between the clients and the API are encoded using the JSON format. For more information about the protocol and JSON, see the [JSON-RPC 2.0 specification](http://www.jsonrpc.org/specification) and the [JSON format homepage](http://json.org/). For more information about integrating Zabbix functionality into your Python applications, see the [zabbix_utils](https://github.com/zabbix/python-zabbix-utils) Python library for Zabbix API.
pt-br	### Visão geral A API do Zabbix permite recuperar e modificar programaticamente a configuração do Zabbix e fornece acesso a dados históricos. Ela é amplamente utilizada para: - criar novos aplicativos para trabalhar com o Zabbix; - integrar o Zabbix a um software de terceiros; - automatizar tarefas rotineiras. A API do Zabbix é uma API baseada em HTTP e é fornecida como parte do frontend web. Ela utiliza o protocolo JSON-RPC 2.0, o que significa duas coisas: - a API consiste em um conjunto de métodos separados; - as solicitações e respostas entre os clientes e a API são codificadas usando o formato JSON. Para mais informações sobre o protocolo e o JSON, consulte a [especificação JSON-RPC 2.0](http://www.jsonrpc.org/specification) e a [página inicial do formato JSON](http://json.org/). Para mais informações sobre como integrar a funcionalidade do Zabbix em seus aplicativos Python, consulte a biblioteca Python [zabbix_utils](https://github.com/zabbix/python-zabbix-utils) para a API do Zabbix.

en	### Structure The API consists of a number of methods that are nominally grouped into separate APIs. Each of the methods performs one specific task. For example, the `host.create` method belongs to the *host* API and is used to create new hosts. Historically, APIs are sometimes referred to as "classes". ::: notetip Most APIs contain at least four methods: `get`, `create`, `update` and `delete` for retrieving, creating, updating and deleting data respectively, but some APIs may provide a totally different set of methods. :::
pt-br	### Estrutura A API consiste em vários métodos que são agrupados nominalmente em APIs separadas. Cada um dos métodos executa uma tarefa específica. Por exemplo, o método `host.create` pertence à API *host* e é usado para criar novos hosts. Historicamente, as APIs às vezes são chamadas de "classes". ::: notetip A maioria das APIs contém pelo menos quatro métodos: `get`, `create`, `update` e `delete` para recuperar, criar, atualizar e excluir dados, respectivamente, mas algumas APIs podem fornecer um conjunto totalmente diferente de métodos. :::

en	### Performing requests Once you have set up the frontend, you can use remote HTTP requests to call the API. To do that, you need to send HTTP POST requests to the `api_jsonrpc.php` file located in the frontend directory. For example, if your Zabbix frontend is installed under `https://example.com/zabbix`, an HTTP request to call the `apiinfo.version` method may look like this: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}' ``` The request must have the `Content-Type` header set to one of these values: `application/json-rpc`, `application/json` or `application/jsonrequest`. The request object must contain the following properties: - `jsonrpc` - the version of the JSON-RPC protocol used by the API (Zabbix API implements JSON-RPC version 2.0); - `method` - the API method being called; - `params` - the parameters that will be passed to the API method; - `id` - an arbitrary identifier of the request (if omitted, the API treats the request as a [notification](https://www.jsonrpc.org/specification#notification)). If the request is correct, the response returned by the API should look like this: ```json { "jsonrpc": "2.0", "result": "7.4.0", "id": 1 } ``` The response object, in turn, contains the following properties: - `jsonrpc` - the version of the JSON-RPC protocol; - `result` - the data returned by the method; - `id` - an identifier of the corresponding request.
pt-br	### Realizando solicitações Depois de configurar o frontend, você pode usar solicitações HTTP remotas para chamar a API. Para isso, é necessário enviar solicitações HTTP POST para o arquivo `api_jsonrpc.php` localizado no diretório do frontend. Por exemplo, se o seu frontend do Zabbix estiver instalado em `https://example.com/zabbix`, uma solicitação HTTP para chamar o método `apiinfo.version` pode ser assim: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}' ``` O cabeçalho da solicitação deve ser definido como um destes valores: `application/json-rpc`, `application/json` ou `application/jsonrequest`. O objeto da solicitação deve conter as seguintes propriedades: - `jsonrpc` - a versão do protocolo JSON-RPC usada pela API (a API do Zabbix implementa a versão 2.0 do JSON-RPC); - `method` - o método da API que está sendo chamado; - `params` - os parâmetros que serão passados para o método da API; - `id` - um identificador arbitrário da solicitação (se omitido, a API trata a solicitação como uma [notificação](https://www.jsonrpc.org/specification#notification)). Se a solicitação estiver correta, a resposta retornada pela API deve ser semelhante a esta: ```json { "jsonrpc": "2.0", "result": "7.4.0", "id": 1 } ``` O objeto de resposta, por sua vez, contém as seguintes propriedades: - `jsonrpc` - a versão do protocolo JSON-RPC; - `result` - os dados retornados pelo método; - `id` - um identificador da solicitação correspondente.

en	### Example workflow The following section will walk you through some examples of usage in a greater detail.
pt-br	### Exemplo de fluxo de trabalho A seção a seguir irá guiá-lo por alguns exemplos de uso em maior detalhe.

en	#### Authentication To access any data in Zabbix, you need to either: - use an existing [API token](/manual/web_interface/frontend_sections/users/api_tokens) (created in Zabbix frontend or using the [Token API](/manual/api/reference/token)); - use an authentication token obtained with the [user.login](/manual/api/reference/user/login) method. For example, if you wanted to obtain a new authentication token by logging in as a standard *Admin* user, then a JSON request would look like this: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}' ``` If you provided the credentials correctly, the response returned by the API should contain the user authentication token: ```json { "jsonrpc": "2.0", "result": "0424bd59b807674191e7d77572075f33", "id": 1 } ```
pt-br	#### Autenticação Para acessar qualquer dado no Zabbix, você precisa: - usar um [token de API](/manual/web_interface/frontend_sections/users/api_tokens) existente (criado no frontend do Zabbix ou usando a [API de Token](/manual/api/reference/token)); - usar um token de autenticação obtido com o método [user.login](/manual/api/reference/user/login). Por exemplo, se você quiser obter um novo token de autenticação fazendo login como o usuário padrão *Admin*, a solicitação JSON seria assim: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}' ``` Se você forneceu as credenciais corretamente, a resposta retornada pela API deve conter o token de autenticação do usuário: ```json { "jsonrpc": "2.0", "result": "0424bd59b807674191e7d77572075f33", "id": 1 } ```

en	#### Authorization methods
pt-br	#### Métodos de autorização

en	##### By "Authorization" header All API requests require an authentication or an API token. You can provide the credentials by using the Authorization header in the request: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33' ``` ::: noteimportant If you are experiencing authentication issues, see [Authorization header forwarding](/manual/installation/known_issues#authorization-header-forwarding). ::: Zabbix API accepts headers in a case-insensitive way (e.g., `authorization`, `Authorization`, and `AUTHORIZATION` are treated the same). The Authorization header is supported in cross-origin requests ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)).
pt-br	##### Pelo cabeçalho "Authorization" Todas as solicitações da API exigem autenticação ou um token de API. Você pode fornecer as credenciais usando o cabeçalho Authorization na solicitação: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33' ``` ::: noteimportant Se você estiver enfrentando problemas de autenticação, consulte [Encaminhamento do cabeçalho Authorization](/manual/installation/known_issues#authorization-header-forwarding). ::: A API do Zabbix aceita cabeçalhos de forma case-insensitive (por exemplo, `authorization`, `Authorization` e `AUTHORIZATION` são tratados da mesma forma). O cabeçalho Authorization é suportado em solicitações de origem cruzada ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)).

en	##### By Zabbix cookie A *"zbx_session"* cookie is used to authorize an API request from Zabbix UI performed using JavaScript (from a module or a custom widget).
pt-br	##### Por cookie do Zabbix Um cookie *"zbx_session"* é usado para autorizar uma solicitação de API da interface do Zabbix realizada usando JavaScript (de um módulo ou de um widget personalizado).

en	#### Retrieving hosts Now you have a valid user authentication token that can be used to access the data in Zabbix. For example, you can use the [host.get](/manual/api/reference/host/get) method to retrieve the IDs, host names and interfaces of all the configured [hosts](/manual/api/reference/host/object): Request: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data @data.json ``` ::: notetip `data.json` is a file that contains a JSON query. Instead of a file, you can pass the query in the `--data` argument. ::: data.json ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "output": [ "hostid", "host" ], "selectInterfaces": [ "interfaceid", "ip" ] }, "id": 2 } ``` The response object will contain the requested data about the hosts: ```json { "jsonrpc": "2.0", "result": [ { "hostid": "10084", "host": "Zabbix server", "interfaces": [ { "interfaceid": "1", "ip": "127.0.0.1" } ] } ], "id": 2 } ``` ::: notetip For performance reasons it is always recommended to list the object properties you want to retrieve. Thus, you will avoid retrieving everything. :::
pt-br	#### Recuperando hosts Agora você tem um token de autenticação de usuário válido que pode ser usado para acessar os dados no Zabbix. Por exemplo, você pode usar o método [host.get](/manual/api/reference/host/get) para recuperar os IDs, nomes de host e interfaces de todos os [hosts](/manual/api/reference/host/object) configurados: Requisição: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data @data.json ``` ::: notetip `data.json` é um arquivo que contém uma consulta JSON. Em vez de um arquivo, você pode passar a consulta no argumento `--data`. ::: data.json ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "output": [ "hostid", "host" ], "selectInterfaces": [ "interfaceid", "ip" ] }, "id": 2 } ``` O objeto de resposta conterá os dados solicitados sobre os hosts: ```json { "jsonrpc": "2.0", "result": [ { "hostid": "10084", "host": "Zabbix server", "interfaces": [ { "interfaceid": "1", "ip": "127.0.0.1" } ] } ], "id": 2 } ``` ::: notetip Por motivos de desempenho, é sempre recomendado listar as propriedades do objeto que você deseja recuperar. Assim, você evitará recuperar tudo. :::

en	#### Creating a new item Now, create a new [item](/manual/api/reference/item/object) on the host "Zabbix server" using the data you have obtained from the previous `host.get` request. This can be done using the [item.create](/manual/api/reference/item/create) method: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}' ``` A successful response will contain the ID of the newly created item, which can be used to reference the item in the following requests: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "24759" ] }, "id": 3 } ``` ::: notetip The `item.create` method as well as other *create methods* can also accept arrays of objects and create multiple items with one API call. :::
pt-br	#### Criando um novo item Agora, crie um novo [item](/manual/api/reference/item/object) no host "Zabbix server" usando os dados obtidos na solicitação anterior `host.get`. Isso pode ser feito usando o método [item.create](/manual/api/reference/item/create): ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}' ``` Uma resposta bem-sucedida conterá o ID do item recém-criado, que pode ser usado para referenciar o item nas próximas solicitações: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "24759" ] }, "id": 3 } ``` ::: notetip O método `item.create`, assim como outros *métodos de criação*, também pode aceitar arrays de objetos e criar múltiplos itens com uma única chamada à API. :::

en	#### Creating multiple triggers Thus, if *create methods* accept arrays, you can add multiple [triggers](/manual/api/reference/trigger/object), for example, this one: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5",},{"description":"Too many processes on {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300",}],"id":4}' ``` The successful response will contain the IDs of the newly created triggers: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "17369", "17370" ] }, "id": 4 } ```
pt-br	#### Criando múltiplos triggers Assim, se os *métodos de criação* aceitarem arrays, você pode adicionar múltiplos [triggers](/manual/api/reference/trigger/object), por exemplo, este: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5",},{"description":"Too many processes on {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300",}],"id":4}' ``` A resposta bem-sucedida conterá os IDs dos triggers recém-criados: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "17369", "17370" ] }, "id": 4 } ```

en	#### Updating an item Enable an item by setting its status to "0": ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}' ``` The successful response will contain the ID of the updated item: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "10092" ] }, "id": 5 } ``` ::: notetip The `item.update` method as well as other *update methods* can also accept arrays of objects and update multiple items with one API call. :::
pt-br	#### Atualizando um item Habilite um item definindo seu status como "0": ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}' ``` A resposta bem-sucedida conterá o ID do item atualizado: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "10092" ] }, "id": 5 } ``` ::: notetip O método `item.update`, assim como outros *métodos de atualização*, também pode aceitar arrays de objetos e atualizar vários itens com uma única chamada de API. :::

en	#### Updating multiple triggers Enable multiple triggers by setting their status to "0": ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}' ``` The successful response will contain the IDs of the updated triggers: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "13938", "13939" ] }, "id": 6 } ``` ::: notetip This is the preferred method of updating. Some API methods, such as the `host.massupdate` allow to write a simpler code. However, it is not recommended to use these methods as they will be removed in the future releases. :::
pt-br	#### Atualizando múltiplos triggers Habilite múltiplos triggers definindo seu status como "0": ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}' ``` A resposta bem-sucedida conterá os IDs dos triggers atualizados: ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "13938", "13939" ] }, "id": 6 } ``` ::: notetip Este é o método preferencial de atualização. Alguns métodos da API, como o `host.massupdate`, permitem escrever um código mais simples. No entanto, não é recomendado usar esses métodos, pois eles serão removidos em versões futuras. :::

en	#### Error handling Up to the present moment, everything you have tried has worked fine. But what would happen if you tried making an incorrect call to the API? Try to create another host by calling [host.create](/manual/api/reference/host/create) but omitting the mandatory `groups` parameter: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux server","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}' ``` The response will then contain an error message: ```json { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params.", "data": "No groups for host \"Linux server\"." }, "id": 7 } ``` If an error has occurred, instead of the `result` property, the response object will contain the `error` property with the following data: - `code` - an error code; - `message` - a short error summary; - `data` - a more detailed error message. Errors can occur in various cases, such as, using incorrect input values, a session timeout or trying to access non-existing objects. Your application should be able to gracefully handle these kinds of errors.
pt-br	#### Tratamento de erros Até o momento, tudo o que você tentou funcionou bem. Mas o que aconteceria se você tentasse fazer uma chamada incorreta para a API? Tente criar outro host chamando [host.create](/manual/api/reference/host/create), mas omitindo o parâmetro obrigatório `groups`: ```bash curl --request POST \ --url 'https://example.com/zabbix/api_jsonrpc.php' \ --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \ --header 'Content-Type: application/json-rpc' \ --data '{"jsonrpc":"2.0","method":"host.create","params":{"host":"Linux server","interfaces":[{"type":1,"main":1,"useip":1,"ip":"192.168.3.1","dns":"","port":"10050"}]},"id":7}' ``` A resposta então conterá uma mensagem de erro: ```json { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params.", "data": "No groups for host \"Linux server\"." }, "id": 7 } ``` Se ocorrer um erro, em vez da propriedade `result`, o objeto de resposta conterá a propriedade `error` com os seguintes dados: - `code` - um código de erro; - `message` - um resumo curto do erro; - `data` - uma mensagem de erro mais detalhada. Erros podem ocorrer em vários casos, como, uso de valores de entrada incorretos, expiração de sessão ou tentativa de acessar objetos inexistentes. Sua aplicação deve ser capaz de lidar graciosamente com esses tipos de erros.

en	### API versions To simplify API versioning, since Zabbix 2.0.4, the version of the API matches the version of Zabbix itself. You can use the [apiinfo.version](/manual/api/reference/apiinfo/version) method to find out the version of the API you are working with. This can be useful for adjusting your application to use version-specific features. Zabbix guarantees feature backward compatibility inside a major version. When making backward incompatible changes between major releases, Zabbix usually leaves the old features as deprecated in the next release, and only removes them in the release after that. Occasionally, Zabbix may remove features between major releases without providing any backward compatibility. It is important that you never rely on any deprecated features and migrate to newer alternatives as soon as possible. ::: notetip You can follow all the changes made to the API in the [API changelog](/manual/api/changes). :::
pt-br	### Versões da API Para simplificar o versionamento da API, desde o Zabbix 2.0.4, a versão da API corresponde à versão do próprio Zabbix. Você pode usar o método [apiinfo.version](/manual/api/reference/apiinfo/version) para descobrir a versão da API com a qual está trabalhando. Isso pode ser útil para ajustar seu aplicativo para usar recursos específicos da versão. O Zabbix garante compatibilidade de recursos com versões anteriores dentro de uma versão principal. Ao fazer alterações incompatíveis com versões anteriores entre versões principais, o Zabbix geralmente deixa os recursos antigos como obsoletos na próxima versão e só os remove na versão seguinte. Ocasionalmente, o Zabbix pode remover recursos entre versões principais sem fornecer nenhuma compatibilidade com versões anteriores. É importante que você nunca dependa de recursos obsoletos e migre para alternativas mais recentes o mais rápido possível. ::: notetip Você pode acompanhar todas as alterações feitas na API no [API changelog](/manual/api/changes). :::

en	### Further reading Now, you have enough knowledge to start working with the Zabbix API, however, do not stop here. For further reading you are advised to have a look at the [list of available APIs](/manual/api/reference).
pt-br	### Leitura adicional Agora, você tem conhecimento suficiente para começar a trabalhar com a API do Zabbix, no entanto, não pare por aqui. Para leitura adicional, recomenda-se dar uma olhada na [lista de APIs disponíveis](/manual/api/reference).