API Reference

The SmoothDeploy API lets you trigger test runs, read results, and work with email inboxes from any HTTP client. Every request is authenticated with an API key you create in the console.

Base URL

https://api.smoothdeploy.com

All paths start with /v1/.

Authentication

Send your API key in the x-api-key header on every request. Most routes also require x-project-id when the operation is project-scoped. See Authentication for the full header reference.

Request and response format

All request bodies are JSON. Set Content-Type: application/json.

Most endpoints wrap their payload in a data field:

{ "data": { ... } }

List endpoints that do not paginate return an array under data:

{ "data": [ ... ] }

Operations that produce no payload (e.g. delete) return:

{ "data": null }

GET /v1/tests is an exception — it returns { children, pagination } rather than { data }. See Tests for the exact shape.

Pagination

GET /v1/tests and GET /v1/test-runs paginate. Both support these query parameters:

Parameter	Type	Default	Notes
`page`	integer	`0`	Zero-based page index
`limit`	integer	`50` (`GET /v1/tests`), `20` (`GET /v1/test-runs`)	Items per page. `GET /v1/test-runs` accepts a maximum of `500`

Both return a pagination object alongside the result set:

{
  "pagination": {
    "page": 0,
    "limit": 20,
    "total": 143,
    "totalPages": 8,
    "hasMore": true
  }
}

All other list endpoints return the full result set with no pagination.

Error responses

All errors follow the same shape:

{ "message": "Human-readable description of the error" }

Status	Meaning
`400`	Invalid request — missing field, failed validation, or a business rule violation (e.g. inbox limit reached)
`401`	Missing or invalid API key
`403`	Valid key but insufficient scope for this operation
`404`	Resource not found in your organization
`409`	Conflict — a run for this test is already active
`500`	Unexpected server error

Scopes

Each API key carries a set of scopes that control which endpoints it can reach. See Scopes for the full reference.

API reference pages

Authentication — headers, key format, security guidance
Scopes — every scope and the endpoints each unlocks
Tests — create, read, update, run, and export tests
Steps — read and update test steps and shared steps
Test Runs — list runs, read results, cancel
Email Inboxes — list inboxes and read messages