API Quickstart

By the end of this page you will have created a Master Investment Brief and polled it to completion — a real session_id in hand. The whole pipeline is one pattern: submit → get an id → poll. Output is decision-support analysis, not investment advice.

How do I get an InvesTeam API key?¶

You authenticate every call with a programmatic API key of the form hfk_…, sent as a bearer token. A key is an application credential you issue and revoke yourself — it is unrelated to InvesTeam's keyless GCP infrastructure. You need the pipeline:write scope to create a brief and pipeline:read to poll it.

See Authentication & API Keys for how to issue, scope, rotate, and revoke keys.

How do I make my first InvesTeam API call?¶

Send a POST /api/v1/briefs with your key and a free-form investment question. The response carries a session_id and a status — that session_id is your first success.

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.status_code, resp.json())

The status is one of rejected (off-mandate — read the message), needs_clarification / awaiting_answers (answer, then re-poll), or completed (the brief is ready). Every brief response also carries a top-level disclosure object.

How do I poll for the result?¶

Fetch the session with GET /api/v1/briefs/{id} every two to three seconds until status is completed or rejected.

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"])

On the brief read, a 404 means the id is unknown or foreign (not_found) — a brief that exists is always readable by its owner. On the downstream committee polls a 404 means "not ready yet, keep polling". See the Briefs reference.

How do I answer a clarification?¶

If the status 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" \
  -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"])

What's next?¶

You have a completed brief. To run the analysis, convene a committee with POST /api/v1/orchestrations and poll its execution and findings — the full run is covered in the Briefs reference and the rest of Integrate. Prefer an AI client? See the MCP Quickstart.