Docsbook
Übersicht

Create goal

POST/api/v1/create_goal
Features

Define a goal — one thing you want a reader to do. Matched RETROACTIVELY against the history already recorded, so the numbers appear immediately rather than starting from today. Warnings come back in issues and are worth relaying to the owner verbatim. Set value_usd only if you can defend the number; leaving it empty keeps money figures switched off rather than showing an invented one.

Price — $0.00001 per call (twice what serving it costs us), charged to the workspace balance, the same as over MCP.

Also reachable by name at POST /api/v1/tools/create_goal.

Input6
Authorizationheaderrequired
Your API key, sent as Authorization: Bearer dbk_YOUR_API_KEY.Sent from your browser straight to the API — never to Docsbook, never stored.
keystring · body
Machine name, e.g. 'reached_pricing'. Lowercase and underscores; it is the handle funnels and these tools refer to the goal by. Never put a path, id or email in it.
kindstring · body
page = a pageview of a path. event = one of the events the docs emit (see get_analytics event names). section = a heading/anchor came into view — THIS is how a 'scrolled as far as pricing' goal works, and it needs no new tracking. outbound = a click leaving for a host (matched by host, so query strings do not matter). One of: page, event, section, outbound.
matchstring · body
What to match: a path for 'page', an event name for 'event', a heading anchor for 'section' (with or without the '#'), a host for 'outbound'.
match_pathstring · body
Optional scope — only count the goal on this page. Lets one event be two goals ('copied the quickstart snippet' vs 'copied the auth snippet').
labelstring · body
Human label for the dashboard. Defaults to the key.
value_usdnumber · body
What ONE completion is worth, in dollars. Omit unless defensible.
Output3
okboolean
Whether the tool itself succeeded. A tool that ran and refused — an exhausted balance, a plan restriction, a bad argument — answers 200 with ok: false: the call was made and billed, and that refusal is its answer.
resultobject
The tool's own JSON answer, already parsed — not a string to parse a second time.
Show child attributes3
workspace_idnumber
goalobject
issuesobject[]
Warnings worth relaying to the owner verbatim.
duration_msinteger
Server-side wall time for the call.
Limitations
  • Refused when it cannot ever fire (an event these docs do not emit) or when the value is 0 — a goal that never fires looks EXACTLY like a goal with 100% drop-off, and $0 reads as a measurement instead of an absent declaration.
Responses
200The tool ran. Read ok to see whether it succeeded.
401Missing or invalid API key.
Example input
curl -X POST 'https://docsbook.io/api/v1/create_goal' \
  -H 'Authorization: Bearer dbk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"page"}'
Example output
{
  "ok": true,
  "result": {
    "workspace_id": 0,
    "goal": {},
    "issues": []
  },
  "duration_ms": 0
}

Aktualisiert

War diese Seite hilfreich?