AQUA Application Hub Developers

AQUA developer portal

An application infrastructure API lets developers programmatically access reusable application answers, opportunity fit scoring, and application graph data. The AQUA Application Hub REST API exposes these capabilities with typed operations, the local AQUA companion (a stdio MCP server with 43 tools) for agent environments, and a deferred Appfeeder capture integration. Public discovery routes are available without authentication; user-account endpoints require a Supabase session cookie or Bearer JWT.

Quickstart

Public discovery APIs are available without authentication; private account APIs require a session or Bearer JWT. Under local-first mode, legacy hosted private-answer write routes refuse requests (HTTP 403 with local_first:true). Sign in at /login to get a session cookie, or retrieve a Bearer JWT from GET /api/auth/token for the browser extension. Agents never need a JWT: they work through the local AQUA companion. Start with the OpenAPI document for typed operations and error models.

# Get your auth token (requires active session)
curl https://aquaidp.xyz/api/auth/token

# The local-first MCP manifest and the public catalog configuration
curl https://aquaidp.xyz/.well-known/mcp
curl https://aquaidp.xyz/.well-known/aqua-catalog.json

# Private answer matching happens in the local vault, not
# /api/match-question — that route returns 403 under local-first.

# Read the OpenAPI spec
curl https://aquaidp.xyz/openapi.json | jq .info

OpenAPI specification

The full OpenAPI 3.0.3 document is published at /openapi.json. It documents 10 operations across matching, applications, answers, hub, review, drafting, and auth. Every operation has a unique operationId, typed request/response schemas, and documented error models. Some legacy private-write operations are listed for compatibility but refuse with HTTP 403 in local-first mode.

  • matchQuestion — match a question against the user answer bank
  • intakeApplication — ingest raw application text and extract questions
  • captureAnswer — capture an answer from a form field (extension)
  • smartMatcher — compute fit scores for a target program
  • checkAutofillEligibility — check auto-fill eligibility thresholds
  • stressTestAnswer — run a reviewer-persona stress test
  • generateDraft — generate a draft answer via BYOK or platform LLM

Authentication

AQUA uses Supabase Auth. Two credential types are accepted:

Session cookie (browser)

After login at /login, Supabase sets an sb-access-token cookie. The web app and browser extension use this automatically.

Bearer JWT (browser extension)

Send Authorization: Bearer <JWT> with API requests. Get the JWT from GET /api/auth/token while logged in.

MCP server: the local AQUA companion

Agents work through the AQUA companion, a zero-dependency command-line tool and stdio MCP server the user runs on their own machine. It works on one consented, encrypted workspace plus the public catalog, holds no account token and no database key, and cannot approve, sign, freeze, export or submit anything: the human approves in the browser review. It registers 43 tools (22 read, 15 private_write, 1 human_consent, 5 human_only); tiers are enforced in code. The full guide is at /agents.

# Install (aqua-mcp-server from npm, Node.js 22+; it includes the companion)
npx -y aqua-mcp-server --help

# Connect Claude Code (the server starts without a workspace)
claude mcp add aqua -- npx -y aqua-mcp-server --keychain

# Fallback: the companion tarball from this site
npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz --help

# Self-check: config, catalog, workspace, keychain
npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz doctor
  • npm: aqua-companion is also published on npm. aqua-mcp-server on npm includes it and is the primary install, so use that; the tarball above is the fallback.
  • aqua-mcp-server is published on npm and is the primary install: `npx -y aqua-mcp-server`. It includes the companion and serves the same tools. Versions below 2.0 are legacy and must not be used.
  • Hosted read-only MCP at https://aquaidp.xyz/mcp: live.
  • Public catalog configuration: /.well-known/aqua-catalog.json (publishable/anon key only).

read (22)

Always allowed. Only reads the workspace or the public catalog cache.

discover_applications, doctor, get_application_details, hub_find_similar_questions, hub_get_acceptance_stats, hub_get_heat_scores, hub_get_program_by_slug, hub_get_program_detail, hub_get_program_questions, hub_get_program_rankings, hub_get_program_themes, hub_get_question_significance, hub_get_universal_questions, hub_search_programs, inspect_extracted_questions, locate_workspace, match_canonical_questions, prepare_packet, read_review_status, refresh_catalog, search_answer_bank, verify_packet

private_write (15)

Stages private records in the user's local workspace (drafts, imports, evidence). Refused in --read-only mode. Never approves anything.

add_question, assemble_application, attach_evidence, create_draft_version, import_history, import_local_application, link_answer, link_history, mark_question, prepare_catalog_candidate, present_review_decisions, record_observed_submission, request_evidence, sync_from_vault_export, update_question

human_consent (1)

Acts only after the human confirms in the MCP client UI (elicitation). Without that capability it returns requires_human with the exact command for the user to run.

init_workspace

human_only (5)

Never acts. Returns requires_human with the steps the user takes in the AQUA browser app (approve, sign, freeze/export, submit, attest).

approve_answer, attest_submission, export_packet, sign_packet, submit_catalog_candidate

The machine-readable manifest is at /.well-known/mcp. Source: aqua-companion/.

Appfeeder browser extension

Appfeeder source is preserved, but its hosted capture and matching endpoints refuse private-content operations while local-first is active. The extension capture workflow is deferred; a JWT does not override those privacy guards. Its legacy paths include /api/answers/capture and /api/match-question. Source is in the repository under appfeeder/.

Error handling

Many API errors use a ProblemDetails shape (RFC 9457) with machine-readable error codes, human-readable title and detail, and a resolution hint suggesting the next step. Local-first refusals may instead return a compact JSON response with local_first: true.

{
  "error": "Unauthorized",
  "title": "Authentication required",
  "status": 401,
  "detail": "A valid Supabase session cookie or Bearer JWT is required.",
  "resolution": "Sign in at /login or include Authorization: Bearer <JWT>"
}

Agent integration

For agent guidance including when-to-use, how-to-use, limitations, and Markdown content negotiation, see llms.txt. The step-by-step agent path is the agent guide. The MCP manifest at /.well-known/mcp describes the tool surface in machine-readable form.

Repository

Full source code is available at github.com/SunrisesIllNeverSee/application-hub. The agent companion is in aqua-companion/, the Next.js app is in app/, and the Appfeeder extension is in appfeeder/.