Pipeline Walkthrough

This page runs the whole InvesTeam pipeline once, end to end, over HTTP: a free-form question becomes a Master Investment Brief, a committee convenes and deliberates, and you read the final analysis. Every stage is the same submit → get an id → poll pattern, and one session_id threads the entire run. Output is decision-support analysis, not investment advice.

How does the InvesTeam analysis pipeline work end to end?¶

You create a brief, poll it to completed (answering clarifications if asked), convene a committee over it, poll the execution while streaming the transcript, and finally fetch the synthesized analysis. All nine steps below share one session_id, returned from the first call. Send an Idempotency-Key on every submit so a retry cannot double-run.

text

POST /api/v1/briefs                → session_id + status
  poll GET /api/v1/briefs/{id}       until completed | rejected
    (if needs_clarification) POST /api/v1/briefs/{id}/answers → re-poll
  POST /api/v1/orchestrations        → convene the committee
  poll GET /api/v1/orchestrations/{id}  for the committee + task plan
  poll GET /api/v1/executions/{id}      until completed | failed
    stream GET /api/v1/executions/{id}/transcript?after=<seq>
  poll GET /api/v1/analyses/{id}        for the final analysis

Step 1 — Create a brief¶

Submit a free-form investment question to POST /api/v1/briefs with the pipeline:write scope. You get back a session_id and a status — capture the session_id; it threads the rest of the run.

bash

curl -sS https://investeam.io/api/v1/briefs \
  -H "Authorization: Bearer hfk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f2c1e7a-brief-001" \
  -d '{"input": "Is NVDA a buy right now?"}'

import requests

headers = {"Authorization": "Bearer hfk_your_key_here"}
resp = requests.post(
    "https://investeam.io/api/v1/briefs",
    headers={**headers, "Idempotency-Key": "9f2c1e7a-brief-001"},
    json={"input": "Is NVDA a buy right now?"},
)
session_id = resp.json()["session_id"]
print(session_id, resp.json()["status"])

The status is one of rejected (off-mandate — read the message), needs_clarification / awaiting_answers (answer, then re-poll), or completed.

Step 2 — Poll the brief, and answer clarifications if asked¶

Poll GET /api/v1/briefs/{id} every two to three seconds. If the brief is needs_clarification, submit answers to POST /api/v1/briefs/{id}/answers and re-poll to completed. Combine selected options and a free-text custom answer freely.

bash

curl -sS https://investeam.io/api/v1/briefs/SESSION_ID/answers \
  -H "Authorization: Bearer hfk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f2c1e7a-answers-001" \
  -d '{"answers": [{"question_id": "q1", "selected_options": ["growth"], "custom_answer": "5-year horizon"}]}'

import requests

resp = requests.post(
    "https://investeam.io/api/v1/briefs/SESSION_ID/answers",
    headers={
        "Authorization": "Bearer hfk_your_key_here",
        "Idempotency-Key": "9f2c1e7a-answers-001",
    },
    json={"answers": [{"question_id": "q1", "selected_options": ["growth"]}]},
)
print(resp.json()["status"])

Keep it to one clarification round for a first run. A 404 on the brief read is not_found, not not-ready — see the async model.

Step 3 — Convene a committee¶

With a completed brief, convene a committee over it with POST /api/v1/orchestrations (scope pipeline:write). Pass the session_id and the Master Investment Brief object; the response starts the committee run.

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.json()["status"])

Convening spends a full committee run. Inspect the completed brief before you convene, and keep the Idempotency-Key so a retry cannot fire a second committee.

Step 4 — Poll the orchestration for the committee plan¶

Poll GET /api/v1/orchestrations/{id} (scope pipeline:read) for the committee roster and its task plan. A 404 here is not-ready — 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())

Step 5 — Poll the execution and stream the transcript¶

Poll GET /api/v1/executions/{id} for the execution's status and its findings as they land — running, partial, completed, or failed. In parallel, stream the deliberation with GET /api/v1/executions/{id}/transcript?after=<seq>, advancing the cursor with each read.

bash

curl -sS "https://investeam.io/api/v1/executions/SESSION_ID/transcript?after=0" \
  -H "Authorization: Bearer hfk_your_key_here"

import requests

after = 0
resp = requests.get(
    f"https://investeam.io/api/v1/executions/SESSION_ID/transcript?after={after}",
    headers={"Authorization": "Bearer hfk_your_key_here"},
)
body = resp.json()
after = body["latest_seq"]  # feed this back as the next `after`
print(len(body["entries"]), "new turns; cursor now", after)

See the Transcript reference for the cursor model and the drain-then-stop rule. Once the execution is terminal, do one final transcript read, then stop polling.

Step 6 — Fetch the final analysis¶

When the committee completes, fetch the synthesized, red-teamed analysis with GET /api/v1/analyses/{id} — the premium object, gated behind the pipeline:findings scope. A 404 is not-ready; keep polling.

bash

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

import requests

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

The disclosure obligation¶

Every response in this run that carries AI-generated output includes 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).

Where next?¶

You have run the pipeline end to end. Dig into each stage in the Briefs, Committee, Transcript, and Analysis references, and generate a client from the OpenAPI spec. For failures, see the Error Reference.