Committee API Reference

The committee endpoints convene an AI investment committee over a completed Master Investment Brief and let you follow its work. You convene, poll the orchestration for the committee plan, and poll the execution for status and findings. Every call is authenticated with Authorization: Bearer <token>, and every response on these paths carries a top-level disclosure object.

How do I convene a committee?¶

Submit a completed brief to POST /api/v1/orchestrations (scope pipeline:write). Pass the session_id and the Master Investment Brief object; the committee run starts and you get back the session and its status.

bash

curl -sS https://investeam.io/api/v1/orchestrations \
  -H "Authorization: Bearer hfk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f2c1e7a-convene-001" \
  -d '{"session_id": "SESSION_ID", "brief": {"...": "the Master Investment Brief JSON"}}'

import requests

resp = requests.post(
    "https://investeam.io/api/v1/orchestrations",
    headers={
        "Authorization": "Bearer hfk_your_key_here",
        "Idempotency-Key": "9f2c1e7a-convene-001",
    },
    json={"session_id": "SESSION_ID", "brief": {"...": "the brief JSON"}},
)
print(resp.status_code, resp.json())

session_id is required; brief is the Master Investment Brief object, passed through to the orchestrator, which validates it. Convening spends a full committee run — send the Idempotency-Key so a retry cannot fire a second one.

How do I poll the committee plan?¶

Fetch the persisted committee and its task plan with GET /api/v1/orchestrations/{id} (scope pipeline:read). A 404 here is not-ready — the plan is still in flight — so keep polling.

bash

curl -sS https://investeam.io/api/v1/orchestrations/SESSION_ID \
  -H "Authorization: Bearer hfk_your_key_here"

import requests

resp = requests.get(
    "https://investeam.io/api/v1/orchestrations/SESSION_ID",
    headers={"Authorization": "Bearer hfk_your_key_here"},
)
print(resp.status_code, resp.json())

The response carries the committee roster and the research tasks assigned to its members — the plan the execution runs.

How do I get committee execution status and findings?¶

Poll GET /api/v1/executions/{id} (scope pipeline:read) for the execution's status and any findings so far. The status is running, partial, completed, or failed — an open enum, so treat an unrecognized value as non-terminal and keep polling. A 404 is not-ready ("no execution yet").

bash

curl -sS https://investeam.io/api/v1/executions/SESSION_ID \
  -H "Authorization: Bearer hfk_your_key_here"

import requests

resp = requests.get(
    "https://investeam.io/api/v1/executions/SESSION_ID",
    headers={"Authorization": "Bearer hfk_your_key_here"},
)
print(resp.json().get("status"))

Poll every two to three seconds until the status is completed or failed. To watch the deliberation as it happens, stream the transcript in parallel — see the Transcript reference. For the final synthesized findings, fetch the Analysis.

The disclosure obligation¶

Every committee response carries a disclosure object. Output is AI-generated and may contain errors and is not investment advice; you must show this not-advice + AI-generated disclosure to your end users and must not strip the response disclosure field (see https://investeam.io/api-terms).

For the full error envelope and every status code, see the Error Reference. The aggregate schema lives in the public OpenAPI spec.