Get Started

Introduction

Quickstart

Authentication

Use the API

Skill Catalog

Connect your agent

MCP Protocol

Rest Protocol

Billing

Wallet

Top up with Stripe

Reference

Error Codes

Response Envelope

Source on GitHub

Sally Platform docs

Sally Skills is a metered, agent-callable surface over Sally's metabolic-health stack. Plug it into any MCP- or REST-aware agent. Pay per call. No subscription.

These docs are a curated summary for users. The canonical reference — schemas, protocols, response shapes, error codes — lives in the open-source repo at a1c-ai-agent/sally-skills. Treat anything you read here as a starting point; the repo is always current.

New here? Skip to Quickstart — you can be calling Sally from your agent in 90 seconds.

Quickstart

Four steps from zero to a working integration.

Sign up on A1C Insights

Sally Skills uses your A1C account for identity. Install the iOS app and create an account if you haven't yet — sign-up is free.

Mint an API key

Sign in at console.a1c.io with the same email. Click + New key, give it a label (e.g. "Claude Code, laptop"), and copy the sk-sally-… value.

Save the plaintext now. You'll only see it once — the platform stores a hash, not the key itself.

Top up the wallet (only for paid skills)

health_sync is free. Paid skills check the wallet first and reject with 402 payment_required if you're short. Top up via Stripe Checkout on the Billing page.

Connect your agent

Drop the key into your agent's MCP or REST config. Worked examples in Connect your agent.

View source on GitHub →

Authentication

The sk-sally-… key is the identity. The gateway resolves every key to one A1C user and uses that user's UUID for every downstream query. Skill inputs never take a user identifier — schemas are strict and reject unknown fields with invalid_input.

How it works

Multi-key per user — mint a key per device or per agent. Each key has its own audit trail in usage_events.
Per-account wallet — top-ups are shared across every key. Revoking one key doesn't strand a balance.
Instant revocation — revoke from the console; other keys keep working.
Plaintext shown once — the platform stores a SHA-256 hash plus a 12-char prefix for lookup. The plaintext is never persisted server-side after creation.

Sending the key

Every request to sally.a1c.io needs the Authorization header:

Authorization: Bearer sk-sally-...

Full identity model in SYSTEM_DESIGN.md →

Skill catalog

Six skills live today. Discover them programmatically via MCP tools/list or REST GET /v1/skills — both return the same set with versions, descriptions, JSON-Schema inputs, and prices.

FREE

health_sync

Wearables, CGM, sleep, vitals, activity, environment — daily series + opt-in minute-base CGM.

$0.003

chat_with_sally

Conversational preventive-health + TCM knowledge with source citations.

$0.008

analyze_lab_result

Lipid, HbA1c, CBC, thyroid, hormone, micronutrient panels via VLM OCR + clinical analysis.

$0.004

food_journal

Assess meals via inline image — macros, smart/trap categorisation, dish naming.

$0.003

health_insights

Daily readouts — morning, afternoon, evening, or auto.

$0.005

metabolic_overview

CGM-powered snapshot — TIR, variability, postprandial spikes, with what-is-driving narrative.

Roadmap (coming soon)

These appear in tools/list as coming_soon so agents discover the roadmap; tools/call rejects them with not_found until live.

health_report — longitudinal biomarker trends + clinician-shareable summaries
metabolic_risk_score — 5- and 10-year T2D, metabolic syndrome, cardiovascular risk
supplement_grading — interactions, evidence quality, biomarker gaps
preventive_protocol — multi-week intervention plans with checkpoints

Canonical catalog in SKILLS.md →

Connect your agent

Any MCP-aware client takes the same shape: server URL + Authorization header. Drop it in and restart the agent — the LLM picks tools from tools/list on its own, no per-skill wiring.

Claude Code

Add to ~/.claude/mcp.json (or per-project .mcp.json):

{
  "mcpServers": {
    "sally": {
      "url": "https://sally.a1c.io/mcp",
      "headers": { "Authorization": "Bearer sk-sally-..." }
    }
  }
}

Claude Desktop

Same JSON, in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or the equivalent path on Windows.

Cursor, Continue, Hermes, OpenClaw

Each client has its own MCP config file but the shape is identical. See the per-client guides on GitHub for exact paths.

Custom REST integration

curl -sS https://sally.a1c.io/v1/call \
  -H "Authorization: Bearer sk-sally-..." \
  -H "Content-Type: application/json" \
  -d '{ "skill": "health_sync", "input": { "aggregate": true } }'

Per-client guides on GitHub →

MCP protocol

The gateway speaks Model Context Protocol (JSON-RPC 2.0 over HTTPS) at https://sally.a1c.io/mcp.

tools/list

Discover every available skill, including roadmap (coming_soon) entries.

POST /mcp
Authorization: Bearer sk-sally-...
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

tools/call

Invoke a skill by name with its input arguments.

{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "health_sync",
    "arguments": { "aggregate": true }
  }
}

Full MCP protocol docs →

REST protocol

Dispatcher endpoint

Single entry point — pick the skill in the body.

POST https://sally.a1c.io/v1/call
{ "skill": "health_sync", "input": { ... } }

Per-skill endpoint

Same dispatcher, slightly cleaner URL — name in the path.

POST https://sally.a1c.io/v1/skills/health_sync
{ ... input ... }

List skills (no auth)

curl -sS https://sally.a1c.io/v1/skills | jq

Full REST reference →

Wallet

One wallet per A1C account, keyed on your user UUID. Every sk-sally-… you mint draws from the same balance.

Free skills work regardless of balance — pre-check is skipped.
Paid skills deduct on success. Failures are logged but not billed.
Insufficient balance → 402 payment_required before any upstream cost is incurred.
Per-key audit — every call records api_key_id in usage_events so you can see which key spent what.

See your balance + recent calls on console.a1c.io/billing.

Top up with Stripe

Card payments via Stripe Checkout. No subscriptions — one-time top-ups credit the wallet immediately.

Sign in at console.a1c.io/billing
Pick a preset ($5 / $10 / $20 / $50 / $100) or enter a custom amount ($5–$500)
Stripe-hosted checkout → enter your card → submit
You're redirected back to the console; balance updates within ~2s

x402 onchain micropayments are on the roadmap but not live. Stripe is the only payment method for now.

Refunds & disputes

Email ai@sallya1c.com with the Stripe payment ID. Refunds flow back through Stripe and automatically debit the wallet via the webhook.

Error codes

Every error returns the same envelope with a stable code and a human message. The HTTP status mirrors the code semantically.

Code	HTTP	When
`unauthorized`	401	Missing, malformed, or revoked key
`payment_required`	402	Wallet balance < skill price
`forbidden`	403	Key valid but not allowed for this skill / user
`not_found`	404	Unknown skill name, or `coming_soon` called via `tools/call`
`invalid_input`	422	Zod input validation failed (check the `details` field)
`rate_limited`	429	Per-key per-skill token bucket exhausted
`upstream_error`	502	Upstream service (langchain / OCR) returned an error
`gateway_error`	500	Bug in the gateway itself — please file an issue

Latest error reference on GitHub →

Response envelope

Every response — REST or MCP — follows the same shape.

Success

{
  "ok": true,
  "skill": "health_sync",
  "version": "1.0.0",
  "data": { "...": "skill-specific payload" },
  "usage": { "units": 1, "cost_usd": 0 }
}

Error

{
  "ok": false,
  "skill": "health_sync",
  "error": {
    "code": "invalid_input",
    "message": "requested window is 120 days; max is 90",
    "details": null
  }
}

Source on GitHub

Treat a1c-ai-agent/sally-skills as the single source of truth. These docs are a curated summary; the repo always reflects the latest live behavior. File issues for bugs, open PRs for fixes, or just star the repo to keep tabs.

README.md — onboarding, agent setup snippets, curl examples
SKILLS.md — full skill catalog, prices, error codes
packages/ — per-skill READMEs (input/output schemas, pricing rationale)
protocols/ — MCP and REST protocol guides
agents/ — per-client setup guides (Claude Code, Desktop, Cursor, etc.)

Ready to Plug in?

Get an API key