streaming
POST/public/v1/research
Billing Category — Focused Research or Broad Research
Executes a legal research query using a natural-language `query`. The AI agent automatically determines which content types to search, constructs a search plan, retrieves primary legal authority, and synthesizes a research response.
Event sequence
Order of NDJSON events for each response mode. Repeat indicator ↻ marks zero-or-more events.
(lens)
(text)
(text_and_lens)
Request body
application/jsonResponse events
Each line of the NDJSON stream is one of these typed events. Click a row to open the full schema in the inspector.
Examples
Paired cURL requests and live wire-format responses. Copy a block directly into your shell.
text_streamText mode streamapplication/x-ndjson
Requestbash
curl https://api.trustfoundry.ai/public/v1/research \ -X POST \ -H "X-API-Key: $TRUSTFOUNDRY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "What are the elements of a breach of fiduciary duty claim in Delaware?", "response_format": "text" }'
Responsendjson
{"type":"execution_started","execution_id":"abc-123"}
{"type":"task_started","execution_id":"abc-123","task_id":"t1","task_type":"legal_research"}
{"type":"task_progress","execution_id":"abc-123","task_id":"t1","upstream_event":{"type":"search_start"}}
{"type":"response_delta","execution_id":"abc-123","content":"## Elements of Breach of Fiduciary Duty\n\n"}
{"type":"response_delta","execution_id":"abc-123","content":"Under Delaware law, the elements are..."}
{"type":"task_completed","execution_id":"abc-123","task_id":"t1","task_type":"legal_research"}
{"type":"done","execution_id":"abc-123","status":"completed","usage":{"category":"focused_research","credits_used":1}}lens_streamLens mode streamapplication/x-ndjson
Requestbash
curl https://api.trustfoundry.ai/public/v1/research \ -X POST \ -H "X-API-Key: $TRUSTFOUNDRY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "What are the elements of a breach of fiduciary duty claim in Delaware?", "response_format": "lens" }'
Responsendjson
{"type":"execution_started","execution_id":"abc-123"}
{"type":"task_started","execution_id":"abc-123","task_id":"t1","task_type":"legal_research"}
{"type":"heartbeat","timestamp":"2026-06-13T18:30:00Z"}
{"type":"task_progress","execution_id":"abc-123","task_id":"t1","upstream_event":{"type":"search_start"}}
{"type":"task_completed","execution_id":"abc-123","task_id":"t1","task_type":"legal_research"}
{"type":"lens_ready","execution_id":"abc-123","lens":{"lens_type":"research_lens","generated_at":"2026-06-13T18:30:00Z","confidence":"high","assumptions":[],"gaps":[],"query":"...","issue_map":[],"authorities":[{"authority_id":"a1","citation":"Foo v. Bar","title":"Foo v. Bar","url":"https://example.test/foo","result_type":"case","jurisdiction":"DE"}],"relevant_legal_text":[]}}
{"type":"done","execution_id":"abc-123","status":"completed","usage":{"category":"focused_research","credits_used":1}}text_and_lens_streamtext_and_lens mode stream (co-emits streamed markdown and final lens)application/x-ndjson
Requestbash
curl https://api.trustfoundry.ai/public/v1/research \ -X POST \ -H "X-API-Key: $TRUSTFOUNDRY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "What are the elements of a breach of fiduciary duty claim in Delaware?", "response_format": "text" }'
Responsendjson
{"type":"execution_started","execution_id":"abc-123"}
{"type":"task_started","execution_id":"abc-123","task_id":"t1","task_type":"legal_research"}
{"type":"task_progress","execution_id":"abc-123","task_id":"t1","upstream_event":{"type":"search_start"}}
{"type":"response_delta","execution_id":"abc-123","content":"## Elements of Breach of Fiduciary Duty\n\n"}
{"type":"response_delta","execution_id":"abc-123","content":"Under Delaware law, the elements are..."}
{"type":"task_completed","execution_id":"abc-123","task_id":"t1","task_type":"legal_research"}
{"type":"lens_ready","execution_id":"abc-123","lens":{"lens_type":"research_lens","generated_at":"2026-06-13T18:30:00Z","confidence":"high","assumptions":[],"gaps":[],"query":"...","issue_map":[],"authorities":[{"authority_id":"a1","citation":"Foo v. Bar","title":"Foo v. Bar","url":"https://example.test/foo","result_type":"case","jurisdiction":"DE"}],"relevant_legal_text":[]}}
{"type":"done","execution_id":"abc-123","status":"completed","usage":{"category":"focused_research","credits_used":1}}