Nimbly API Documentation (1.0.0)

To access our Nimbly API, you need to authenticate using a secret token as an API key. API keys are a simple and secure way to identify your application when making requests to our API.

To obtain API keys for authentication, please reach out to our team. Once your request for API keys has been approved, we will securely send them to you via email, ensuring that you have the necessary credentials to access our API.

Your API keys are sensitive credentials. Avoid sharing them publicly to maintain the confidentiality of your data and the security of your API resources.

For authenticating your API requests, include your API key in the request headers as shown below:

GET /reports
x-api-key: YOUR_API_KEY			

Replace YOUR_API_KEY with the actual API key you received from our team.

This x-api-key header is used to allow the server to identify and authorize your organization account. Please note that any API call made without including the 'x-api-key' header will result in a failed request.

The API base URL is now:

https://api.hellonimbly.com/v1.0/public

If your integration still uses the previous cloudfunctions.net base URL, please migrate: only the base URL changes, while every path, parameter, response and your API key stay exactly the same. The old base URL is deprecated - it keeps working during the deprecation window, but new capabilities (such as the MCP server below) are only available on the new base URL.

Our Nimbly API use rate limiter to ensure equitable access to our API resources while maintaining system stability. This document outlines our rate limiting policies, how to handle rate limit errors, and tips for optimizing your API usage within these limits.

Our rate limiter enforces the following rate limiting policy:

• Rate Limit: You can make up to 3 requests per second (RPS) to our API per API key.

When you exceed the rate limit, our API will respond with a 429 Too Many Requests status code. This indicates that you have reached the maximum allowed request rate. The response will include additional information in the headers for your reference:

• X-RateLimit-Limit: The total number of requests allowed per second.
• X-RateLimit-Remaining: The number of requests remaining in the current rate-limiting window.

Here's an example of a rate-limited response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 0

{
  "message": "Limit Exceeded"
}

To ensure smooth API interactions and avoid rate-limiting errors:

• Implement Backoff: If you receive a 429 error, implement a backoff mechanism in your code to retry the request after a delay.
• Monitor Headers: Pay attention to the X-RateLimit-Limit and X-RateLimit-Remaining headers in the response to track your rate limit usage.
• Cache Data: Consider caching data locally to reduce the number of API requests when possible.
• Contact Support: If you consistently encounter rate-limiting issues, please contact our support team for assistance or to discuss rate limit adjustments.

By following these guidelines, you can work effectively within our rate limits and ensure a smooth experience while using the Nimbly API.

The same data this API exposes is also available to AI assistants through a Model Context Protocol server, so tools like Claude, Claude Code and Cursor can answer questions about your sites, audits and issues directly.

The MCP server is served over Streamable HTTP at:

POST https://api.hellonimbly.com/v1.0/public/mcp

Authenticate with the same API key you use for the REST endpoints, either as an x-api-key header or as Authorization: Bearer YOUR_API_KEY for clients that only offer a bearer-token field. The endpoint holds no session state and accepts POST only; GET and DELETE return 405.

The server implements MCP revision 2026-07-28, where each request is self-contained and no initialize handshake is needed. Clients built against earlier revisions are served too and need no special configuration, so any current MCP client works as-is.

Every tool is read-only and scoped to the organization that owns the API key.

• list_sites, get_site: locations, their departments, city and timezone.
• list_reports, get_report: submitted audit reports, including per-question answers and scores.
• list_issues, get_issue, get_issue_status_history: findings and corrective actions, with their full status trail.
• list_users, get_user: active users, their roles and coverage.
• list_questionnaires: audit checklists and their question counts.
• list_schedules: planned audits in a date range with completion percentages.
• list_departments: departments defined in your organization.

For Claude Code, add the server from your terminal:

claude mcp add --transport http nimbly https://api.hellonimbly.com/v1.0/public/mcp --header "x-api-key: YOUR_API_KEY"

For Claude Desktop, Cursor and other clients that read a JSON config file, add:

{
  "mcpServers": {
    "nimbly": {
      "type": "http",
      "url": "https://api.hellonimbly.com/v1.0/public/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Tool calls draw on the same per-organization rate limit as the REST endpoints, so one tool call costs the same as one REST request. When the limit is exhausted the tool returns an error result telling the assistant to retry shortly, rather than failing the whole conversation.

Simplify your API interaction with our Exported Postman Collections. This collection contains a curated set of API endpoints and request examples that will accelerate your development and integration processes.

Simply follow these steps to start interact with our Nimbly API

• Download Postman if you haven't already.
• Download our Exported Postman Collection (by Right-click the link and choose "Save link as…") and import it into your Postman workspace.
• Begin exploring our API by making requests, testing responses, and integrating the functionality into your applications.

Endpoints for accessing Nimbly statistics dashboard data.

Endpoints for searching Nimbly entities (sites, users, questionnaires).

Nimbly API for issue's related usecase. Issues are generated based on your report's answer. One example for this usecase is to get list of all issues created within your organization.

Endpoints for managing API rate limit configuration.

Nimbly API for report's related usecase. Reports are generated when you do a checklist in the form of questionnaire from the nimbly app. One example for this usecase is to get list of all reports generated within your organization.

Nimbly API for site's related usecase. Sites are locations where reports and issues are generated within your organization. One example for this usecase is to get list of all sites created within your organization.

Endpoints for listing and retrieving user details.

Endpoints for listing questionnaires.

Endpoints for listing schedules.

Endpoints for listing departments.