The Foreman API allows you to programmatically interact with your Foreman account — automating tasks, retrieving miner data, managing clients, and integrating Foreman into your own tools and workflows. Whether you're building a custom dashboard, scripting bulk operations, or connecting Foreman to third-party systems, the API gives you direct access to the platform's core functionality.

API Documentation: https://app.swaggerhub.com/apis/foremanmining/foreman-api/2.0.0#/

How to Use the API

The API documentation is hosted on SwaggerHub, which provides an interactive interface for exploring and testing every available endpoint. From the documentation page, you can:

• Browse all available endpoints organized by resource type.
• View required and optional parameters for each request.
• See example request and response payloads.
• Send test requests directly from the browser using the Try it out feature.

To get started, familiarize yourself with the authentication method for your account (typically an API key), then explore the endpoints relevant to your use case.

Rate Limits

The API enforces a limit of 1 call per second, per endpoint, per client. This means:

• You can call different endpoints simultaneously without conflict.
• You can call the same endpoint for different clients simultaneously without conflict.
• If you need to make repeated calls to the same endpoint for the same client, wait at least 1 second between each request.

Staying within these limits ensures reliable performance and prevents your requests from being throttled.

Testing Without a Sandbox

Foreman does not currently offer a dedicated sandbox or staging environment. For testing, you have two practical options:

1. Create a test client — Set up an additional client in your Foreman account and move a small number of miners to it. This gives you a safe, isolated environment to test API calls without affecting your production data.
2. Use SwaggerHub — The interactive docs let you fire off real API requests directly from the browser, which is useful for validating endpoint behavior before writing any code.

Staying Up to Date

The API is actively maintained and updated. All changes are documented in the Foreman Release Notes. To find API-specific updates, search for API within the Release Notes — this will surface all recent additions, changes, and deprecations.

Checking the Release Notes regularly is the best way to catch new endpoints, parameter changes, or anything that might affect existing integrations.

Tips for Getting the Most Out of the API

• Start with SwaggerHub. Before writing any code, use the interactive docs to understand exactly what each endpoint returns. It saves time and reduces trial-and-error.
• Build retry logic with backoff. Even with careful rate limiting, network issues happen. A simple retry with a 1–2 second delay handles most transient failures gracefully.
• Use a dedicated test client. Keeping a small test environment separate from production makes it safe to experiment with write operations, such as configuration changes or miner management.
• Watch the Release Notes. Set a reminder to check for API updates periodically, especially before deploying new integrations, to avoid surprises from changed behavior.
• Scope your API calls. Only request the data you need. Targeted, specific calls are faster, easier to debug, and less likely to run into rate limits than broad queries.