Briefs API Reference

The Briefs endpoints create and read a Master Investment Brief — the structured analysis mandate the rest of the pipeline runs on. Every call is authenticated with Authorization: Bearer <token> (an hfk_… key or a Firebase ID token). Every brief response carries a top-level disclosure object.

How do I create a brief?¶

Submit a free-form investment mandate to POST /api/v1/briefs. Requires the pipeline:write scope. The response is a BriefResponse with a session_id and a status.

bash

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

import requests

resp = requests.post(
    "https://investeam.io/api/v1/briefs",
    headers={"Authorization": "Bearer hfk_your_key_here"},
    json={"input": "Is NVDA a buy right now?"},
)
print(resp.json())

input is required, 1–20,000 characters. The status is one of rejected, needs_clarification / awaiting_answers, or completed. Treat the status enum as open — map an unrecognized value to a safe keep-polling state.

How do I answer clarification questions?¶

When a brief is needs_clarification, answer with POST /api/v1/briefs/{id}/answers (scope pipeline:write). Provide at least one answer; combine selected_options and a 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" \
  -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"},
    json={"answers": [{"question_id": "q1", "selected_options": ["growth"]}]},
)
print(resp.json()["status"])

The response is another needs_clarification round or a completed brief.

How do I poll a brief?¶

Fetch a session and its brief with GET /api/v1/briefs/{id} (scope pipeline:read) — for re-hydration or to poll to a terminal state.

bash

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

import requests

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

A 404 here is not_found (an unknown or foreign id), not not-ready — a brief that exists is always readable by its owner. For the poll routes that use 404 to mean "not ready yet", see the async submit → poll model.

How do I list my sessions?¶

GET /api/v1/sessions (scope pipeline:read) returns the calling principal's sessions, newest-first, as {"sessions": [{session_id, title, status, created_at}]}.

bash

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

import requests

resp = requests.get(
    "https://investeam.io/api/v1/sessions",
    headers={"Authorization": "Bearer hfk_your_key_here"},
)
print([s["session_id"] for s in resp.json()["sessions"]])

The disclosure obligation¶

Every AI-output-carrying response 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).

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