nLight.fit developer resources

Everything nLight.fit publishes for people and programs building against it, with the URL of each and a request you can run for every one. If you are an agent deciding whether this API is integrable, this page and the documents it links are the whole answer.

This page is also served at /api and /api-docs, and as raw Markdown at /docs/developers.md.

Start here

The MCP server is the intended integration point. nLight.fit exposes a member's health record as read-only Model Context Protocol tools over Streamable HTTP, so an MCP client calls them natively rather than through a REST wrapper you have to write. The REST endpoints exist because the web app uses them.

Nothing below needs an account to try. The handshake and the tool catalog on the real endpoint need no credential, and the sandbox needs none for anything at all.

Call the sandbox

https://nlight.fit/api/sandbox speaks the same protocol with the same tool schemas against a synthetic member record. No account, no token, no approval:

curl -sS https://nlight.fit/api/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Every tool works. Every value is generated, and every response says so.

Handshake with the real server

initialize and tools/list are answered on the production endpoint without a credential too, so you can confirm the server is real and see the tool surface before anyone signs up:

curl -sS https://nlight.fit/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2026-07-28","capabilities":{},
                 "clientInfo":{"name":"my-client","version":"1.0.0"}}}'

curl -sS https://nlight.fit/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

tools/call is where a credential becomes necessary, because that is where a member's record is read.

Or use the CLI

npm install -g https://nlight.fit/cli/nlight-fit-latest.tgz
nlight discover      # fetch every developer document listed below
nlight init          # MCP handshake against the sandbox
nlight tools         # list the tools
nlight call get_streak metric=vitamins

Installing from that URL needs no registry account — npm supports tarball URLs natively, and it is the same artifact npm publish would upload. Registry publication is pending; x-cli.registryPublished in the OpenAPI document says whether npm install -g nlight-fit works yet. See the CLI reference for the full command set and how to point it at production.

Machine-readable resources

Every documentation page is also served as raw Markdown at /docs/<slug>.md — for example /docs/mcp.md — with no navigation chrome to strip. Every HTML page on the site serves Markdown under Accept: text/markdown.

Endpoints

A version alias exists at /api/v1/* for tooling that expects a version segment in the path. It routes to exactly the same handlers; see versioning and deprecation.

The full operation list, with request and response schemas for each, is in the OpenAPI document. It is built from the same constants the handlers use, so a documented operation that no longer exists fails the build rather than misleading a generated client.

Service status

healthCheck is the one REST action that needs no credential, and it is what the API catalog names as this API's status link:

curl -sS https://nlight.fit/api/proxy \
  -H 'Content-Type: application/json' \
  -d '{"action":"healthCheck"}'

{
  "version": "3.1.0",
  "status": "healthy",
  "timestamp": "2026-08-23T00:00:00.000Z",
  "mongodb": "connected"
}

A signed-in caller gets the same fields plus operational detail. Anyone can poll the four above.

Authentication

There are two routes, and which one you want depends on whose record you are reading.

Your own account: three calls, no human

Signup is open, so a program can go from nothing to calling tools without anyone approving anything:

# 1. Create an account. The response carries a session token.
curl -sS https://nlight.fit/api/auth \
  -H 'Content-Type: application/json' \
  -d '{"action":"register","username":"my-agent","password":"..."}'

# 2. Exchange that session for a read-scoped API token.
curl -sS https://nlight.fit/api/tokens \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <session token from step 1>' \
  -d '{"action":"create","name":"my-agent","scopes":["read"]}'

# 3. Use it.
curl -sS https://nlight.fit/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer rt_ro_...' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_columns","arguments":{}}}'

This is the path credentialSteps in x-access-terms describes, with humanInvolved: false on every step. A member can do step 2 from Settings → MCP / CLI Access instead.

Somebody else's account: OAuth 2.1

A client reading a member's record — Claude connecting to someone's health history — goes through OAuth, because that is where a person decides to share it.

1. An unauthenticated tools/call returns 401 with WWW-Authenticate: Bearer realm="routine-tracker-mcp", resource_metadata="https://nlight.fit/.well-known/oauth-protected-resource".
2. That document names the authorization server. Its metadata is at /.well-known/oauth-authorization-server.
3. Register dynamically (RFC 7591) at POST /api/oauth/register. Public clients only — there is no client secret.
4. Send the member through GET /api/oauth/authorize with a PKCE code_challenge (S256; plain is not accepted). They approve a consent screen.
5. Exchange the code at POST /api/oauth/token with the code_verifier.

Step 3 is open, and you can do it right now. Registration needs no credential and no human:

curl -sS https://nlight.fit/api/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"my-client",
       "redirect_uris":["https://example.com/callback"],
       "grant_types":["authorization_code","refresh_token"],
       "response_types":["code"],
       "token_endpoint_auth_method":"none"}'

{
  "client_id": "…",
  "client_id_issued_at": 1787450670,
  "token_endpoint_auth_method": "none",
  "scope": "read"
}

Step 4 is the one step in this route that a program cannot complete, and that is deliberate: it is where a person decides to share their own medical record. It is published as data under delegatedAccess in x-access-terms, alongside the fully automatable credentialSteps above, so a client can pick the route that matches what it is doing rather than discover the boundary by hitting it.

In Claude, all of that is Add custom connector and pasting https://nlight.fit/api/mcp.

Tokens are read-only today, carry their scopes in the database rather than in the token string, and are revoked individually and immediately. Full detail in authentication and token management.

Conventions every response follows

Rate limits are reported, not just enforced. Every response carries RateLimit-Policy describing the quota, and every response that spends or reads one carries RateLimit describing what is left, so a client paces itself instead of discovering the limit by hitting it. A 429 adds Retry-After.

RateLimit-Policy: "mcp";q=120;w=60
RateLimit: "mcp";r=118;t=47
RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 47

RateLimit and RateLimit-Policy follow the IETF structured-field draft; the three-header form is the earlier draft, sent alongside because that is what most existing SDKs read. The complete quota table is published as data under x-ratelimit-policies in the OpenAPI document. Details in errors and limits.

The version is on every response. Api-Version names the API version that answered. Deprecation, when it happens, arrives as a Deprecation header (RFC 9745) and then a Sunset header (RFC 8594), with notice periods stated in the versioning policy.

Every response links back to this documentation. The Link header carries service-desc (the OpenAPI document), service-doc (this page) and version-history (the versioning policy), so a client holding any response can find the rest without a discovery request.

Errors are structured. REST failures return error, a stable code where one applies, and a requestId to quote in a support request. MCP failures are JSON-RPC error objects with the standard codes. Both tables are in errors and limits.

Human-readable documentation

• MCP server — transport, methods, which need no credential, scope, and what is deliberately not exposed. Also at /mcp.
• MCP tool reference — all eighteen tools with full input schemas.
• Client setup — connecting Claude Desktop, Claude Code or Cursor.
• Sandbox — the credential-free environment and what its data is and is not. Also at /sandbox.
• Authentication — token format, scopes, storage and revocation.
• nLight.fit CLI — npm install -g https://nlight.fit/cli/nlight-fit-latest.tgz. Also at /cli.
• Token management — minting and revoking tokens from Settings.
• Errors and limits — status codes, JSON-RPC error codes, rate limits and protocol versions.
• Versioning and deprecation — how change is signalled before it lands. Also at /deprecation.
• Security and privacy — encryption, third-party handling, and an honest account of what is not protected.

What it costs

Tracking is free, and API and MCP access are part of the free tier. Member is $50/year and changes how hard the coach thinks over a member's own history — it does not change what this API exposes.

The machine-readable version is x-access-terms in the OpenAPI document and _meta."fit.nlight".pricing in the MCP manifest, with credentialSteps giving the path above and delegatedAccess giving the OAuth one.

Signup is open, so nothing here needs a human. Building against the sandbox first is still the better order — you never create an account you do not need, never handle someone's real bloodwork while you are still getting the shapes right, and you develop against a populated record rather than an empty one. Then change one URL: the tool names, schemas, validation and response envelopes are the same objects in both, not two implementations kept in agreement by hand.

Contact

Austin@nLight.fit — one mailbox, for developer questions and security reports alike. Please report security issues privately and allow a reasonable window for a fix before disclosure.

nLight.fit is based in Boston, MA.