Using the Monterra API with API tokens

Written By Kelson Reiss

Last updated About 1 month ago

Required role: Admin · Tier: Pro (API Access)

The Monterra API lets you read and write your org's project data from your own scripts, BI tools, or integrations. Interactive reference and live request console live at /api-doc.

Generate an API token

Tokens are scoped to your org and expire on a fixed cadence.

  1. Open /tokens-control (linked as Get API Token from the API docs page).
  2. Click Generate Token. If one already exists, the button reads Update Token and rotates the old token.
  3. Copy the token immediately and store it somewhere safe. Treat it like a password.

The page shows days remaining until expiry. Once expired, regenerate from the same screen. Only admins on an org with the API Access module see the generate button; other admins see a prompt to email help@monterra.ai.

Authenticate requests

Pass the token in the x-api-token request header on every call. No other auth headers are needed (the org is derived from the token).

GET /api/projects HTTP/1.1Host: app.monterra.aix-api-token: <your-token>

A missing, malformed, or expired token returns 401 Unauthorized.

Resources

Browse the full schema at /api-doc. The main resources:

  • Projects (/api/projects). List, create, update, and delete projects. Supports filtering by status, sector, region, utility, address, tag, and created-at date range. Pass limit and offset for paginated responses (max limit 200).
  • Quotes (/api/projects/quotes). The latest quote for a project, including line items, markups, and totals.
  • Proposals (/api/projects/proposals). The generated proposal PDF for a project. Pass all=true to get every version.
  • Equipment (/api/pricebook/equipment). Your price book catalog items.
  • Additional costs (/api/pricebook/additional_costs). Fees, markups, and discounts from your price book.
  • Survey responses (/api/projects/survey-responses). Survey answers per project.
  • Notes (/api/projects/notes). Project notes.
  • Markers (/api/projects/map_elements/markers). Equipment and load placements on the project map.
  • Lines (/api/projects/map_elements/lines). Conduit and trench runs.
  • Photos (/api/projects/photos). Project photo metadata and uploads.
  • Files (/api/projects/files). Project file attachments.
  • Project stats (/api/analytics/project-stats). Aggregated counts and pipeline analytics.

Best practices

  • Page through large result sets. Pass limit and offset rather than fetching everything at once. The paginated response includes total_count so you can loop until you have everything.
  • Filter server-side. Use query params (status, created_after, tag, etc.) instead of pulling all projects and filtering in your script.
  • Cache the token, not the data. The token is stable until you rotate it. Store it as an environment variable in your script or BI tool.
  • Rotate after exposure. If a token leaks (committed to a repo, shared in chat), click Update Token to invalidate the old one immediately.
  • Back off on errors. If you see repeated 5xx responses, pause and retry with exponential backoff rather than hammering the endpoint.

Tips

  • The Swagger console at /api-doc runs live requests against production. Use it to confirm a payload shape before wiring it into your script.
  • The x-monterra-orgId header is set automatically from the token. You never send it yourself.