Accessing the API

Learn how to authenticate and make requests to the Preads API.

Base URL

All API requests should be made to:

https://preads.hansaldev.com/api/v1/offers

Authentication

The Preads API uses API keys for authentication. You can find your API keys in your app's integration page in the publisher dashboard.

API Key Types

Key Type	Purpose	Visibility
API Key	Used for client-side integrations (iframe, JavaScript)	Public - can be exposed in frontend code
API Secret	Used for server-side API requests	Private - must be kept secure on your server

Making Requests

Include your API credentials in the request headers or query parameters:

Using Query Parameters (Recommended for GET requests)

        GET https://preads.hansaldev.com/api/v1/offers?apiKey=YOUR_API_KEY&apiSecret=YOUR_API_SECRET
    

Using Headers (Recommended for POST requests)

        curl -X POST https://preads.hansaldev.com/v1/conversions \
            -H "X-API-Key: YOUR_API_KEY" \
            -H "X-API-Secret: YOUR_API_SECRET" \
            -H "Content-Type: application/json" \
            -d '{"userId": "USER123", "offerId": 12345}'

Rate Limiting

API requests are limited to 100 requests per minute per API key.

Rate limit information is included in response headers:

        X-RateLimit-Limit: 100
            X-RateLimit-Remaining: 95
            X-RateLimit-Reset: 1705789234

Response Format

All API responses are in JSON format with the following structure:

        
{
    "success": true,
    "data": { ... },
    "message": "Request successful",
    "meta": {
    "timestamp": 1705789234,
    "request_id": "req_abc123"
    }
}

Error Handling

Errors follow a consistent format:

        
{
    "success": false,
    "error": {
        "code": "INVALID_API_KEY",
        "message": "The provided API key is invalid or expired",
        "details": null
    },
    "meta": {
        "timestamp": 1705789234,
        "request_id": "req_abc123"
    }
}

Common Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is missing or invalid
`INVALID_API_SECRET`	401	API secret is missing or invalid
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INVALID_REQUEST`	400	Request is malformed or missing required parameters
`RESOURCE_NOT_FOUND`	404	Requested resource doesn't exist
`SERVER_ERROR`	500	Internal server error

Best Practices

Never expose your API Secret in client-side code
Implement exponential backoff for rate limit errors
Cache API responses when appropriate to reduce API calls
Use HTTPS for all API requests
Store API credentials securely (environment variables, secrets manager)
Monitor your API usage via the publisher dashboard