bidsmith design-doc

Google requires a design document with every Basic-Access (and Standard-Access) developer-token application. The document explains what your tool does, which API endpoints it calls, how often, how it handles credentials, and how it satisfies the API’s Required Minimum Functionality (RMF). Reviewers read it carefully and reject submissions that are vague or obviously templated.

bidsmith design-doc generates that document for you. The parts that describe bidsmith itself — the module list, the API endpoints, the GAQL queries, the RMF mapping, the safety model — are pulled from bidsmith’s own source code, so the doc cannot drift from what the tool actually does. The parts that describe your team — applicant identity, why you need API access, who runs the tool — come from a TOML config you fill in.

Synopsis

bidsmith design-doc init   [--output design-doc.toml] [--force]
bidsmith design-doc render [--config design-doc.toml] [--output design-doc.html]

How to use it

1. Generate the config template.

   bidsmith design-doc init

   Writes design-doc.toml in the current directory. The file is heavily commented — every field is documented inline.

2. Fill in the placeholders. Open design-doc.toml in your editor. Every field marked <FILL IN …> needs a real value before the doc will render. The fields reviewers focus on:

   • core_business, primary_customers, value_exchange — Google’s compliance team asks for exactly these three things: the specific service or product your company provides, who buys it, and who pays whom for what. Answer concretely; a mission statement won’t pass.
   • why_this_tool_exists — three to five sentences describing your team’s specific use case. Reviewers reject submissions where this reads like stock copy. Be concrete: real campaign counts, real geographies, real review/audit needs.
   • who_uses_it_operators — how many people on your team run bidsmith, and against which manager account.

3. Render the HTML.

   bidsmith design-doc render

   Writes design-doc.html in the current directory. Validation runs first — if any required field is still empty or still contains a <FILL IN …> placeholder, render exits non-zero and tells you which.

4. Print to PDF. Open design-doc.html in your browser, then ⌘+P (or Ctrl+P) → Save as PDF. The template ships with print-tuned A4 CSS, so the output looks the same in every browser.

5. Attach the PDF to your Basic-Access application at Google Ads → Tools → API Center.

Flags

init

Flag	Description
-o, --output FILE	Output file path. Defaults to design-doc.toml.
--force	Overwrite an existing file. Default: refuse to clobber.

render

Flag	Description
-c, --config FILE	Input TOML config. Defaults to design-doc.toml.
-o, --output FILE	Output HTML file. Use - for stdout. Defaults to design-doc.html.

Environment variables

None for the config or template, but the rendered doc reflects bidsmith’s runtime API version. If you’ve set BIDSMITH_API_VERSION to override the default (v25), §5 of the rendered doc will show that override.

Exit codes

Code	Meaning
0	Successful render.
1	TOML parse error, missing required field, invalid manager account ID, template error, or file write error.

What gets auto-generated vs. user-supplied

Section of the doc	Source
§1 Summary (applicant references)	applicant_legal_entity from TOML
§2 Business model	core_business, primary_customers, value_exchange from TOML
§3 Why the API is essential	why_this_tool_exists from TOML; the capability → API service necessity table is auto-generated
§3 Operator population + internal-tool classification	who_uses_it_operators from TOML; the classification callout is universal
§4 How it works (plan/apply safety)	Universal — describes the read/write boundary and plan/apply contract
§5 Endpoints + API version	crate::api::client::api_version() and the actual HTTP call sites
§5 GAQL query list	crate::api::live_state::QUERIES — iterated, count derived
§5 Operation volume	Stock estimates; override volume_typical_per_day / volume_ceiling in TOML if your usage differs
§6 RMF mapping	Hardcoded — universal for any bidsmith user
§7 Authentication and data handling	Universal description of bidsmith’s OAuth flow and data handling
§9 Contact	contact_name, contact_email, company_url from TOML

Don't reuse stock paragraphs verbatim

The biggest reason API applications get rejected is that the design doc reads like a template. The core_business and why_this_tool_exists fields specifically must describe your company’s actual situation — what you sell, campaign counts, geographies, the workflow problem you’re solving. Reviewers will recognise generic copy on sight.

Re-rendering for a follow-up application

Check design-doc.toml into your bidsmith-config Git repo. If Google asks for a revised submission (e.g. after asking follow-up questions), edit the TOML, re-run bidsmith design-doc render, re-print the PDF.

When bidsmith adds or changes API surface (new GAQL queries, a version bump), the next render automatically reflects it — you don’t have to touch the TOML at all.

See also

• Apply for Basic API access — end-to-end walkthrough of the application process.
• Connect to Google Ads — what to do once your developer token is approved.