Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
READ

get_import_batch

Fetches one brief import with its words and every suggestion Heimdall drafted from it, each with its decision so far.

Read one brief import by its id, the import_batch_id argument: the batch with its status and counts, the brief's words, and suggestions, each with its kind, title, payload, confidence, rationale, the span of the brief it came from, its status (pending, accepted, edited, merged, rejected or dismissed), the record it created when accepted and the existing record it may duplicate. Poll it after start_brief_import until the status is ready or failed.

Deciding a suggestion is the person's call, on the Brief Import page or through decide_suggestion on their word. A staff token with import:view is needed; an unknown or out-of-scope id is RESOURCE_NOT_FOUND.

Requires ability

import:view

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same actions as

GET/v1/council/{session}GET/v1/imports/{batch}GET/v1/imports/{batch}/suggestions

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Annotations

Read-only

It reads and never changes anything.

Arguments

import_batch_id*string

UUID of the brief import.

What it returns

{  "data": {    "id": "f2a3b4c5-d6e7-4f8a-8b9c-0d1e2f3a4b5c",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "source": "pasted_text",    "status": "ready",    "title": "Laundry shop brief",    "excerpt": "An informational website for a laundry shop with order placement, tracking, payment and appointment scheduling…",    "text": "An informational website for a laundry shop with order placement, tracking, payment and appointment scheduling. Customers choose services…",    "suggestion_count": 23,    "pending_count": 21,    "provider": "anthropic",    "model": "claude-sonnet-5-5",    "usage_id": "a3b4c5d6-e7f8-4a9b-8c0d-1e2f3a4b5c6d",    "failure_reason": null,    "created_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",    "creator_name": "Bea Analyst",    "started_at": "2026-10-28T11:20:05+00:00",    "finished_at": "2026-10-28T11:21:40+00:00",    "created_at": "2026-10-28T11:20:00+00:00",    "updated_at": "2026-10-28T11:21:40+00:00",    "suggestions": [      {        "id": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e",        "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",        "batch_id": "f2a3b4c5-d6e7-4f8a-8b9c-0d1e2f3a4b5c",        "kind": "epic",        "position": 1,        "parent_id": null,        "title": "Order placement",        "payload": {          "title": "Order placement",          "goal": "A customer books a wash in under two minutes."        },        "confidence": 0.92,        "rationale": "The brief names ordering as the first thing the site must do.",        "source_quote": "customers place laundry orders online",        "source_span": { "start": 58, "end": 95 },        "voice": null,        "status": "pending",        "duplicate_type": null,        "duplicate_id": null,        "created_type": null,        "created_id": null,        "decided_by": null,        "decider_name": null,        "decided_at": null,        "created_at": "2026-10-28T11:21:40+00:00"      }    ]  }}

How it fails

RESOURCE_NOT_FOUND

unknown import_batch_id, or a batch outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry import:view.

TOKEN_MISSING_ABILITY

token lacks import:view.

Related

list_import_batchesevery reading of the project.decide_suggestiona row decided on the person's word.convene_councilthe council on the batch.Imports APIthe same record over REST.

How is this guide?

Last updated on