Developer Documentation

Welcome to the Nostavia API. Our infrastructure provides a unified, typed GraphQL and REST interface for ingesting raw clinical data (PDFs, LIS HL7 feeds, wearable telemetry) and extracting structured clinical intelligence via the SOMA Dual-Brain architecture.

Authentication

The Nostavia API uses API keys to authenticate requests. You can view and manage your API keys in the Nostavia Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Bearer Token Auth

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value in the Authorization header.

curl -X GET https://api.nostavia.com/v1/users \
  -H "Authorization: Bearer nostavia_sk_test_51Mz..."

Environments

We provide two distinct environments to ensure safe development without risking PHI exposure.

• Sandbox (api.sandbox.nostavia.com): Uses synthetic data models. Any PDFs uploaded here are piped to a deterministic mock engine that returns predictable dummy data. Keys start with nostavia_sk_test_.
• Production (api.nostavia.com): The live SOMA engine. Requires signed BAAs (Business Associate Agreements). Keys start with nostavia_sk_prod_.

Webhooks & Events

Because clinical interpretation of large 50-page PDF lab reports can take up to 2.5 seconds, we highly recommend using asynchronous processing with Webhooks rather than holding HTTP connections open.

Verifying Webhook Signatures

Nostavia signs the webhook events it sends to your endpoints by including a signature in each event's Nostavia-Signature header. This allows you to verify that the events were sent by Nostavia, not by a third party.

We use HMAC SHA-256 for the signature. Here is a complete Node.js example to verify the incoming payload:

import crypto from 'crypto';
import express from 'express';

const app = express();
const endpointSecret = 'whsec_9b83b...';

app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['nostavia-signature'];
  const timestamp = request.headers['nostavia-timestamp'];
  
  // 1. Recreate the signed payload
  const signedPayload = `${timestamp}.${request.body.toString()}`;
  
  // 2. Compute HMAC
  const hmac = crypto.createHmac('sha256', endpointSecret);
  const expectedSig = hmac.update(signedPayload).digest('hex');
  
  // 3. Compare securely to prevent timing attacks
  if (crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) {
    console.log("Webhook verified!", JSON.parse(request.body));
    response.send();
  } else {
    response.status(400).send('Webhook Error: Invalid Signature');
  }
});