API reference

Nine operations. Each is POST https://api.datagoat.io/v1/<path> over REST and a tool of the same name over MCP (https://api.datagoat.io/mcp). The full schemas are in openapi.json, generated from the same definitions the server validates against.

Tool	REST	Does	Cost
`dg_ask`	`/v1/ask`	Answer yesno, score, choice and rank questions about cases, from a table or any shape. The one call.	one decision per answered case; a fit on a new record
`dg_add_dataset`	`/v1/add-dataset`	Store a table once (rows, CSV, a URL, or a presigned upload); append pieces	free
`dg_poll`	`/v1/poll`	Follow a pending ask to its answer	free
`dg_preflight`	`/v1/preflight`	Check a table before the first ask: grain, column values, fitness	free
`dg_report_outcomes`	`/v1/report-outcomes`	Record what really happened after you acted	free
`dg_drift`	`/v1/drift`	Compare a refit with the fit before it: keep, refit or abandon	free
`dg_verify`	`/v1/verify`	Check a Verdict is genuine. Needs no key.	free
`dg_describe`	`/v1/describe`	Question types, shapes, limits, prices, retention, and the samples. Needs no key.	free
`dg_delete_dataset`	`/v1/delete-dataset`	Delete a stored dataset now	free

POST /v1/agents/register with no credential returns a free test key for the samples.

Conventions

Auth: Authorization: Bearer dgk_live_… (or dgk_test_…, or an OAuth token).
Idempotency: send idempotency_key on dg_ask. A retry with the same key within 24 hours returns the first answer and never fits or bills twice; the same key with a different body is a
Pending: a first fit on a large record answers 202 with {"status": "pending", "task_id"}. Poll dg_poll; do not re-send the ask.
Errors: RFC 9457 problems, application/problem+json, with code, remedy, field and request_id. A refusal is not an error: it is an answer with state: "refused".
Determinism: the same record bytes and the same question give the same answer. Change one byte and the next ask fits again.
Retention: inline data is deleted when the call ends; stored datasets 24 hours after last use; answers after 24 hours. See Your data.
MCP tool hints: dg_ask, dg_poll, dg_preflight, dg_drift, dg_verify and dg_describe are read-only; dg_add_dataset and dg_report_outcomes write; dg_delete_dataset is destructive. dg_ask and dg_add_dataset are open-world because they can download a fetch_url.
Response size: an answer carries every case you asked about (up to 10,000) and every ranked case (up to top_k, at most 1,000). Over MCP, ask about the cases the conversation needs; bulk scoring belongs on REST.