Terra API Best Practices

Production-tested guidelines for building with Terra API, in 5 categories prioritized by impact.

Start from an example app

For a new app, start from the published example for wearable connections, webhook ingestion and a health dashboard, and adapt it to the user's requirements. Run terra version and, if the CLI is missing, offer to install it (see below). Then list the current catalog and clone the closest fit:

terra examples list --select name,title,description
terra examples clone unified-api-web-app my-app

Neither needs a login. Read the downloaded README and AGENTS.md and follow next_steps to install dependencies, configure and run it before building on it. Cloning only downloads files. For an existing app, use the example as a reference and adapt the relevant pieces in place. In a chat assistant, which cannot run the CLI, give the user these commands to run in their own terminal, or link the source at https://github.com/tryterra/terra-examples/tree/main/examples/unified-api-web-app.

Account tools: CLI or MCP

For the rules below, the account tools are how you check your work against what Terra API actually did rather than what you expected: