Retrieve a council session

curl https://api.example.test/v1/council/$SESSION_ID \  -H "Authorization: Bearer $TOKEN"

One sitting with its turns and every finding. Poll it while the status is queued, running or summarising; read the ranked findings first once it is ready.

Requires ability

import:view

The token must hold this ability, or the call is refused with 403.

MCP tools

get_council_session get_import_batch

Run the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted in the app under Account Settings, then API Tokens, sent as Authorization: Bearer zg_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team, and optionally to one project, at mint time.

In: header

Path Parameters

session*string

The session, bound by the middleware.

Formatuuid

Responses

200OKapplication/json

The session, with its turns and findings.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (a zg_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who registered a row answers FORBIDDEN with the same status, and says so in its own description. On this endpoint: FORBIDDEN: when the token is a client guest's, or the holder's role on the project does not carry import:view.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. On this endpoint: RESOURCE_NOT_FOUND: when the session is hidden from the token or missing.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/council/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "moment": "requirement_review",    "subject_type": "work-item",    "subject_id": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f",    "subject_title": "Apply a voucher at checkout",    "status": "ready",    "voices": [      "thor",      "loki"    ],    "round": 1,    "summary": "The story is sound; one criterion cannot be verified and the voucher code is personal data the record does not say how to keep.",    "ranked": [      {        "finding_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81",        "reason": "A tester is blocked until the limit is named."      }    ],    "disagreements": [],    "finding_count": 2,    "cost_micros": 12500,    "cost": "$0.0125",    "failure_reason": null,    "requested_by": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",    "requester_name": "Jane Doe",    "started_at": "2026-10-28T15:00:05+00:00",    "finished_at": "2026-10-28T15:03:00+00:00",    "created_at": "2026-10-28T15:00:00+00:00",    "turns": [],    "findings": [      {        "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81",        "session_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",        "turn_id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c03",        "voice": "thor",        "voice_name": "Thor",        "round": 1,        "position": 1,        "title": "The voucher criterion cannot be verified",        "claim": "The criterion \"the basket updates quickly\" names no limit, so a tester cannot pass or fail it.",        "evidence": "the basket updates quickly",        "suggestion": "Then the basket total updates within 1 second of the voucher being applied.",        "severity": "high",        "confidence": 0.85,        "kind": null,        "payload": null,        "status": "pending",        "suggestion_id": null,        "decided_by": null,        "decider_name": null,        "decided_at": null,        "created_at": "2026-10-28T15:01:10+00:00"      }    ]  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: Data;}export interface Data {  id: string;  project_id: string;  moment: string;  subject_type: string | null;  subject_id: string | null;  subject_title: string | null;  status: string;  voices: unknown[];  round: number;  phase: string;  summary: string | null;  plan: string | null;  ranked: Ranked[] | null;  disagreements: Disagreement[] | null;  finding_count: number;  cost_micros: number;  cost: string;  failure_reason: string | null;  requested_by: string | null;  requester_name: string | null;  started_at: string | null;  finished_at: string | null;  created_at: string | null;  turns: CouncilTurnResource[];  findings: CouncilFindingResource[];}export interface Ranked {  finding_id: string;  reason: string;}export interface Disagreement {  topic: string;  voices: string[];  positions: string;}export interface CouncilTurnResource {  id: string;  session_id: string;  voice: string;  voice_name: "Heimdall" | "Odin" | "Thor" | "Loki" | "Týr" | "Frigg" | "Baldur" | "Hel";  lens: "Moderator and front door" | "Architecture, design decisions and the data model" | "Testing, verification and defects" | "Security, abuse cases and data exposure" | "Requirement rigour, business rules and compliance" | "Planning, estimates, risks and capacity" | "Experience, accessibility and clarity" | "Incidents, post-mortems and past failures";  round: number;  kind: string;  status: string;  stance: string | null;  sources: unknown[] | null;  finding_count: number;  failure_reason: string | null;  started_at: string | null;  finished_at: string | null;}export interface CouncilFindingResource {  id: string;  session_id: string;  turn_id: string;  voice: string;  voice_name: "Heimdall" | "Odin" | "Thor" | "Loki" | "Týr" | "Frigg" | "Baldur" | "Hel";  round: number;  position: number;  title: string;  claim: string;  evidence: string | null;  suggestion: string | null;  severity: string;  confidence: number | null;  kind: string | null;  payload: unknown[] | null;  status: string;  suggestion_id: string | null;  decided_by: string | null;  decider_name: string | null;  decided_at: string | null;  created_at: string | null;}

Retrieve a council session

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Authorization

Path Parameters

Responses