Welcome to the Hawzu API documentation. Hawzu’s REST API allows you to programmatically manage test cases, executions, releases, defects, and analytics while preserving execution integrity and audit history.
/api/v1 are versioned and backward compatible.All API requests should be made to:
https://api.hawzu.com
The Hawzu API is versioned via the URL path (e.g., /api/v1).
We maintain backward compatibility within a version.
Breaking changes will only be introduced in a new version.
All API requests require authentication using a Bearer token in the Authorization header.
API tokens are independent security principals with explicitly assigned permissions. Permissions can be scoped at either the workspace level or the project level. All API requests are authorized strictly according to the token’s assigned role and scope.
Visit Create Access Token to create your API token. Copy the token immediately as it won't be shown again.
API tokens must be created and managed via the Hawzu web interface. Token creation and revocation are not available through the API.
Include your API token in the Authorization header of every request
Authorization: Bearer YOUR_API_TOKENThe Hawzu API uses standard HTTP methods to indicate the action being performed:
| Method | Description | Example |
|---|---|---|
GET | Retrieve a resource or list of resources | /api/v1/me |
POST | Create a new resource | /api/v1/executions |
PUT | Update an existing resource (full replacement) | /api/v1/testcases/{id} |
PATCH | Partially update a resource | /api/v1/testcases/{id} |
DELETE | Delete a resource | /api/v1/testcases/{id} |
The API uses standard HTTP status codes to indicate the result of a request:
| Code | Description |
|---|---|
200 OK | Request succeeded. Response body contains the requested data. |
201 Created | Resource created successfully. Response body contains the created resource. |
204 No Content | Request succeeded but no content is returned (common for DELETE operations). |
| Code | Description |
|---|---|
400 Bad Request | Invalid request syntax or parameters. Check the request body and parameters. |
401 Unauthorized | Authentication required or invalid token. Check your Authorization header. |
403 Forbidden | Valid authentication but insufficient permissions for this resource. |
404 Not Found | The requested resource does not exist. |
409 Conflict | Request conflicts with current state (e.g., duplicate resource). |
422 Unprocessable Entity | Request is well-formed but contains semantic errors (validation failures). |
429 Too Many Requests | Rate limit exceeded. Wait before retrying. |
API requests are rate limited to ensure service stability.
If you exceed the limit, you will receive a 429 Too Many Requests response.
| Code | Description |
|---|---|
500 Internal Server Error | An unexpected error occurred on the server. Please try again later. |
503 Service Unavailable | Service temporarily unavailable (maintenance or overload). |
All requests should include:
Authorization: Bearer YOUR_API_TOKEN - Required for authenticationContent-Type: application/json - Required for POST, PUT, and PATCH requests with a bodyFor POST, PUT, and PATCH requests, send data as JSON in the request body:
{
"field1": "value1",
"field2": "value2"
}All successful responses return JSON data:
{
"id": "resource_id",
"name": "Resource Name",
"created_at": "2025-01-01T00:00:00Z"
}Error responses follow a consistent format:
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
"field": "Additional error details"
}
}
}