API Reference

The TMS API gives you full programmatic access to everything in the platform: projects, test cases, test runs, results, AI features, integrations, and more. Use it to build custom integrations, automate your CI/CD pipeline, or connect TMS to your internal tools.

---

Base URL

On ProvaLab cloud, all API requests go through:

https://tms.provalab.io/api/v1

The examples in this reference use that URL. If you run a self-hosted TMS, replace the host with your own (https://<your-tms-host>/api/v1); a local development server is http://localhost:8000/api/v1.

Interactive API docs and OpenAPI spec

The live API documentation is generated from the running backend:

• Swagger UI: https://tms.provalab.io/api/docs
• ReDoc: https://tms.provalab.io/api/redoc
• OpenAPI JSON: https://tms.provalab.io/api/v1/openapi.json

Self-hosted instances serve the same paths under their own host.

---

Authentication

Every API request must be authenticated using one of these methods:

Bearer token (JWT)

Obtain a token by calling the login endpoint and include it in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

• Access token lifetime: 30 minutes
• Refresh token lifetime: 7 days

When the access token expires, use the refresh endpoint to get a new one.

API key

For long-lived programmatic access (CI/CD, scripts, integrations), use an API key in the X-API-Key header:

X-API-Key: tms_...

ProvaLab API keys always start with tms_.

To create an API key:

1. Open the ProvaLab account portal at auth.provalab.io (also reachable from the app switcher in the TMS top bar under Account & Auth)
2. Click API Keys in the left sidebar, or go directly to auth.provalab.io/api-keys
3. Click Create API Key, give it a name and select the scopes you need
4. Copy the key -- it is only shown once

info

Keys are managed (rotated, expired or revoked) from the same API Keys page in the account portal.

OAuth 2.0

TMS also supports OAuth authentication through Google and GitHub. See the Authentication API page for details.

---

Rate limits

API requests are rate-limited based on your subscription plan:

Plan	Requests per minute
Free	100
Pro	1,000
Enterprise	5,000

Every response includes rate limit headers so you can monitor your usage:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 947
X-RateLimit-Reset: 1700053200

When you exceed the limit, the API returns a 429 Too Many Requests response:

{
  "detail": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}

---

Request format

Send request bodies as JSON with the Content-Type: application/json header:

curl -X POST https://tms.provalab.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "yourpass"}'

---

Response format

All responses are returned as JSON. Successful responses include the resource data directly:

{
  "id": 1,
  "name": "My Project",
  "status": "active",
  "created_at": "2025-11-15T10:00:00Z"
}

---

Pagination

List endpoints return paginated results. Use page and page_size query parameters to navigate:

GET /api/v1/organizations/1/projects?page=2&page_size=20

Paginated responses include metadata:

{
  "items": [
    { "id": 1, "name": "Project A" },
    { "id": 2, "name": "Project B" }
  ],
  "total": 47,
  "page": 2,
  "page_size": 20,
  "total_pages": 3
}

Parameter	Type	Default	Max	Description
page	integer	1	--	Page number (starts at 1)
page_size	integer	20	100	Items per page

---

Error format

Errors follow a consistent structure:

{
  "detail": "Project not found",
  "error_code": "NOT_FOUND",
  "timestamp": "2025-11-15T10:00:00Z"
}

Validation errors include field-level details:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "Invalid email format",
      "type": "value_error.email"
    },
    {
      "loc": ["body", "password"],
      "msg": "Password must be at least 8 characters",
      "type": "value_error.str.min_length"
    }
  ]
}

Common HTTP status codes

Code	Meaning
200	Success
201	Resource created
204	Success, no content returned
400	Bad request (invalid input)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Resource not found
409	Conflict (e.g., duplicate resource)
422	Validation error
429	Rate limit exceeded
500	Internal server error

---

API sections

Section	Description
Authentication API	Login, register, token refresh, API keys
Test Management API	Projects, test cases, suites, plans, runs, and results
Integrations API	Webhooks, Jira, Slack, and GitHub configuration
AI API	Test generation, failure analysis, chat, and flaky test detection