Tags

Introduction

Biomarkers and scores capture what the body does. Tags capture everything else—a symptom, a medication, a shift, a subscription—as discrete, time-bound records ready to query, stream, and correlate with health signals.

Tags can come from anywhere—the Sahha SDK reading device health platforms, Sahha's platform integrations with Garmin, Oura, and other connected services, or direct API calls from your own app or backend. Whatever the source, every tag arrives in the same shape: a name, an optional value, a type, and a time range.

Key Features

How It Works

A tag is a structured record with a name (what's being tracked), an optional value (the variant, severity, or dose), a type ( event or state), and a time range. The same schema is used whether the tag is a clinical signal collected by the SDK or a business event posted from your backend.

Events are points in time—a moment was recorded and nothing more. endDateTime must be null.

States span windows. A closed state has both startDateTime and endDateTime set. An open state has endDateTime: null, meaning the window is still active; close it later by re-uploading the same tag with an endDateTime set.

Identity is the tuple, not the id. Each tag's identity is derived from profile + name + type + source + startDateTime. The id field is server-generated; any value supplied on upload is ignored. Re-uploading a tag with the same identity tuple updates the existing record, so retries after transient errors and follow-up edits never create duplicates.

Tags flow into Sahha through three channels: the mobile SDK, Sahha's platform integrations with services like Garmin and Oura, and direct API calls from your backend or app. Reserved names must follow the schema below regardless of channel; custom names can use any shape. Reserved tags with a non-matching shape are rejected per-item (200 OK with the rejection reported in warnings)—the rest of the batch still lands. Tags flow out via the API and webhooks in the same shape they came in.

List of Tags (Reserved)

Sahha maintains a curated namespace of tag names with a fixed schema . Reserved tags can come from any source—the Sahha SDK (reading HealthKit and Health Connect), Sahha's platform integrations with Garmin, Oura, and other connected services, or your own app or backend—as long as the tag's type, category, and value match the entry below. Names inside this namespace arrive in a consistent shape across platforms and may power native analytics in future releases.

The namespace will grow over time. Currently it covers two categories: symptom and reproductive.

Symptom

Every symptom tag is logged with the same value set—a five-level severity scale—and arrives as a point-in-time event.

Reproductive

Reproductive tags use a mix of event and state types, each with its own closed value set (or no value for presence-only flags).

Reserved Additional Properties

The additionalProperties field is free-form on every tag—use any keys you need on custom tags. The keys below are populated by the SDK on specific reserved tags, so custom code shouldn't redefine them on the tags they appear on.

Custom Tags

Outside the reserved namespace there is no fixed schema —pick any category, name, and value your product needs. Custom tags use the same record shape, the same API, and the same webhook stream as reserved ones; they're stored and returned exactly as sent.

Typical custom use cases:

• Workforce & shifts — night_shift, on_call, field_deployment
• Subscription & lifecycle — premium_tier, trial, lapsed, onboarding_complete
• Clinical & coaching — medication, therapy_session, intervention_arm
• Habits & lifestyle — caffeine, alcohol, meal, meditation

Built-in analytics interpret reserved names only. Custom tags are first-class for storage and delivery, and any reporting you build on top can mix both freely.

Use Cases

Output Schema

Every tag returns a consistent JSON structure regardless of source or category.

{
	"id": "f3b1a8e0-4c5d-4e6f-9a8b-1c2d3e4f5a01",
	"type": "state",
	"category": "work",
	"name": "night_shift",
	"value": "12_hour",
	"source": "acme.workforce",
	"startDateTime": "2024-02-09T19:00:00+00:00",
	"endDateTime": "2024-02-10T07:00:00+00:00",
	"receivedAtUtc": "2024-02-10T07:05:02+00:00",
	"additionalProperties": {
		"role": "icu_nurse",
		"overtime": "false"
	}
}

More examples

An open state —still active, no end yet. Close it later by posting a follow-up tag with the same name and an endDateTime.

{
	"id": "f3b1a8e0-4c5d-4e6f-9a8b-1c2d3e4f5a02",
	"type": "state",
	"category": "subscription",
	"name": "premium_tier",
	"value": "annual",
	"source": "acme.billing",
	"startDateTime": "2024-01-28T00:00:00+00:00",
	"endDateTime": null,
	"receivedAtUtc": "2024-01-28T00:00:16+00:00",
	"additionalProperties": {
		"autoRenew": "true",
		"priceUsd": "99"
	}
}

An event with a dose — type: "event" requires endDateTime: null. The value field carries the dose at the top level so analytics can aggregate without parsing notes.

{
	"id": "f3b1a8e0-4c5d-4e6f-9a8b-1c2d3e4f5a03",
	"type": "event",
	"category": "medication",
	"name": "insulin_bolus",
	"value": "6_units",
	"source": "acme.clinical",
	"startDateTime": "2024-02-11T12:30:00+00:00",
	"endDateTime": null,
	"receivedAtUtc": "2024-02-11T12:30:10+00:00",
	"additionalProperties": {
		"timing": "before_breakfast"
	}
}

FAQ

Getting Started

Support

For help with Tags, reach out in the Slack community or contact support@sahha.ai .