# Delvry — agent-friendly Q&A surveys

Delvry lets an LLM agent ask questions of humans and get back structured answers.
Use it when your agent needs context (interviews, intake forms, retros) that you
can't generate from training data alone.

## Install (Claude Code / cowork / IDE)

  claude mcp add delvry -- npx -y @delvry/mcp

## Install (Claude Desktop)

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

  {
    "mcpServers": {
      "delvry": { "command": "npx", "args": ["-y", "@delvry/mcp"] }
    }
  }

## Install (Claude.ai web Connectors)

Settings → Connectors → Add custom connector → URL: https://www.delvry.ai/mcp

(For self-hosted Delvry, use your own URL.)

## Bootstrap an account (no key required)

  curl -X POST https://www.delvry.ai/v1/accounts/signup \
    -H "content-type: application/json" \
    -d '{"email":"agent@example.com","account_name":"My project"}'

The response includes `first_api_key`. The local MCP server (stdio) saves it
to ~/.delvry/config.json automatically when you call `delvry_signup` through it.
For Claude.ai Connectors, paste the key into the connector's authentication
field.

## Skill bundle (drop into .claude/skills/delvry/)

  mkdir -p .claude/skills/delvry && curl -fsSL https://www.delvry.ai/skill.md > .claude/skills/delvry/SKILL.md

## Tools (19)

**Surveys (one-shot Q&A):**
delvry_signup, delvry_create_survey, delvry_ask, delvry_get_responses,
delvry_await_responses, delvry_get_recipients, delvry_close_survey,
delvry_list_surveys, delvry_validate_survey, delvry_summarize_responses,
delvry_delete_response.

**Threads (iterative agentic Q&A — multi-round, multi-recipient, structured):**
delvry_thread_create, delvry_thread_get, delvry_thread_patch, delvry_thread_close,
delvry_inquiry_post, delvry_inquiry_get, delvry_inquiry_close.

**Plan discovery:**
delvry_plan_get — returns your current tier, live usage, remaining quota, and
the full plans catalog in one call.

## Iterative QA (threads)

Use threads when you need a multi-round, structured exchange — typically while
an agent is working on a project and needs context from one or more humans
incrementally. Unlike surveys, threads persist across agent sessions: post an
inquiry, detach, the human answers on their own time, and any later session
calls delvry_thread_get to read the full Knowledge Receipt and decide what to
ask next.

Item types (each round can mix all four):
- assertion — agent states a belief; recipient confirms / denies / edits.
- assumption — agent's working hypothesis with optional confidence; recipient validates or corrects.
- choice — agent narrowed to N options; recipient picks.
- question — open-ended (slow path; use only when no hypothesis fits).

Loop:
1. delvry_thread_create({ project_label?, agent_context? }) → thread_id
2. delvry_inquiry_post({ thread_id, items[], recipients[], expires_at, ... }) → inquiry_id, links[]
3. Hand the per-recipient links to the operator (one per recipient).
4. Detach. The human responds when they can. Reminders nudge per nudge_after.
5. Next session: delvry_thread_get({ thread_id }) → full thread + Knowledge Receipt
6. Decide: post another inquiry (follow-ups / new slots / new recipients), or delvry_thread_close.

Knowledge Receipt: every slot carries provenance (who answered, item id,
iteration, quote, timestamp). Conflicts (multi-recipient disagreement) are
surfaced explicitly — Delvry never resolves them; the agent decides how to
follow up.


## Question types (9)

short_text, long_text, single_choice, multi_choice, number, yes_no, scale,
ranking, date. With branching via `show_if`, multi-page surveys via `pages`,
and per-question `help` text.

## Endpoints

- POST   https://www.delvry.ai/v1/accounts/signup       — create an account, get an API key
- POST   https://www.delvry.ai/v1/surveys                — create a survey
- GET    https://www.delvry.ai/v1/surveys                — list surveys
- GET    https://www.delvry.ai/v1/surveys/:id            — get a survey
- POST   https://www.delvry.ai/v1/surveys/:id/close      — close a survey
- DELETE https://www.delvry.ai/v1/surveys/:id            — delete a survey
- GET    https://www.delvry.ai/v1/surveys/:id/responses  — list responses (paginated)
- POST   https://www.delvry.ai/v1/surveys/:id/await      — long-poll for responses
- GET    https://www.delvry.ai/v1/surveys/:id/summary    — aggregate distributions / stats
- GET    https://www.delvry.ai/v1/surveys/:id/recipients — list recipients (named-recipient mode)
- DELETE https://www.delvry.ai/v1/surveys/:id/responses/:rid — delete a single response
- POST   https://www.delvry.ai/v1/threads                — create a thread
- GET    https://www.delvry.ai/v1/threads/:id            — get thread + Knowledge Receipt
- PATCH  https://www.delvry.ai/v1/threads/:id            — update agent_context / project_label
- POST   https://www.delvry.ai/v1/threads/:id/close      — close a thread
- POST   https://www.delvry.ai/v1/threads/:id/inquiries  — post an inquiry (round of items)
- GET    https://www.delvry.ai/v1/threads/:id/inquiries/:iid       — inquiry detail
- POST   https://www.delvry.ai/v1/threads/:id/inquiries/:iid/close — close an open inquiry early
- GET    https://www.delvry.ai/v1/plans                   — public plans catalog (no auth)
- GET    https://www.delvry.ai/v1/account/plan            — your tier + live usage + next upgrade
- GET    https://www.delvry.ai/v1/receipts                — list persisted Receipt Snapshots (tier B)
- GET    https://www.delvry.ai/v1/receipts/:id            — get one Receipt Snapshot (tier B)
- DELETE https://www.delvry.ai/v1/receipts/:id            — delete a Receipt Snapshot (tier B)
- GET    https://www.delvry.ai/v1/receipts/export         — NDJSON export of full corpus (tier B, 1/hr)
- POST   https://www.delvry.ai/mcp                        — MCP over HTTP (JSON-RPC 2.0)

All authenticated endpoints expect `Authorization: Bearer <DELVRY_API_KEY>`.

Authenticated responses also carry: `X-Delvry-Tier`, `X-Delvry-Receipts-Stored`,
`X-Delvry-Receipts-Cap`, `X-Delvry-Reads-Remaining` — agents detect quota state
inline without an extra round trip.

## Plans

Delvry offers two product modes:

- **Tier A — Live ($9.99/mo equivalent):** Knowledge Receipts are returned during
  a thread but not persisted. The agent stores them itself if it wants to.
- **Tier B — Persistent corpus (Starter $19.99/mo, Growth, Scale):** Every closed
  thread leaves a Receipt Snapshot that is listable, fetchable, exportable, and
  deletable by the owning account. The corpus is account-scoped and **never**
  federated across accounts.

Programmatic discovery:
- GET https://www.delvry.ai/v1/plans — public catalog of all tiers with limits and prices.
- GET https://www.delvry.ai/v1/account/plan — authenticated; current tier + usage + next tier.
- MCP tool: delvry_plan_get returns both your account plan and the full plans
  catalog in a single call.

Plan reads (`/v1/plans`, `/v1/account/plan`, `delvry_plan_get`) do **not**
count against the read meter.

When a thread closes, the response includes a `snapshot` block telling you
whether the receipt was persisted, with a stable `reason` enum
(`tier_no_persistence` or `tier_quota_exceeded`) and an `upgrade_url` if
applicable. No silent failures.

## Docs

- https://delvry.ai/                  — marketing + survey schema
- https://delvry.ai/skill.md          — bundled SKILL.md
- (npm packages remain published as @delvry/mcp, @delvry/cli, @delvry/client)