Docs
On this page
Last updated 2026-07-07 API version v1

Developer FAQ

Short, direct answers to the questions developers ask most about the InvesTeam API. Each links into the reference where you can go deeper.

Is the InvesTeam API investment advice?

No. The API returns decision-support analysis, not investment advice. The output is AI-generated and may contain errors; it is not a recommendation, solicitation, or offer, and it creates no advisory or fiduciary relationship. You and your users own every decision. See Capabilities & Limits.

Can InvesTeam execute trades or connect to a broker?

No. There is no execution surface and no brokerage connection anywhere in the platform. The API produces analysis and stops there; placing orders is always your own system's responsibility.

How do I get an API key?

You issue a programmatic hfk_… key as an interactively signed-in user; the plaintext is shown once, so capture it into a secret store immediately. A key carries scopes (pipeline:read, pipeline:write, pipeline:findings). See Authentication & API Keys.

What's the difference between the API and the MCP server?

The REST API is for your code to call over HTTP; the MCP server projects the same endpoints as tools for an AI agent to call. Same pipeline, same key, different integration shape. See API or MCP.

Why does a poll return 404?

On a downstream poll route (orchestration, execution, transcript, analysis) a 404 means "valid id, this stage hasn't produced output yet" — keep polling. The one exception is GET /api/v1/briefs/{id}, where a 404 is a genuine not_found. See the async model.

Why is my POST returning a session id instead of the result?

Because every submit is asynchronous. A POST returns a session_id and a status immediately, and you poll a matching read route for the result — a committee run takes minutes, so nothing blocks on it. See the async submit → poll model.

Do I need an idempotency key?

Yes — send an Idempotency-Key header on every submit so a retry cannot double-run. The same key with the same body returns the original result; the same key with a different body returns 409 conflict. See the async model.

How do I connect InvesTeam to Claude?

Add the InvesTeam MCP server to your client's config with your hfk_… key and prompt it to create a brief. See the MCP Quickstart.

How fast can I poll the transcript?

Every two to three seconds, advancing the after cursor forward only. Once the execution is terminal, do one final drain read and stop. See Rate Limits & Quotas and the Transcript reference.

What does retryable: true mean?

It means the failure is transient and a retry with back-off can succeed (upstream_error, internal_error, rate_limited). A retryable: false error (bad_request, unauthorized, forbidden, not_found, conflict) will not succeed unchanged — fix the request. See the Error Reference.

Is hfk_ the same as the internal service key?

No. An hfk_ key is an application credential for your integration that resolves to a principal, scopes, and tier at the public edge, and is never forwarded to an internal service. The internal service keys (X-API-Key) are a separate mechanism that authenticate the BFF to private services — not something you ever hold. See Authentication & API Keys.

Is the API available in languages other than English?

The developer docs and API reference are English-only. The product UI is bilingual (English + Hebrew), and the disclosure object's notice always carries both an English and a Hebrew string so you can show your users the correct language.

What happens when an endpoint is deprecated?

A deprecated endpoint returns Deprecation: true and Sunset: <date> headers for at least 90 days before removal, and is marked deprecated: true in the OpenAPI. See Versioning & Deprecation.

How do I list a user's past sessions?

GET /api/v1/sessions (scope pipeline:read) returns the calling principal's sessions, newest-first. See the Briefs reference.

Is there an OpenAPI spec I can generate a client from?

Yes — the aggregate spec is at https://investeam.io/api/v1/openapi.json, with Swagger UI at https://investeam.io/api/docs. See OpenAPI Specification.

What must I do with the disclosure object?

You must pass it through to your end users. 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). See Capabilities & Limits.