API Documentation

Welcome to Planner API documentation. Choose a link from the navigation menu on the left to view the documentation. Alternatively, view our Endpoint Explorer to get a list of endpoints, check example requests and view model properties. If you need any further help or support, click on the support link below.

This documentation provides a comprehensive outline to the Planner API, a RESTful API for retrieving events from Forward Planner.

API Overview

The Forward Planner API is a RESTful web service that provides access to Forward Planner events, including support for querying and filtering results.

Base URL

API Version

Current version: v2

Data Format

All data is returned in JSON format with UTF-8 encoding.

Audience

Intended for developers integrating with the Planner system.

Terms of Service

Available at Planner Terms

Authentication

The Forward Planner API uses authentication header for secure access to data.

Access Token

Include your access token in the request header:

• Authorization: Bearer your_access_token_here

Getting your API Key

1. Log into your Forward Planner account
2. Navigate to API Settings in your account profile
3. Generate or copy your existing API key
4. If you do not see the API Settings section, please contact us and we will enable it for your account

Authenticate

Endpoint: POST `/api/v2/auth`

• Authenticate with username and API key.
• Returns an access token and refresh token. Use the access token for subsequent requests.
• Example request using curl:

  curl -X POST /api/v2/auth \
      -H "Content-Type: application/json" \
      -d '{
      "username": "your_username",
      "password": "your_api_key"
  }'

• Example Response (200 OK):

  {
      "userId": your_userId,
      "productId": your_productId,
      "email": "your_email",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refreshToken": "dGhpcy1pcy1hLXNhbXBsZS1yZWZyZXNoLXRva2Vu..."
  }

• If the request fails (e.g., invalid credentials), you will receive a `401 Unauthorised` error.

Renew Token

Endpoint: POST `/api/v2/auth/renew`

• Renew access token using refresh token.
• Provides a new access token without re-entering credentials.
• Example Request:

  curl -X POST /api/v2/auth/renew \ 
      -H "Content-Type: application/json" \ 
      -d '{   
      "refreshToken": "dGhpcy1pcy1hLXNhbXBsZS1yZWZyZXNoLXRva2Vu..." 
  }'

• Access tokens expire after 15 minutes.
• Refresh tokens expire after 30 days.

Best Practice

• Store refresh tokens securely (e.g., in encrypted storage).
• Implement token expiration handling in your client code.
• Refresh proactively (e.g., 1 minute before expiry).

FAQ

Error Handling

All errors return a JSON payload with error and message fields.

Common status codes

Best Practice

• Always check the status code and parse the error message for debugging.
• Log errors and implement retry logic for transient issues (e.g., 5xx server errors, though rare).

FAQ

Rate Limiting

To ensure fair usage and system stability, API requests are rate-limited.

Limits

• 500 requests per minute, 3,000 requests per hour and 10,000 day (per account).
• Some public endpoints have a lower threshold.
• Exceeding limits returns a 429 Too Many Requests response with headers like Retry-After (seconds until retry).

Best Practice

• Implement exponential backoff in your client (e.g., retry after 1s, then 2s, etc.).
• Monitor usage via response headers (e.g., X-Rate-Limit-Remaining).
• For high-volume needs, contact support to discuss increased limits.

Example 429 Response

{   
  "error": "Throttle Limit Reached",   
  "message": "You have exceeded the rate limit. Retry after 60 seconds." 
}

FAQ and Best Practices

Some common questions and best practices for using the API.

Troubleshooting

Some common troubleshooting steps for API issues.