Overview

Welcome to the QA Sphere API documentation. Our API allows you to programmatically manage test cases, runs, and results in your QA Sphere projects.

Authentication

All API requests require authentication using an API key. See the Authentication guide to get started.

Base URL

https://{your-company}.{your-region-code}.qasphere.com/api/public/v0

Response Format

All responses are returned in JSON format. Successful responses typically include:

• Status codes in the 2XX range
• Data specific to the endpoint
• Pagination information where applicable

Error responses include:

• Status codes in the 4XX or 5XX range
• Error message explaining the issue
• Additional context where available

Rate Limiting

API requests are rate limited to protect the service and ensure fair usage.

• 20 requests per second, per user

The limit is applied per user, not per API key. Every API key you create belongs to the user who created it, and all of that user's API keys and OAuth authorizations draw from the same 20 requests per second. Creating additional API keys under the same account will not raise your throughput — if you need more, distribute the work across separate user accounts.

The limit uses a token bucket with a capacity of 20, so a client that has been idle can issue up to 20 requests at once. Capacity equals one second of refill, so there is no allowance above 20 to save up — sustained traffic and bursts are both capped at 20 requests per second.

Handling a 429

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

{
  "message": "Too many requests, please try again later."
}

The response includes a Retry-After header giving the number of seconds to wait before the next request will be accepted:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Scope: public_api

Wait at least that long before retrying. If the header is missing, fall back to exponential backoff.

X-RateLimit-Scope: public_api marks a 429 that came from the per-user throughput limit — your credentials were accepted and only your request rate was too high, so retrying after Retry-After will succeed.

Repeated authentication failures

A 429 without the X-RateLimit-Scope header means the requests reaching us are being rejected before they are authenticated. Sending invalid credentials repeatedly gets your IP rate limited even though no single request succeeds, so make sure retry logic stops on 401 instead of retrying it — waiting out a single Retry-After will not clear this one while the failures continue.

OAuth device flow limits

The device flow is limited separately and does not use 429. Both endpoints reject with 400 and an RFC 8628 slow_down error, and neither sends a Retry-After header:

{
  "error": "slow_down",
  "error_description": "polling too frequently"
}

Token polling is normally performed by the OAuth client or tool, not by the person authorizing it. The client must start with the interval returned by the device authorization endpoint. If the token endpoint returns slow_down, it must increase that interval by 5 seconds before continuing to poll, as RFC 8628 §3.5 describes. The QA Sphere CLI handles this automatically.

Requesting a new device code starts a new authorization attempt and is under the user's control. If that endpoint returns slow_down, wait before starting another attempt instead of repeatedly requesting new codes.

Staying under the limit

• Retry on 429 with exponential backoff, honoring Retry-After
• For ordinary public API requests, do not retry 4xx responses other than 429. OAuth device flow clients must continue on authorization_pending and retry more slowly on slow_down
• Use batch endpoints instead of many individual requests where one exists
• Cache responses that change infrequently, such as project and folder listings
• Keep client-side concurrency modest; parallel workers share the same per-user budget

If you use the QA Sphere CLI, all of this is handled for you, from v0.8.0 onward. Earlier versions do not recognize 429 and will fail against these limits, so upgrade if you are on v0.7.0 or older.