Test Access API
The Test Access API allows you to verify that DeployHQ can connect to your repository and servers. Tests run asynchronously on deployment workers (the same servers that perform your actual deployments), so results accurately reflect real deployment connectivity.
Tip: You can explore and test these endpoints interactively using our OpenAPI documentation.
Run Test Access (Full Project)
Queues an asynchronous test of repository connectivity and all server connections for a project. The response contains an identifier that you use with the Get Test Access Results endpoint below to poll for results.
URL
/projects/:project_id/test_access
HTTP Method
POST
Example cURL request
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user adamatechmedia.com:my-api-key \
https://test.deployhq.com/projects/my-project/test_access
Example Response
{
"identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "running",
"created_at": "2026-04-02T12:00:00Z",
"completed_at": null
}
Run Test Access (Single Server)
Queues an asynchronous connectivity test for a single server within a project. As with the full project test, use the returned identifier to poll for results.
URL
/projects/:project_id/servers/:server_id/test_access
HTTP Method
POST
Example cURL request
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user adamatechmedia.com:my-api-key \
https://test.deployhq.com/projects/my-project/servers/5a951ebb-1234-5678-abcd-ef1234567890/test_access
Example Response
{
"identifier": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "running",
"created_at": "2026-04-02T12:00:05Z",
"completed_at": null
}
Get Test Access Results
Retrieves the status and results of a test access run. Poll this endpoint until the status changes from running to completed or failed.
URL
/projects/:project_id/test_access/:identifier
HTTP Method
GET
Example cURL request
curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adamatechmedia.com:my-api-key \
https://test.deployhq.com/projects/my-project/test_access/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Example Response (completed, full project)
{
"identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"created_at": "2026-04-02T12:00:00Z",
"completed_at": "2026-04-02T12:00:15Z",
"results": {
"repository": {
"status": "ok",
"message": null
},
"servers": [
{
"name": "production",
"identifier": "5a951ebb-1234-5678-abcd-ef1234567890",
"status": "ok",
"message": null
},
{
"name": "staging-ftp",
"identifier": "a4eec86c-1234-5678-abcd-ef1234567890",
"status": "error",
"message": "Connection refused"
}
]
}
}
Example Response (completed, single server)
{
"identifier": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "completed",
"created_at": "2026-04-02T12:00:05Z",
"completed_at": "2026-04-02T12:00:10Z",
"results": {
"servers": [
{
"name": "production",
"identifier": "5a951ebb-1234-5678-abcd-ef1234567890",
"status": "ok",
"message": null
}
]
}
}
Example Response (still running)
{
"identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "running",
"created_at": "2026-04-02T12:00:00Z",
"completed_at": null
}
Polling
Tests run asynchronously. After triggering a test, poll the results endpoint every 2-3 seconds until the status is completed or failed. Results are not returned while the status is running.
Fields
Test Run
| Field | Description |
|---|---|
identifier |
Unique identifier for the test run |
status |
Current status: running, completed, or failed |
created_at |
When the test was triggered (ISO 8601) |
completed_at |
When the test finished (ISO 8601), null while running |
results |
Test results object, present only when completed |
Results
| Field | Description |
|---|---|
results.repository |
Repository connectivity result (omitted for single-server tests) |
results.repository.status |
ok or error |
results.repository.message |
Error message if status is error, null otherwise |
results.servers |
Array of server connectivity results |
results.servers[].name |
Server name |
results.servers[].identifier |
Server identifier |
results.servers[].status |
ok or error |
results.servers[].message |
Error message if status is error, null otherwise |