Analysis API Reference

The analysis endpoint returns the final, red-teamed synthesis of the committee's work — the last artifact in the pipeline. Poll GET /api/v1/analyses/{id} once the committee completes. Reading it requires the pipeline:findings scope. The response carries a top-level disclosure object.

How do I fetch the final analysis?¶

Poll GET /api/v1/analyses/{id} with a key that carries the pipeline:findings scope. A 404 is not-ready ("no analysis yet") — keep polling every two to three seconds until the synthesis payload returns.

bash

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

import time
import requests

url = "https://investeam.io/api/v1/analyses/SESSION_ID"
headers = {"Authorization": "Bearer hfk_your_key_here"}

while True:
    resp = requests.get(url, headers=headers)
    if resp.status_code == 200:
        break
    if resp.status_code == 404:
        time.sleep(2.5)
        continue
    resp.raise_for_status()
print(resp.json())

The analysis is available once the committee's execution reaches completed. It is the synthesized reading of the committee's findings — decision-support analysis, not a directive to act.

Why do I get a 403 on the analysis?¶

A 403 forbidden means your key lacks the pipeline:findings scope. The final analysis is the premium object, so a read+write key with only pipeline:read can poll execution status but not read it. Add pipeline:findings to the key — see Authentication & API Keys.

The disclosure obligation¶

The analysis 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.