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 sayhttps://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 Permissiondoctype offers 11 modules:shortlinks, qrcode, campaigns, analytics, domains, utm_templates, tags, teams, plans, search, organization.api_keys.create_api_key/update_api_keyaccept only 4:shortlinks, app_dynamic_link, campaign, analytics.- Of those 4,
app_dynamic_linkandcampaignare dead strings — no endpoint authorizes against them (the campaigns module usescampaigns, plural), so a grant for either silently denies every call. api_keys.pysetsflags.ignore_validate = Trueto write values the doctype rejects, with a comment about a migration that never completed.validate_api_key_permissionchecks forpermission_level: "all", but"all"is not a creatable value (valid_levels = ["none", "read", "write"]).
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 nocreate_success_response helper. Success is frappe.response["data"] = payload, which yields {"data": {...}}. But:
- 22 endpoints
returna value instead, so on/api/method/they arrive undermessageand on/api/v1/underdata— the envelope depends on which URL you called. - 76 endpoints do both, and will emit
dataandmessagetogether if a non-error return path fires. - Errors have two shapes.
create_error_responseproduces a bare{"error": {message, status_code, code, details?}}with the right HTTP status. But everyfrappe.throw()call site (all ofapi_keys.py,notifications.py,onboarding.py, much ofauth.pyandteams.py) produces Frappe’s native{"exc_type": ..., "_server_messages": ...}— andValidationErrormaps to HTTP 417, not 422.
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 distincterror_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_EXCEEDEDvsRATE_LIMITEDFEATURE_ACCESS_DENIEDvsFEATURE_NOT_AVAILABLE_IN_PLANNO_SUBSCRIPTIONvsSUBSCRIPTION_REQUIREDORGANIZATION_REQUIRED(403) vsORGANIZATION_NOT_FOUND(404) vsNO_ORGANIZATION(400) — same condition, three codes, three statusesVALIDATION_ERRORmaps to both 400 and 422 depending on call siteINVALID_OR_EXPIRED_INVITATIONmaps to both 400 and 404
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. NoWebhook 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 fordate_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 startedintroduction · 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
Introductionapi-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.txtat the docs root so agents can index the whole reference, mirroringdub.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. Buildscripts/generate_openapi.py in the backend repo that:
- 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. - Introspects each function for its signature, defaults, and required parameters via
inspect. - Parses docstrings for descriptions (and enforces their presence in CI).
- Emits shared
components/schemasfor 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. - Emits
securitySchemesfrom whatever §2.3 concludes. - Writes
api-reference/openapi.jsonin this repo.
@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.- Confirm production base URL (§2.1).
- Curl staging for all four auth transports; record results (§2.3).
- Decide canonical URL form; add
shortlinks_import,analytics_agent_api,app_associationto the REST allowlist; make REST 404s return JSON (§2.2). - Fix
valid_modulesinapi_keys.pyto match the doctype; decide the fate ofpermission_level: "all"(§2.4). - Land the security fixes in §2.5 — at minimum the path traversal, the SSRF, and the two cross-tenant reads.
- Decide the envelope contract (§2.6) and the pagination shape (§2.7).
- Move error codes into a
constants.pyenum, collapsing the duplicates (§2.8).
Phase 1 — Spec foundation (~1 week)
- Write
api_manifest.yamlclassifying all 225 functions as public / dashboard-only / internal. Start fromdashlink/api/v1/WHITELIST_CHECKLIST.md, which already inventories every function with line numbers. - Build
generate_openapi.pyand the shared component schemas. - Generate a first full
openapi.jsonand validate it (npx @redocly/cli lint). - Add the CI drift check.
openapi.json contains all ~109 public operations and lints clean.
Phase 2 — Docs chassis (~3 days)
- Rewrite
docs.json: real support email, real dashboard URL, real socials, correctapi.baseUrl, two tabs, full nav tree. - Delete
essentials/*,api-reference/endpoint/*,development.mdx,snippets/, starter images. - Fix the three factually-wrong things live today: rate limits table, per-key vs per-org wording, base URL.
- Write the six API-reference concept pages (introduction, authentication, rate limits, errors, pagination, versioning) against the Phase 0 decision record.
Phase 3 — Endpoint coverage (~2 weeks)
Generate the 109 operation pages and hand-write each group’s index page. Priority order by developer value:- Links (18) + QR Codes (10) — the core product
- Analytics (20) — the main differentiator; needs care around plan gating, the 21 dimensions, and retention
- Campaigns (11) + Tags (3) + UTM Templates (4)
- Domains (11) + App Association (2) — pair with the domain-verification and deep-link guides
- CSV Import (6) + Search (2)
- Organization (2) + Teams (6) + API Keys (6) + Plans (3)
- AI Reports & Agent (5) — last; the two streaming endpoints return SSE or JSON depending on cache state and need their own handling section
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)
llms.txt+ per-page.mdvariants.- MCP server page — note that no Dashlink MCP server exists yet; either build one or reframe the
ai-tools/pages around the docs MCP. - Language tabs beyond cURL once an SDK exists (see §6).
- Changelog tab.
- Playground smoke test: execute every operation from the Mintlify playground against staging.
- Accessibility and mobile pass.
6. Beyond parity — what dub.co has that Dashlink doesn’t
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
- 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.
- Run the auth transport test against staging (§2.3). One curl loop; it unblocks the authentication page, the
docs.jsonsecurity scheme, and every code sample in the reference. - Triage §2.5 with whoever owns security.
files.serveanddomains.is_domain_in_useshould be fixed before the API is publicised, independent of documentation. - 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.