ContextQMD
Back to Wazuh

API Reference

docs/ref/modules/server-api/api-reference.md

4.14.417.0 KB
Original Source

API Reference

This document covers the key API endpoints with practical examples, the Wazuh Query Language (WQL), error handling, and input validation.

All paths are validated against api/api/spec/spec.yaml (OpenAPI 3.0).
For the complete endpoint specification, refer to the official Wazuh API Reference.

Common Query Parameters

Most GET endpoints accept these standard parameters:

ParameterTypeDefaultDescription
prettybooleanfalseHuman-readable output
wait_for_completebooleanfalseDisable timeout response
offsetint0First element to return
limitint500Max elements to return (max: 100,000)
searchstring—Free-text search (prefix - for complementary)
sortstring—Sort by fields (+ asc, - desc, dot notation for nested)
selectstring—Fields to return (comma-separated)
qstring—WQL query filter
distinctbooleanfalseReturn distinct values

Authentication

Obtain JWT token

bash
curl -u <USER>:<PASSWORD> -k -X POST "https://localhost:55000/security/user/authenticate"
json
{
  "data": {
    "token": "<YOUR_JWT_TOKEN>"
  },
  "error": 0
}

All subsequent requests must include the token:

bash
curl -k -X <METHOD> "https://localhost:55000/<ENDPOINT>" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

Update token expiration

bash
curl -k -X PUT "https://localhost:55000/security/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"auth_token_exp_timeout": 1800}'

Note: Changing security config revokes all existing tokens.

Key Endpoints & Examples

API Info

GET / — Returns API version, hostname, and timestamp.

bash
curl -k -X GET "https://localhost:55000/?pretty=true" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "data": {
    "title": "Wazuh API REST",
    "api_version": "5.0.0",
    "revision": "alpha0",
    "license_name": "GPL 2.0",
    "hostname": "wazuh-manager",
    "timestamp": "2026-02-20T12:00:00Z"
  },
  "error": 0
}

Agents

List agents

GET /agents — Return all agents with optional filters.

bash
# List active agents, limit 5
curl -k -X GET "https://localhost:55000/agents?status=active&limit=5&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

# Filter with WQL: active Ubuntu agents
curl -k -X GET "https://localhost:55000/agents?q=status%3Dactive%3Bos.name~%3Dubuntu&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

# Select specific fields
curl -k -X GET "https://localhost:55000/agents?select=id,name,status,ip&sort=-id&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Key filters: status, os.platform, os.name, os.version, manager, version, group, node_name, name, ip, older_than.

Add agent

POST /agents — Create a new agent. Returns the agent ID and registration key.

bash
curl -k -X POST "https://localhost:55000/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-server-01", "ip": "10.0.10.11"}'
json
{
  "data": {
    "id": "009",
    "key": "MDA5IHdlYi1zZXJ2ZXItMDEgMTAuMC4xMC4xMSA..."
  },
  "error": 0
}

Restart agent

PUT /agents/{agent_id}/restart — Restart a specific agent.

bash
curl -k -X PUT "https://localhost:55000/agents/002/restart?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Delete agents

DELETE /agents — Delete agents by ID or criteria. Requires agents_list and status.

bash
# Delete disconnected agents older than 30 days
curl -k -X DELETE "https://localhost:55000/agents?agents_list=all&status=disconnected&older_than=30d&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

# Delete specific agent permanently
curl -k -X DELETE "https://localhost:55000/agents?agents_list=009&status=all&purge=true&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Agent overview

GET /overview/agents — Full summary: status counts, OS distribution, versions, groups, and last registered agent.

bash
curl -k -X GET "https://localhost:55000/overview/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Groups

List groups

GET /groups — List all agent groups with agent count and checksums.

bash
curl -k -X GET "https://localhost:55000/groups?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Create group

POST /groups — Create a new agent group.

bash
curl -k -X POST "https://localhost:55000/groups?pretty=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group_id": "web-servers"}'

Assign agent to group

PUT /agents/{agent_id}/group/{group_id} — Add an agent to a group.

bash
curl -k -X PUT "https://localhost:55000/agents/002/group/web-servers?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Cluster

Cluster status

GET /cluster/status — Check if the cluster is enabled and running.

bash
curl -k -X GET "https://localhost:55000/cluster/status?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

List nodes

GET /cluster/nodes — List all cluster nodes with type, version, and IP.

bash
# All nodes
curl -k -X GET "https://localhost:55000/cluster/nodes?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

# Only worker nodes
curl -k -X GET "https://localhost:55000/cluster/nodes?type=worker&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Restart cluster

PUT /cluster/restart — Restart all cluster nodes.

bash
curl -k -X PUT "https://localhost:55000/cluster/restart?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Active Response

PUT /active-response — Execute an active response command on agents.

bash
curl -k -X PUT "https://localhost:55000/active-response?agents_list=001,002&pretty=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "!firewall-drop", "arguments": ["-srcip", "10.0.0.50"]}'

Security

List users

GET /security/users — List all security users with their roles.

bash
curl -k -X GET "https://localhost:55000/security/users?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Revoke tokens

PUT /security/user/revoke — Revoke all active JWT tokens.

bash
curl -k -X PUT "https://localhost:55000/security/user/revoke?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Syscheck & Rootcheck

PUT /syscheck — Run a syscheck (FIM) scan on agents.

bash
curl -k -X PUT "https://localhost:55000/syscheck?agents_list=001,002&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

PUT /rootcheck — Run a rootcheck scan on agents.

bash
curl -k -X PUT "https://localhost:55000/rootcheck?agents_list=001&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

MITRE ATT&CK

GET /mitre/techniques — Query MITRE techniques with full details (tactics, mitigations, software, groups, references).

bash
# Search for specific technique
curl -k -X GET "https://localhost:55000/mitre/techniques?search=phishing&limit=3&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

# Get by technique ID
curl -k -X GET "https://localhost:55000/mitre/techniques?technique_ids=T1566&pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Other MITRE endpoints: /mitre/tactics, /mitre/groups, /mitre/software, /mitre/mitigations, /mitre/references, /mitre/metadata.

Tasks

GET /tasks/status — Check the status of async tasks (upgrades, etc.).

bash
curl -k -X GET "https://localhost:55000/tasks/status?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Full Endpoint Index

<details> <summary>Click to expand all endpoints</summary>

API Info

MethodEndpointDescription
GET/API info

Agents

MethodEndpointDescription
GET/agentsList agents
POST/agentsCreate agent
DELETE/agentsDelete agents
POST/agents/insertInsert agent with key
POST/agents/insert/quickQuick insertion
PUT/agents/{agent_id}/restartRestart agent
GET/agents/{agent_id}/keyGet agent key
DELETE/agents/{agent_id}/groupRemove from all groups
PUT/agents/{agent_id}/group/{group_id}Assign to group
DELETE/agents/{agent_id}/group/{group_id}Remove from group
GET/agents/{agent_id}/group/is_syncSync status
GET/agents/{agent_id}/config/{component}/{configuration}Active config
GET/agents/{agent_id}/daemons/statsDaemon stats
GET/agents/{agent_id}/stats/{component}Component stats
PUT/agents/restartRestart all
PUT/agents/reconnectForce reconnect
PUT/agents/groupBulk assign to group
DELETE/agents/groupBulk remove from group
PUT/agents/group/{group_id}/restartRestart group
PUT/agents/node/{node_id}/restartRestart by node
GET/agents/no_groupWithout group
GET/agents/outdatedOutdated agents
PUT/agents/upgradeUpgrade agents
PUT/agents/upgrade_customCustom upgrade
GET/agents/upgrade_resultUpgrade result
GET/agents/uninstallUninstall agents
GET/agents/stats/distinctDistinct fields
GET/agents/summarySummary
GET/agents/summary/osOS summary
GET/agents/summary/statusStatus summary

Groups

MethodEndpointDescription
GET/groupsList groups
POST/groupsCreate group
DELETE/groupsDelete groups
GET/groups/{group_id}/agentsGroup agents
GET/groups/{group_id}/configurationGroup config
PUT/groups/{group_id}/configurationUpdate group config
GET/groups/{group_id}/filesGroup files
GET/groups/{group_id}/files/{file_name}File content

Cluster

MethodEndpointDescription
GET/cluster/statusCluster status
GET/cluster/nodesList nodes
GET/cluster/healthcheckHealthcheck
GET/cluster/local/infoLocal node info
GET/cluster/local/configLocal node config
GET/cluster/api/configAPI config
PUT/cluster/restartRestart cluster
GET/cluster/configuration/validationValidate config
GET/cluster/version/checkVersion check
GET/cluster/{node_id}/statusNode status
GET/cluster/{node_id}/infoNode info
GET/cluster/{node_id}/configurationNode config
PUT/cluster/{node_id}/configurationUpdate node config
GET/cluster/{node_id}/configuration/{component}/{configuration}Active config
GET/cluster/{node_id}/daemons/statsDaemon stats
GET/cluster/{node_id}/statsNode stats
GET/cluster/{node_id}/stats/hourlyHourly stats
GET/cluster/{node_id}/stats/weeklyWeekly stats
GET/cluster/{node_id}/stats/analysisdAnalysisd stats
GET/cluster/{node_id}/stats/remotedRemoted stats
GET/cluster/{node_id}/logsNode logs
GET/cluster/{node_id}/logs/summaryLog summary

Security

MethodEndpointDescription
POST/security/user/authenticateLogin (get JWT)
POST/security/user/authenticate/run_asLogin with auth context
PUT/security/user/revokeRevoke tokens
GET/security/usersList users
POST/security/usersCreate user
DELETE/security/usersDelete users
PUT/security/users/{user_id}Update user
PUT/security/users/{user_id}/run_asSet run_as
POST/security/users/{user_id}/rolesAssign roles
DELETE/security/users/{user_id}/rolesRemove roles
GET/security/users/meCurrent user
GET/security/users/me/policiesMy policies
GET/security/rolesList roles
POST/security/rolesCreate role
DELETE/security/rolesDelete roles
PUT/security/roles/{role_id}Update role
POST/security/roles/{role_id}/policiesAssign policies
DELETE/security/roles/{role_id}/policiesRemove policies
POST/security/roles/{role_id}/rulesAssign rules
DELETE/security/roles/{role_id}/rulesRemove rules
GET/security/policiesList policies
POST/security/policiesCreate policy
DELETE/security/policiesDelete policies
PUT/security/policies/{policy_id}Update policy
GET/security/rulesList rules
POST/security/rulesCreate rule
DELETE/security/rulesDelete rules
PUT/security/rules/{rule_id}Update rule
GET/security/actionsRBAC actions
GET/security/resourcesRBAC resources
GET/security/configSecurity config
PUT/security/configUpdate config
DELETE/security/configReset config

Syscheck, Rootcheck & Active Response

MethodEndpointDescription
PUT/syscheckRun syscheck scan
PUT/rootcheckRun rootcheck scan
PUT/active-responseRun AR command

MITRE

MethodEndpointDescription
GET/mitre/techniquesTechniques
GET/mitre/tacticsTactics
GET/mitre/groupsGroups
GET/mitre/softwareSoftware
GET/mitre/mitigationsMitigations
GET/mitre/referencesReferences
GET/mitre/metadataMetadata

Events, Overview & Tasks

MethodEndpointDescription
GET/overview/agentsAgent overview
GET/tasks/statusTask status
</details>

Wazuh Query Language (WQL)

WQL allows server-side filtering of large datasets, reducing payload size and avoiding client-side filtering.

Syntax

field operator value[;connector field operator value]

Operators

OperatorMeaning
=Equals
!=Not equals
>Greater than
<Less than
>=Greater than or equal
<=Less than or equal
~=Contains (like)

Connectors

ConnectorMeaning
;AND
,OR

Examples

bash
# Active agents
curl -k -X GET "https://localhost:55000/agents?q=status%3Dactive" \
  -H "Authorization: Bearer $TOKEN"

# Active agents on Ubuntu
curl -k -X GET "https://localhost:55000/agents?q=status%3Dactive%3Bos.name~%3Dubuntu" \
  -H "Authorization: Bearer $TOKEN"

# Agents with version not equal to 5.0.0
curl -k -X GET "https://localhost:55000/agents?q=version!%3Dwazuh%205.0.0" \
  -H "Authorization: Bearer $TOKEN"

Error Handling

Errors follow a structured JSON response format.

HTTP Status Codes

HTTP CodeMeaningNotes
400Bad RequestInvalid parameters
401UnauthorizedInvalid or expired token
403ForbiddenRBAC denied
404Not FoundInvalid endpoint
405Method Not AllowedInvalid HTTP method
413Payload Too LargeRequest body too large
429Too Many RequestsRate limit exceeded
500Internal ErrorCheck manager logs

Exception Hierarchy

All exceptions inherit from WazuhException (defined in core/exception.py), with a numeric error code catalog:

RangeCategoryExamples
900–999API-level errorsChild process terminated, executor failure, endpoint restricted to master
999–1099Core Wazuh errorsIncompatible Python, internal error, command errors, socket issues
1100–1199Configuration errorsInvalid section/field/type, XML syntax, missing config
1200–1299Agent errorsAgent not found, duplicate, version mismatch
1700–1799RBAC errorsPermission denied, invalid role/policy
2000+Module-specific errorsSyscheck, rootcheck, active response, cluster

Error responses include a dapi_errors field in cluster deployments.

Input Validation

The API layer (api/validator.py) validates all inputs with pre-compiled regex patterns before they reach the framework:

PatternDescription
HashesMD5 (32), SHA1 (40), SHA224 (56), SHA256 (64), SHA384 (96), SHA512 (128)
GroupsGroup name validation (excludes ., .., all)
Base64Standard base64 encoded strings
DatesDate and datetime format validation
WQLQuery syntax (field operator value;connector)
XMLValidated via lxml and defusedxml
Special charsSeparate patterns for names vs. paths