Authenticate with Datapoint AI.

Opens your browser to sign in with Google and set up your account. Your API key is saved locally and never shared.

Upload local media files (images, audio, video) and return dp:// references.

Use this BEFORE plan_survey / create_survey whenever the user wants a survey over local files — annotators cannot reach file:// paths or local disk, and the server rejects non-dp:// / non-https:// URLs.

After uploading, pass the returned dp:// refs verbatim in the plan_survey description so the generated plan references the uploaded media. Example:

refs = upload_media(["/tmp/a.png", "/tmp/b.png"])
# → dp://media/abc123.png and dp://media/def456.png
plan_survey(
    description="Compare design A (dp://media/abc123.png) against "
                "design B (dp://media/def456.png). Target: UX designers.",
    max_responses=10,
)

Already-hosted public https:// URLs do NOT need uploading — you can reference them directly in the description.

Args: file_paths: List of absolute local paths to media files.

Plan a survey from a natural language description.

Describe what you want to learn and from whom. The Datapoint AI service will design an effective survey structure for you.

MEDIA: If the survey compares/rates media (images, audio, video), first call upload_media on any local files to get dp:// refs, then mention those refs (or public https:// URLs) directly in this description so the planner can wire them into the datapoints. Example:

description = (
    "Compare two logo designs for memorability: "
    "A = dp://media/abc123.png, B = dp://media/def456.png. "
    "Target: general software developers."
)

Without explicit refs in the description, the planner will produce placeholder or invented URLs that will fail at create_survey.

After this returns, present the summary and cost to the user and wait for explicit confirmation before calling create_survey. Never chain these two calls — create_survey spends money and dispatches real work.

Args: description: What you want to survey, in plain language. Include the target audience, what you're comparing/rating, any screening criteria — including who should answer (e.g. respondents in specific countries, excluding VPN/bot traffic, balanced regional mix) — and, for media surveys, the dp:// or https:// URLs to use. max_responses: Number of human responses per datapoint (default 10). More = higher confidence but higher cost.

Create a survey from a plan generated by plan_survey.

⚠ Only call this after the user has explicitly confirmed the plan summary and cost from plan_survey. This reserves credits immediately and dispatches paid human annotation work — there is no draft or staging state, and it cannot be undone.

Pass the plan dict as returned by plan_survey. You may edit it first if anything is off — this is a regular Python dict.

Supports both standalone plans and chain plans (with a top-level steps array alongside datapoints). For chain plans, the backend dispatches each step of each datapoint as a linked task; the full sequence is served together, in order, to one annotator per response.

MEDIA VALIDATION: every media entry must use either:

• a dp://media/… reference returned by upload_media, or

• a public https:// URL the annotator's browser can reach.

Media lives at datapoints[*].media (shared across steps) OR datapoints[*].media_per_step["0"], ["1"], ... (one entry per step when steps need different media shapes). The two are mutually exclusive per datapoint.

Local paths, file:// URLs, and private/auth-gated URLs will be rejected or served broken to annotators. If the plan came back with wrong refs (e.g. the planner invented a URL because the description didn't supply one), fix the refs before calling this:

# shared media
plan["datapoints"][0]["media"]["candidates"][0]["url"] = "dp://media/real.png"
# per-step media (chain)
plan["datapoints"][0]["media_per_step"]["1"]["subject"][0]["url"] = "dp://media/real.mp3"

Args: plan: The survey plan dict (typically from plan_survey). Contains name, summary, datapoints, and either task_type + instruction (standalone) or a steps array (chain).

Check the status, progress, and results of a survey.

Args: job_id: The job ID returned by create_survey.

List all your surveys (active and recent).

Pause task serving for an active survey.

In-flight responses keep arriving; new tasks stop being served. The backend rejects with 400 if the survey is completed, failed, or already paused — the message will say which.

Args: job_id: The job ID returned by create_survey.

Resume task serving for a paused survey.

Backend rejects with 400 if the survey is not paused.

Args: job_id: The job ID returned by create_survey.

Permanently cancel a survey and settle its reserved credits.

⚠ Cancellation is irreversible. Once cancelled, the survey stops serving new tasks, any in-flight responses still complete, and all unused reserved credits are returned to the balance. Already-consumed credit (for responses already collected) is NOT refunded — the response is shown in the result so the user knows the final cost.

Before calling, show the user the survey id and confirm they want to cancel. Prefer pause_survey when the user just wants to stop temporarily.

Backend rejects with 400 if the survey is already in a terminal state (completed, failed, or cancelled) — the message will say which.

Args: job_id: The job ID returned by create_survey.

Re-queue failed datapoints on a survey.

Each retried datapoint reserves credit again, the same way the original submission did — only call this when the failures are worth recovering.

Args: job_id: The job ID returned by create_survey. datapoint_indices: Specific failed indices to retry. Omit to retry every failed datapoint in the survey.

Get the raw per-annotator responses for a survey.

check_survey returns aggregated results (consensus, votes, mean/median, ranks). Use this tool when you want to see individual responses from each annotator — useful for spotting outliers, seeing the spread of opinion, or understanding disagreement.

The default view excludes answered rows from chains the annotator abandoned mid-flow or that are still in progress, matching what counts toward your survey's response total. Set the include flags to surface them.

Args: job_id: The job ID returned by create_survey. page: Page number (default 1). per_page: Responses per page (default 100, max 200). include_abandoned: Include answered rows from abandoned chains. include_in_progress: Include answered rows from in-flight chains.

Check your Datapoint AI account balance.

Open a checkout link to purchase Datapoint AI credits.

Returns a hosted checkout URL. The user completes payment in their browser; credits land on their account once payment confirms.

Args: product_id: Optional product identifier. Omit to use the default credit bundle configured on the server.