Reference for the Mountly public API

Some Mountly endpoints are public, while others require a bearer token. When a request is protected, send the token in the Authorization header:

Authorization: Bearer <access_token>

Authentication is not just a header requirement. It is part of the trust boundary around your integration, so the most important decisions happen before the request is ever sent: which workspace issued the token, what the token is meant to do, where it will be stored, and who is responsible for replacing it when that becomes necessary.

Keep tokens on trusted infrastructure

For most integrations, the safe default is simple: store the token outside source control, keep it in environment variables or a secret manager, and send protected requests from trusted server-side code. Long-lived credentials do not belong in browser-delivered code or other untrusted clients.

That approach does two things at once. It reduces the chance of accidental exposure, and it keeps the integration model clear for the next person who has to maintain it.

Issue tokens with a narrow purpose

The easiest integrations to understand are the ones where a token has one obvious job. A token might exist to read form entries for a sync process, power an internal reporting tool, or feed accepted submissions into a single downstream system. That narrow scope makes the integration easier to reason about and limits the blast radius if the credential ever needs to be rotated or revoked.

If a teammate asks what a token is for, the answer should fit in a sentence. When that answer is vague, the integration usually becomes harder to own over time.

Rotate and retire credentials deliberately

Tokens tend to outlive the original setup work, so it helps to manage them as part of the workflow rather than as a one-time configuration step. Rotate them when ownership changes, revoke them when an integration is retired, and replace them immediately if you suspect they were exposed.

It is also worth keeping a simple record of which integration depends on which token. That small habit prevents the common situation where a team inherits long-lived credentials that nobody feels confident touching.

What to do next

Once authentication is in place, continue with Conventions. That section explains the shared request and response patterns your client should preserve, including JSON bodies, timestamps, and pagination metadata.

The Mountly public API is easier to implement when you treat it as one consistent contract rather than a collection of unrelated endpoints. The same payload shapes, timestamp rules, and pagination patterns appear across the API, so a little consistency in your client code goes a long way.

Expect JSON bodies and date-time fields

Request and response bodies are JSON. Timestamps such as createdAt and updatedAt are exposed as date-time strings, which means your client should treat them as machine-readable values rather than presentation text.

That sounds minor, but it affects a lot of downstream behavior. If a client flattens timestamps into display strings too early, bugs tend to show up later in sorting, exports, filtering, or comparisons between systems.

Preserve pagination metadata when it appears

List endpoints may include pagination metadata, and that metadata is part of the contract rather than decoration. Fields such as currentPage, pageSize, pageCount, totalEntries, hasNextPage, and hasPreviousPage tell your client how much data exists, where the current slice sits, and whether another request is needed.

If you are building exports, dashboards, or sync jobs, preserving those fields will make the client much more reliable than trying to reconstruct pagination state from guesses.

Reuse shared schemas instead of remapping everything locally

Forms, form entries, and common error envelopes appear in more than one place throughout the API. The generated reference keeps those shared schemas visible so your client can model them once and reuse them across reads, writes, and follow-up processing.

That approach usually leads to cleaner integrations. Instead of hardcoding slightly different versions of the same object in multiple places, you end up with one stable understanding of the data shape and far fewer subtle mismatches later.

Good defaults for a new client

When you are starting fresh, a few habits make the implementation easier to extend. Begin with a read-only request before you add writes. Let the generated reference drive field names and request shapes. Preserve pagination metadata whenever the API returns it. Model shared objects as reusable types rather than one-off mappings scattered through the codebase.

Those are modest choices, but they keep the client closer to the published contract and make later changes much less painful.

What to do next

Continue with Error handling so you can decide which failures should be surfaced, which require changes to the request, and which may be worth retrying.

Mountly returns structured error responses so your client can react to the kind of failure it received instead of treating every non-success the same way. That structure matters because an expired credential, a malformed payload, and a temporary backend issue do not deserve the same response from your code or your team.

Learn the two shared error shapes first

Two response shapes appear most often in practice:

When you need exact field names, the generated schemas below are the source of truth. At a higher level, though, it is enough to remember that Mountly separates general failures from validation failures so your client can handle them differently.

Respond to failures by category

The most useful first distinction is not between status codes, but between classes of problems.

Once your client makes that distinction, error handling becomes much more predictable. Teams can fix the actual problem instead of lumping every failure into a generic retry loop.

Treat validation failures as actionable feedback

Validation errors are usually the easiest ones to improve because the API is telling you exactly what is wrong with the input. Read the errors object, surface the field-level detail where the team or user can act on it, and correct the payload before trying again.

Retrying the same invalid request rarely helps. The productive response is to change the data, not to repeat the call.

Log for debugging without leaking secrets

When a request fails, your logs should make the failure understandable without exposing sensitive information. Capture which endpoint failed, which workflow or integration sent the request, and whether the problem looked like access, validation, or a likely transient condition. Include enough context to reproduce the issue safely, but avoid logging tokens or sensitive payload data unless it has already been redacted.

If someone can diagnose a problem from the logs without opening a secret store or replaying the entire workflow from memory, the error handling is already doing useful work.

What to do next

Use the generated schemas below when you need the exact structure of general and validation error responses, and handle them differently in code so the next step is clear whenever a request fails.