Skip to main content
This is a planning map, not a strict OpenAPI replacement.

​
Primary Route Files

  • /server/routes/auth.ts
  • /server/routes/deals.ts
  • /server/routes/contacts.ts
  • /server/routes/tasks.ts
  • /server/routes/teams.ts
  • /server/routes/public.ts
  • /server/routes/screenshots.ts
  • /server/routes/shortener.ts
  • /server/routes/agent.ts
  • /server/routes/settings.ts
  • /server/routes/ai-schema.ts

​
Mounted Families

  • GET/POST/... /api/auth/*
  • GET/POST/... /api/deals/*
  • GET/POST/... /api/contacts/*
  • GET/POST/... /api/tasks/*
  • GET/POST/... /api/teams/*
  • GET /api/public/* (public-facing)
  • GET/POST /api/screenshots/* (auth protected)
  • GET/POST /api/shorten/* and GET /r/*
  • GET/POST/... /api/agent/* (provider-neutral MCP bridge)
  • GET/PUT /api/settings and GET /api/settings/agent-connection
  • GET /api/ai/schema|entities|actions

​
Agent Bridge Contract

/api/agent/* is the canonical backend surface for MCP-capable agents. It is shared by Claude Code, OpenAI/Codex or ChatGPT MCP clients, OpenClaw adapters, and future agent hosts.
  • GET /api/agent/schema returns the tool-family schema and approval tiers.
  • Login-link auth starts with POST /api/agent/auth/start; the user opens /agent/authorize/:requestId; the agent polls GET /api/agent/auth/status/:requestId?deviceCode=....
  • Tool calls authenticate with Authorization: Bearer <DEALDASH_AGENT_ACCESS_TOKEN> for login-link tokens or Authorization: Bearer <DEALDASH_AGENT_SERVICE_SECRET> for operator-managed adapters.
  • Login approval links prefer APP_ORIGIN; RENDER_EXTERNAL_URL and SHORT_LINK_DOMAIN are fallback origins only.
  • Agents without MCP installed may start login-link auth directly by posting to https://dealdash.neonoir.ai/api/agent/auth/start; normal setup does not require service secrets, default user IDs, or deployment provider keys.
  • Tool calls require x-dd-request-id. Operator-managed service-secret auth also requires x-dd-acting-user-id; x-dd-channel and x-dd-actor-id identify the adapter.
  • Sensitive writes require x-dd-approval-id.
  • Approval confirmation is restricted to trusted adapters with x-dd-approval-confirm-secret.
  • OpenClaw policy belongs in channel adapters; the backend remains provider-neutral.
Allowlisted V1 families are short links, screenshots, deals, payments, tasks, contacts, influencers, activity, suggestions, context, memory, and approvals. Admin/auth/team, runtime/filesystem, and bulk destructive tools are excluded.

​
Agent Context And Memory

These endpoints make existing DealDash data easier for MCP clients to find before they call narrower tools.
  • GET /api/agent/context/resources: Tier 0 read that returns MCP resource hints such as dealdash://context/search, dealdash://linkshot/view-logs, and dealdash://memory/active.
  • GET /api/agent/context/search: Tier 0 read across deals, screenshots, LinkShot view logs, short links, contacts, influencers, and active agent memory. Filters: q, scope, types, limit, and offset.
  • GET /api/agent/memory: Tier 0 read for human-visible account-scoped memories.
  • POST /api/agent/memory: Tier 1 write to create a durable memory after user approval.
  • PATCH /api/agent/memory/:id/archive: Tier 1 reversible write. Memory is archived, not hard-deleted.
Memory records live in agent_memories, are scoped by user_id, and include source fields, tags, confidence, actor/channel provenance, and status. This is the controlled memory layer. pgvector semantic search is the next upgrade after embedding generation and cost/retention rules are configured.

​
LinkShot Data Visibility

The authenticated /screenshots page uses the existing LinkShot data-writing contract and adds read-only review surfaces for screenshots, due view checks, and view logs.

​
Screenshots

GET /api/screenshots defaults to owned-only records. Optional query:
  • scope=mine-and-shared: include screenshots owned by the signed-in user plus screenshots shared through active team membership.
Shared screenshot rows include ownership context such as owner, sharer, team, and shared date when available. Existing screenshot mutation rules still apply: owned screenshots can use the current link/share/delete flows, while team-shared rows are read-only unless the current user owns the screenshot.

​
Due Views

GET /api/deals/due-views keeps its default extension-compatible response. Optional query:
  • scope=mine-and-shared: include owned deal videos plus authorized team-shared deal records.
  • includeLogs=true: attach recent parsed LinkShot view-log context.
  • includeScreenshots=true: attach authorized screenshot references and counts.
Team-shared deal logs only appear when the deal is shared through team entity sharing with deal sharing enabled.

​
View Logs

GET /api/deals/view-logs is a read-only endpoint for LinkShot view checks. Supported filters:
  • scope
  • dealId
  • videoId
  • from
  • to
  • q
  • limit
  • offset
Rows include checked date, total views, parsed per-platform values, missing platform labels, source URL, deal/promo context, owner/sharer context, and screenshot evidence. Screenshot previews are returned only when the current user owns the screenshot or has an explicit screenshot share; otherwise the row reports a redacted attachment reference. Screenshot upload endpoints accept base64 raster images as PNG, JPEG/JPG, WebP, GIF, AVIF, or BMP. The default binary image limit is 40MB, with a 64MB JSON body limit for base64 request headroom. SCREENSHOT_MAX_IMAGE_BYTES, DEALDASH_AGENT_MAX_IMAGE_BYTES, and API_JSON_BODY_LIMIT can raise or lower limits per deployment. SVG, HEIC, and TIFF should be converted by clients or messaging adapters before upload.

​
Agent Bridge

/api/agent/deals/view-logs exposes the same read-only data as a Tier 0 deals.view_logs operation for MCP-capable agents. Agent calls use either the login-link access token or an internal operator-managed service secret, and the backend applies the same user/team visibility rules as the website. See LinkShot Extension for the website quick view and DealDash Agent Bridge Plugin for MCP usage.

​
Agent Connection Settings

GET /api/settings/agent-connection is an authenticated, read-only Settings endpoint for Bring Your Own Agent setup. It returns safe MCP status, setup instructions, permission tiers, tool groups, future AI feature slots, and recent agent_tool_call logs scoped to the current user. The safe setup payload includes a human guide URL, the public DealDash Agent Kit repo URL, an agent-optimized docs URL, and the MCP command/config path. Public and browser-visible responses expose names and links only, never secret values. The endpoint returns env names and boolean configuration flags only. It must not expose service secret values, approval confirmation secret values, raw request payloads, image data, payment payloads, or cross-account logs.

​
Validation Rule

When changing any route family:
  1. run targeted integration tests
  2. run pnpm check
  3. update docs for endpoint behavior changes
  4. include risk note for auth/public exposure changes