API Documentation
Learn how to use the Auto Rosters API to integrate with your applications.
Introduction
The Auto Rosters API allows you to programmatically access your roster data. This API is available exclusively to premium users.
To use the API, you need to include your API key in the X-API-Key header with each request.
All API requests should be made to https://autorosters.com/api.
Important: For security reasons, your API key can only access roster pages that you own. Attempting to access rosters owned by other users will result in a 403 Forbidden error.
If you don't have an API key yet, you can generate one here.
Authentication
All API requests require authentication using an API key. You can create and manage your API keys in the API Keys section.
API Key Authentication
To authenticate your requests, include your API key in the X-API-Key header:
X-API-Key: your-api-key-here
Authentication Errors
If you don't include an API key or if the API key is invalid, you'll receive a 401 Unauthorized response:
{
"error": "Invalid or missing API key"
}
Premium Requirement
API access is only available to premium users. If your account doesn't have a premium subscription, you'll receive a 403 Forbidden response:
{
"error": "API access requires premium subscription"
}
Ownership Restriction
For security reasons, your API key can only access roster pages that you own. If you try to access a roster owned by another user, you'll receive a 403 Forbidden response:
{
"error": "You do not have permission to access this roster"
}
Error Handling
The API uses standard HTTP status codes to indicate the success or failure of requests. In case of an error, the response body will contain a JSON object with an error field that provides more information about what went wrong.
Common Error Codes
| Status Code | Description | Example |
|---|---|---|
| 400 Bad Request | The request was malformed or missing required parameters | {"error": "Missing required parameter"} |
| 401 Unauthorized | Authentication failed (missing or invalid API key) | {"error": "Invalid or missing API key"} |
| 403 Forbidden | The authenticated user doesn't have permission to access the requested resource | {"error": "API access requires premium subscription"} |
| 404 Not Found | The requested resource doesn't exist | {"error": "Roster page not found"} |
| 429 Too Many Requests | Rate limit exceeded | {"error": "Rate limit exceeded"} |
| 500 Internal Server Error | An unexpected error occurred on the server | {"error": "Internal server error"} |
Error Response Format
All error responses follow the same format:
{
"error": "Error message describing what went wrong"
}
Handling Errors
When implementing your API client, make sure to check the HTTP status code of each response and handle errors appropriately. For 429 Too Many Requests errors, you should implement exponential backoff to retry the request after the specified delay.
Rate Limiting
To ensure fair usage and system stability, the API implements rate limiting. Each API key is limited to a certain number of requests per 5 minutes.
Rate Limit Headers
The API includes rate limit information in the response headers:
| Header | Description |
|---|---|
| X-RateLimit-Limit | The maximum number of requests allowed per 5 minutes |
| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window |
| X-RateLimit-Reset | The time at which the current rate limit window resets, in Unix epoch seconds |
Rate Limit Exceeded
If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{
"error": "Rate limit exceeded"
}
Best Practices
To avoid hitting rate limits, follow these best practices:
- Cache responses when appropriate to reduce the number of API calls
- Implement exponential backoff when retrying rate-limited requests
- Monitor the rate limit headers and adjust your request rate accordingly
- Spread out requests over time instead of making them all at once
API Endpoints
Here's a quick overview of the available endpoints: