Skip to main content

Dashlink API Documentation — Assessment & Completion Plan

Target: a complete, accurate, Mintlify-hosted API reference for Dashlink, structured and formatted like dub.co/docs. Sources of truth for this assessment:
  • Backend: dashlink_frappe_bench/dev-bench/apps/dashlink/dashlink/api/v1/
  • Edge: Dashlink Backend/dashlink-edge/
  • Docs repo: dashlink-api-docs/ (this repo)

1. Where things stand

1.1 The API surface is large and almost entirely undocumented

dashlink/api/v1/ contains 225 @frappe.whitelist() functions across ~45 modules (excluding tests). Not all belong in a public reference — many are dashboard-only, internal, or billing plumbing. Filtering to endpoints that (a) authenticate with an API key via resolve_request_principal() and (b) are safe and sensible for an external developer gives roughly 110 endpoints. Currently documented: 1 endpoint (POST /api/v1/shortlinks/create_shortlink in api-reference/openapi.json). That is roughly 1% coverage.

1.2 The docs repo is a lightly-customised Mintlify starter

918 lines of content across 18 MDX pages. The breakdown: Genuinely written (~440 lines, good quality, some factual errors): overview/introduction.mdx (107), overview/api-keys.mdx (116), overview/rate-limits.mdx (114), index.mdx (97). Nine-line stubs — frontmatter only, zero content: apis/analytics-api.mdx, apis/campaigns-api.mdx, apis/qr-codes-api.mdx, apis/tags-api.mdx, apis/users-api.mdx, apis/utm-templates-api.mdx, getting-started/introduction-links.mdx, getting-started/short-links.mdx, analytics/introduction-filtering-and-aggregation.mdx, branded-links/introduction.mdx, app-dynamic-links/introduction.mdx. (apis/links-api.mdx is 5 lines — frontmatter pointing at the one OpenAPI operation.) Untouched Mintlify boilerplate that must be deleted: essentials/* (6 files — Mintlify’s own authoring guide), api-reference/endpoint/{create,delete,get,webhook}.mdx (the starter’s plant-store example), development.mdx, quickstart.mdx, snippets/snippet-intro.mdx, images/hero-{dark,light}.png, images/checks-passed.png. Orphaned pages — written but not in docs.json navigation, so they are unreachable: everything under getting-started/, analytics/, branded-links/, app-dynamic-links/, ai-tools/, and all of api-reference/. docs.json still carries starter placeholders: support email [email protected], primary CTA pointing at dashboard.mintlify.com, anchors pointing at mintlify.com/docs and mintlify.com/blog, and socials set to x.com/mintlify, github.com/mintlify, linkedin.com/company/mintlify.

1.3 Published content that is factually wrong

These are live on the site today and should be corrected regardless of the wider plan. Rate limits by plan — every row is wrong. overview/rate-limits.mdx publishes Free 60, Plus 300, Growth 1,200, Pro 3,000. The actual values in dashlink/fixtures/plan.json are: The page also invents a “Pro” plan and omits Business and Scale. Rate limits are not per-organization. The page states three times that limits are org-level and shared across keys. api_key_rate_limiter.py keys the counter on rate_limit:api_key:{sha256(api_key)} — it is per API key. An organization with three keys gets three times the advertised throughput. Either the docs or the implementation needs to change; they currently contradict each other. X-RateLimit-Plan is undocumented. A fourth header is emitted on every key-authenticated response and is not mentioned. Retry-After on 429 is also undocumented. Base URL is probably wrong. Docs and docs.json both use https://dashlink.ai, which is the marketing site. The edge repo’s README maps api.dashlink.ai to the Frappe API and dashlink.ai to marketing. Needs confirmation against production site_config.json (see §2.1).

2. Blockers — resolve these before writing endpoint pages

Writing 110 endpoint pages on top of these unknowns will produce documentation that is wrong on day one. Each item below is either a product decision or a small backend change.

2.1 Confirm the production base URL

Docs say https://dashlink.ai; the evidence points to https://api.dashlink.ai. The only in-repo assertion is install.py, which defaults to https://stagingapi.dashlink.ai. Action: confirm against production site_config.json and fix docs.json api.baseUrl plus every code sample.

2.2 Decide the canonical URL form, and fix the module allowlist

Four URL shapes all work and none is marked canonical: The three REST forms are dispatched by the same handler and gated on a hardcoded list in dashlink/api/__init__.py (lines 133–152):
shortlinks_import, analytics_agent_api, and app_association are missing from that list — 13 endpoints that would otherwise be documented at /api/v1/... are reachable only at /api/method/.... Documenting two URL conventions in one reference is a bad outcome. Recommended: adopt https://api.dashlink.ai/api/v1/<module>/<method> as the single public form, add the three missing modules to the allowlist, and make the REST 404 return JSON rather than Werkzeug’s HTML page.

2.3 Verify which authentication transports actually work

get_api_key_from_request() accepts four: Authorization: Bearer, Authorization: ApiKey, X-API-Key, and ?api_key=. However Frappe’s own validate_auth() runs first and raises AuthenticationError when an Authorization header splits into two parts and the session is still Guest. Dashlink keys are not Frappe key/secret pairs, so both Authorization forms may 401 before Dashlink code runs. This was determined by reading frappe/auth.py, not by an live request. Action: curl staging with all four transports and record the results. This decides whether the authentication page can show Authorization: Bearer at all — and it is what most developers will reach for first.

2.4 Reconcile the API-key permission model

This is the hardest blocker because the doctype and the API disagree.
  • API Key Permission doctype offers 11 modules: shortlinks, qrcode, campaigns, analytics, domains, utm_templates, tags, teams, plans, search, organization.
  • api_keys.create_api_key / update_api_key accept only 4: shortlinks, app_dynamic_link, campaign, analytics.
  • Of those 4, app_dynamic_link and campaign are dead strings — no endpoint authorizes against them (the campaigns module uses campaigns, plural), so a grant for either silently denies every call.
  • api_keys.py sets flags.ignore_validate = True to write values the doctype rejects, with a comment about a migration that never completed.
  • validate_api_key_permission checks for permission_level: "all", but "all" is not a creatable value (valid_levels = ["none", "read", "write"]).
Net effect: restricted keys can only be created for 2 modules that actually work. A scopes table cannot be published until valid_modules is replaced with the doctype’s option list. Also document these two behaviours once fixed: update_api_key will not modify permission rows unless permission_type="restricted" is re-sent in the same call; and a self-scoped key’s acting organization follows the creator’s primary organization, so it can change.

2.5 Fix (do not document) the security findings

Surfaced while mapping the API. None should appear in public docs; several need a fix before the API is publicised at all.

2.6 Decide the response envelope contract

There is no create_success_response helper. Success is frappe.response["data"] = payload, which yields {"data": {...}}. But:
  • 22 endpoints return a value instead, so on /api/method/ they arrive under message and on /api/v1/ under data — the envelope depends on which URL you called.
  • 76 endpoints do both, and will emit data and message together if a non-error return path fires.
  • Errors have two shapes. create_error_response produces a bare {"error": {message, status_code, code, details?}} with the right HTTP status. But every frappe.throw() call site (all of api_keys.py, notifications.py, onboarding.py, much of auth.py and teams.py) produces Frappe’s native {"exc_type": ..., "_server_messages": ...} — and ValidationError maps to HTTP 417, not 422.
Recommended: add a create_success_response helper, normalise the 22 outliers, and convert frappe.throw call sites on public endpoints to create_error_response. If that is too large to do now, the reference must explicitly document both envelopes and the 417 — which is a poor developer experience and worth avoiding.

2.7 Normalise pagination and sorting

Three incompatible response shapes exist today: Sorting is also inconsistent: get_shortlinks takes lowercase sort_by (last_modified), while get_dynamic_links and search_shortlinks take title case (Last Modified). And most_clicked is accepted by validation but absent from every sort_field_map, so it silently sorts by title instead. Pick Shape A or C, align the outliers, settle on one casing, and either implement or remove most_clicked.

2.8 Deduplicate error codes

79 distinct error_code literals, with no central enum (constants.py holds only feature codes and CSV limits). Before publishing an error reference, collapse these duplicate pairs:
  • RATE_LIMIT_EXCEEDED vs RATE_LIMITED
  • FEATURE_ACCESS_DENIED vs FEATURE_NOT_AVAILABLE_IN_PLAN
  • NO_SUBSCRIPTION vs SUBSCRIPTION_REQUIRED
  • ORGANIZATION_REQUIRED (403) vs ORGANIZATION_NOT_FOUND (404) vs NO_ORGANIZATION (400) — same condition, three codes, three statuses
  • VALIDATION_ERROR maps to both 400 and 422 depending on call site
  • INVALID_OR_EXPIRED_INVITATION maps to both 400 and 404
Then move them into constants.py as an enum so the docs can be generated from it.

2.9 Remove the webhooks stub

There are no outbound customer-facing webhooks. No Webhook doctype, no event dispatcher, no HMAC signing, no delivery queue; zero occurrences of “webhook” in the edge repo. The only webhook is inbound from Dodo Payments for billing. Delete api-reference/endpoint/webhook.mdx and do not list webhooks as a feature. (If the product wants them — dub.co leads with them — that is a backend project, not a docs task.)

2.10 Decide how retention truncation is surfaced

Analytics queries are silently clamped to the plan’s retention window at the Tinybird transport layer. A Free-plan caller asking for date_from=2020-01-01 gets ~30 days back with no indication the window was moved. retention.clamp_notice() exists and returns {clamped, earliest_date, retention_months}, but no production endpoint calls it. Either surface it in analytics responses or document the silent truncation prominently.

3. Target information architecture

Modelled on dub.co: a narrative Documentation tab for concepts and guides, a generated API Reference tab for endpoints, and SDKs once clients exist.

Tab 1 — Documentation

Getting started introduction · quickstart · authentication · workspaces-and-organizations Links links/introduction · links/custom-domains · links/custom-back-halves · links/utm-and-tags · links/password-protection · links/link-expiration · links/dynamic-routing · links/destination-types (url, wifi, sms, call, email, vcard) · links/bulk-operations · links/csv-import QR codes qr-codes/introduction · qr-codes/styling · qr-codes/frames-and-logos · qr-codes/downloading App dynamic links (deep links) deep-links/introduction · deep-links/app-association (AASA / assetlinks) · deep-links/ios-android-behaviours Analytics analytics/introduction · analytics/dimensions · analytics/filtering · analytics/timeseries-vs-breakdowns · analytics/retention · analytics/exports · analytics/routing-and-password-analytics · analytics/ai-reports Campaigns campaigns/introduction · campaigns/channels Account account/plans-and-limits · account/members-and-roles · account/teams · account/api-keys AI tools ai-tools/cursor · ai-tools/claude-code · ai-tools/windsurf · ai-tools/mcp-server (existing pages; verify and wire into nav)

Tab 2 — API Reference

Introduction api-reference/introduction · api-reference/authentication · api-reference/rate-limits · api-reference/errors · api-reference/pagination · api-reference/versioning Resource groups (page count = endpoints, all generated from OpenAPI):

Formatting conventions to match dub.co

  • One page per operation, frontmatter-only, body generated from the spec: openapi: "POST /api/v1/shortlinks/create_shortlink".
  • <CardGroup> navigation blocks on every group index page.
  • <Tabs> for multi-language examples (cURL / TypeScript / Python / Go) — cURL only until SDKs exist.
  • <ParamField> / <ResponseField> driven by the spec, not hand-written.
  • <Note> / <Warning> / <Info> callouts for plan gating and caveats.
  • <Steps> for every multi-step guide (domain verification, CSV import, deep-link setup).
  • An llms.txt at the docs root so agents can index the whole reference, mirroring dub.co/llms.txt.
  • Playground enabled and pointed at production, with a real key pre-fill prompt.

4. Execution strategy: generate the spec, don’t hand-write it

Hand-authoring 109 endpoint pages guarantees drift — the single existing page is already drifting, and the rate-limits page proves that hand-maintained tables rot. dub.co generates its spec from typed schemas and pipes it into Mintlify. Dashlink should do the equivalent. Build scripts/generate_openapi.py in the backend repo that:
  1. Reads a curated manifest (api_manifest.yaml) listing which of the 225 whitelisted functions are public, their resource group, summary, and HTTP verb. The manifest is the human-controlled part; everything else is derived.
  2. Introspects each function for its signature, defaults, and required parameters via inspect.
  3. Parses docstrings for descriptions (and enforces their presence in CI).
  4. Emits shared components/schemas for the success envelope, the error envelope, pagination shapes A/C, and the rate-limit headers, so 109 operations share 6 definitions instead of repeating them.
  5. Emits securitySchemes from whatever §2.3 concludes.
  6. Writes api-reference/openapi.json in this repo.
Then add a CI check in the backend repo that fails when a new @frappe.whitelist() function appears without a manifest entry. That is what keeps coverage at 100% permanently rather than for one week. The create_shortlink endpoint takes multipart/form-data with no parameters in its Python signature — every field is read from frappe.local.request.form. Several others (create_dynamic_link_v2, update_shortlink_v2, edit_qr_code_v2, create_qr_code_v2, the upload endpoints) do the same. Introspection cannot see these, so the manifest needs an explicit field list for them. There are roughly 8 such endpoints.

5. Phased plan

Phase 0 — Unblock (backend, ~1 week)

Owner: backend. Nothing downstream is safe until this lands.
  1. Confirm production base URL (§2.1).
  2. Curl staging for all four auth transports; record results (§2.3).
  3. Decide canonical URL form; add shortlinks_import, analytics_agent_api, app_association to the REST allowlist; make REST 404s return JSON (§2.2).
  4. Fix valid_modules in api_keys.py to match the doctype; decide the fate of permission_level: "all" (§2.4).
  5. Land the security fixes in §2.5 — at minimum the path traversal, the SSRF, and the two cross-tenant reads.
  6. Decide the envelope contract (§2.6) and the pagination shape (§2.7).
  7. Move error codes into a constants.py enum, collapsing the duplicates (§2.8).
Exit criteria: a one-page decision record answering base URL, canonical path, supported auth transports, envelope shape, pagination shape.

Phase 1 — Spec foundation (~1 week)

  1. Write api_manifest.yaml classifying all 225 functions as public / dashboard-only / internal. Start from dashlink/api/v1/WHITELIST_CHECKLIST.md, which already inventories every function with line numbers.
  2. Build generate_openapi.py and the shared component schemas.
  3. Generate a first full openapi.json and validate it (npx @redocly/cli lint).
  4. Add the CI drift check.
Exit criteria: openapi.json contains all ~109 public operations and lints clean.

Phase 2 — Docs chassis (~3 days)

  1. Rewrite docs.json: real support email, real dashboard URL, real socials, correct api.baseUrl, two tabs, full nav tree.
  2. Delete essentials/*, api-reference/endpoint/*, development.mdx, snippets/, starter images.
  3. Fix the three factually-wrong things live today: rate limits table, per-key vs per-org wording, base URL.
  4. Write the six API-reference concept pages (introduction, authentication, rate limits, errors, pagination, versioning) against the Phase 0 decision record.
Exit criteria: navigation has no orphans, no Mintlify placeholder strings remain, concept pages are accurate.

Phase 3 — Endpoint coverage (~2 weeks)

Generate the 109 operation pages and hand-write each group’s index page. Priority order by developer value:
  1. Links (18) + QR Codes (10) — the core product
  2. Analytics (20) — the main differentiator; needs care around plan gating, the 21 dimensions, and retention
  3. Campaigns (11) + Tags (3) + UTM Templates (4)
  4. Domains (11) + App Association (2) — pair with the domain-verification and deep-link guides
  5. CSV Import (6) + Search (2)
  6. Organization (2) + Teams (6) + API Keys (6) + Plans (3)
  7. AI Reports & Agent (5) — last; the two streaming endpoints return SSE or JSON depending on cache state and need their own handling section
Exit criteria: every manifest-public endpoint has a page; every page’s example request has been executed against staging and its real response pasted in.

Phase 4 — Guides and concepts (~1.5 weeks)

Write the ~30 narrative pages in §3 Tab 1. These are what make docs feel like dub.co’s rather than a generated dump. Highest value first: Links introduction, Analytics introduction, Custom domains, CSV import, Deep links, Plans & limits.

Phase 5 — Polish (~1 week)

  1. llms.txt + per-page .md variants.
  2. MCP server page — note that no Dashlink MCP server exists yet; either build one or reframe the ai-tools/ pages around the docs MCP.
  3. Language tabs beyond cURL once an SDK exists (see §6).
  4. Changelog tab.
  5. Playground smoke test: execute every operation from the Mintlify playground against staging.
  6. Accessibility and mobile pass.
Total: roughly 6–7 weeks, with Phase 0 gating everything and Phase 3 parallelisable across two writers.
Not required for “100% covered”, but these are the gap between a complete reference and a reference developers enjoy: The single highest-leverage item is the TypeScript SDK, because the Phase 1 OpenAPI spec makes it nearly free (Speakeasy or openapi-typescript-codegen) and it unlocks the multi-language tabs that make dub.co’s reference feel complete.

7. Immediate next actions

  1. Fix the rate-limits page now — it is live and wrong on every row, and it invents a plan tier that does not exist. This is a 20-minute change and does not depend on anything else.
  2. Run the auth transport test against staging (§2.3). One curl loop; it unblocks the authentication page, the docs.json security scheme, and every code sample in the reference.
  3. Triage §2.5 with whoever owns security. files.serve and domains.is_domain_in_use should be fixed before the API is publicised, independent of documentation.
  4. Get the Phase 0 decision record written. Six answers — base URL, canonical path, auth transports, envelope, pagination shape, key-scope module list — unblock everything else.