Change report templates from your own code.

What you are connecting

The API is a small set of HTTPS calls at https://api.orvexaai.cloud. The TypeScript SDK makes those same calls. It lives in this product as sdk/src/index.ts and is not published to npm, so any language can use the HTTP API directly.

You do not send a clinic id. The key belongs to one clinic and one environment, and every request uses that clinic. A browser login cannot call these routes, and an API key cannot open the clinic app.

Test key and live key

A clinic can have one active key of each kind. Creating a new one turns the previous key off immediately.

Use the test key while you are editing a draft. Use the live key only when you mean to change the template the clinic is using.

Create a key

Only an owner or admin can create or revoke keys.

1. Sign in to the clinic.
2. Open Settings and find SDK access.
3. If the clinic requires two-step sign-in for owners and admins, finish that first. Settings will not create a key until the second step is on.
4. Create the test key. Copy it when it appears. It is shown once.
5. Store it outside the repo, for example in an environment variable named ORVEXA_API_KEY. Do not commit it, paste it into chat, or put it in frontend code.
6. Create the live key the same way when you are ready to update a published template.

Settings then shows the start of the key and the last time it was used. It does not show the secret again. Replace stops the old key immediately. Revoke does the same. Orvexa stores a hash of the key, not the key itself.

Connect

Import Orvexa from sdk/src/index.ts if you have the repository. Otherwise send the same request with any HTTP client.

import { Orvexa } from "./sdk/src/index.ts";

const apiKey = process.env.ORVEXA_API_KEY;
if (!apiKey) throw new Error("Set ORVEXA_API_KEY");

const orvexa = Orvexa.connect({
  apiUrl: "https://api.orvexaai.cloud",
  apiKey,
});

const workspace = await orvexa.workspace();
// workspace.environment is "test" or "live"
// workspace.organization_id is this clinic

connect rejects a key that does not start with ovx_test_ or ovx_live_. A revoked or unknown key fails on the first request with 401.

curl https://api.orvexaai.cloud/api/v1/sdk/workspace \
  -H "Authorization: Bearer $ORVEXA_API_KEY"

{
  "workspace": {
    "organization_id": "your-clinic-id",
    "environment": "test"
  }
}

You can send the key as Authorization: Bearer or as X-API-Key. Both name the same key.

Change a template

Read the template, edit that schema, and save the whole schema back. The API replaces the current version. It does not merge a partial body.

const templates = await orvexa.templates();
const template = templates.find((item) => item.name === "Progress report");
if (!template) throw new Error("Template not found");

template.schema.code_layout = {
  html: "<article>{{ sections }}</article>",
  css: "article { font-family: Georgia, serif; }",
};

await orvexa.save(template.id, template.schema);

if (workspace.environment === "live") {
  await orvexa.publish(template.id);
}

Each template in the list includes:

• id and name
• status: draft, published, or archived
• version_id and version_number for the current version
• schema, including sections and an optional code_layout with html and css

A draft can be incomplete. A published template has to be complete, and so does a draft you publish. If the schema is not valid, the response says what to finish.

The template editor in the browser does not refresh on its own. Reload it to see the write. If someone else saved that version first, you get 409. Load the template again and save your change on the new version.

HTTP API

Every path is under https://api.orvexaai.cloud. Send JSON, with Content-Type: application/json, on the write calls.

The TypeScript methods are workspace(), templates(), template(id), save(id, schema), and publish(id).

What is recorded

Owners and admins can see this in two places. Settings shows the start of each active key and the last time it was used. Team, then Activity log, records the change itself.

The key is not a staff login, so a template write is recorded as System. The stored record keeps the environment, the template, and the version number. It does not keep the API key, patient information, or the template HTML.

In the activity log, choose Templates for saves, publishes, and restores. Choose SDK keys for keys that were created or revoked. All activity shows both.

Limits and errors

Limits are counted per key, over one minute.

• Reads: 120
• Saves: 60
• Publishes: 30, and each publish also counts toward the save limit

A refused request returns 429 and a Retry-After header, with the message “Too many requests. Wait a moment and try again.”