API Reference

The ProvaLab.io 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 ProvaLab.io to your internal tools.

---

Base URL

All API requests go through:

https://your-tms-instance.com/api/v1

Replace your-tms-instance.com with your actual ProvaLab.io domain. If you are running locally, the default is http://localhost:8000/api/v1.

Interactive API docs

Your ProvaLab.io instance includes built-in API documentation:

• Swagger UI: https://your-tms-instance.com/docs
• ReDoc: https://your-tms-instance.com/redoc
• OpenAPI JSON: https://your-tms-instance.com/openapi.json

---

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: sk_live_abc123...

To create an API key:

1. Log in to ProvaLab.io
2. Go to Settings > Security > API Keys
3. Click Create New Key
4. Give it a name and select the permissions you need
5. Copy the key -- it is only shown once

info

API keys do not expire automatically, but you can revoke them at any time from the Settings page.

OAuth 2.0

ProvaLab.io 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://your-tms-instance.com/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