danger

This API is currently not available for public use. If you got here by mistake, please go back to the current Web API.

Version: 1.0.0

WhatPulse Public API

Welcome to the WhatPulse Public API! This RESTful API provides programmatic access to WhatPulse user data, statistics, and insights. Whether you're building a personal dashboard, creating integrations, or developing third-party applications, our API gives you the tools to work with WhatPulse data in your own projects.

Getting Started

Authentication

All API requests require authentication using Bearer tokens. You can create your personal API key on the API settings page in your WhatPulse account.

Include your API key in the Authorization header of every request:

Authorization: Bearer your-api-key-here

Base URL

All API endpoints are accessible via: https://whatpulse.org/api/v1/

Data Access & Privacy

The API respects WhatPulse's privacy model:

• Your own data: Full access to all your personal statistics and private information
• Public data: Access to publicly available user profiles and statistics
• Private data: Restricted based on user privacy settings and permissions

Users control what data is publicly accessible through their privacy settings, and the API enforces these permissions automatically.

Response Format

All API responses follow a consistent JSON structure:

Successful Responses

{
  "data": {
    // Your requested data here
  },
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 100,
    "last_page": 2
  },
  "links": {
    "first": "https://whatpulse.org/api/v1/endpoint?page=1",
    "last": "https://whatpulse.org/api/v1/endpoint?page=2",
    "prev": null,
    "next": "https://whatpulse.org/api/v1/endpoint?page=2"
  },
  "filters": {
    "applied_filter": "value"
  }
}

Error Responses

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "field_name": ["Specific error message"]
    }
  }
}

Rate Limiting

To ensure fair usage and maintain service quality, the API implements rate limiting:

• Authenticated requests: 1000 requests per hour per API key
• Rate limit headers are included in every response:
  • X-RateLimit-Limit: Maximum requests allowed per hour
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Caching

The API implements intelligent caching to improve performance:

• Cache duration: 1 hour for most endpoints
• Cache headers: Every response includes an X-Cache-Status header:
  • HIT: Response served from cache
  • MISS: Fresh response generated
• Cache keys: Based on endpoint, parameters, and authenticated user
• Automatic invalidation: Caches are cleared when relevant data changes
• Cached responses are user-specific, ensuring you never see another user's private data.

Error Handling

The API uses standard HTTP status codes and provides detailed error information:

Common Status Codes

• 200 OK: Request successful
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Access denied (privacy restrictions)
• 404 Not Found: Resource doesn't exist
• 422 Unprocessable Entity: Validation failed
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Validation Errors

When validation fails, you'll receive detailed information about what went wrong:

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "search": ["The search field must be at least 3 characters."],
      "per_page": ["The per page field must be between 1 and 100."]
    }
  }
}

Best Practices

1. Store your API key securely - Never expose it in client-side code
2. Handle rate limits gracefully - Check rate limit headers and implement backoff strategies
3. Cache responses when appropriate - Respect the API's caching headers
4. Use pagination - Don't try to fetch all data at once
5. Handle errors properly - Always check status codes and parse error messages
6. Respect privacy - Understand that some data may not be accessible based on user settings

Support

Need help? Check out our support documentation or reach out to our community on Discord.

Happy coding, and welcome to the WhatPulse API!