Data API

An agent-friendly guide for asking the Company Brain questions over connected sources, shared memory, and the Ontology Graph, with streamed reasoning, citations, charts, and confidence.

The Data API is the feature that lets an agent actually use your data. Most agents can be handed a document or a credential; very few can reason across everything a company knows. The Data API closes that gap: it is a single entry point that connects an agent to all of your data at once: your connected sources, your shared memory, and the Ontology Graph that ties them together. It turns a plain-language question into a grounded answer.

Agent instruction

If you are an AI agent implementing, modifying, or documenting this integration, re-read this page from the current docs first and treat it as the source of truth. Do not rely on cached instructions or prior conversations when this page differs.

Agent integration guide#

Use the Data API when the user asks a company-specific factual question, wants analysis over connected sources, needs citations, or asks for a number that should come from company data rather than the model's memory.

Agent moment	What to do
Before answering a data question	Call `POST /brain/ask`. Do not guess from model knowledge when the answer should come from company sources.
While the answer streams	Capture reasoning events, sources, charts, and partial results so the user interface or agent transcript can show progress.
When presenting the result	Return the final answer with citations, confidence, and any charts the API produced. Make uncertainty visible.
After durable work	If the result creates a decision, summary, or useful future context, write that back through the Memory API.

Minimal agent loop#

Load the latest version of this page before implementing or updating a Data API integration.
Convert the user's request into one clear plain-language query, preserving scope, filters, and requested output format.
Call POST /brain/ask and stream the response events until the final answer arrives.
Show or return the answer with sources, charts, and confidence. Do not strip citations.
Record durable conclusions or follow-up decisions to shared memory when future agents should remember them.

Agent pattern

const stream = await parcle.brain.ask({
  query: userRequest,
  context: { project, user, thread },
  output: { includeSources: true, includeCharts: true }
});

for await (const event of stream) {
  if (event.type === "step") showProgress(event.message);
  if (event.type === "source") collectCitation(event.source);
  if (event.type === "final") return event.answer;
}

ℹ

Note

One connection, all your data. An agent doesn't integrate with each warehouse, document store, and tool separately. It talks to the Data API, and the Data API reaches everything on its behalf, within the access the agent has been granted.

http

Authorization: Bearer <COMPANY_API_KEY>

ℹ

Info

The endpoints and payloads below are illustrative of the target design, not a wire contract. Every request is authenticated with company credentials and scoped to the data the calling agent is permitted to see.

Ask a question#

Send a question in plain language. That is all an agent has to do.

POST /brain/ask

{ "query": "What was last quarter's revenue by region?" }

The response streams as the agent works, so you can show reasoning progress in real time, then ends with the complete grounded answer:

Reasoning steps

As the brain plans and runs the work, it emits a series of visible steps, including "found the revenue concept," "pulled the relevant data," and "aggregated by region," so a UI can show progress live.

Sources

It declares the data it reads as it goes, so every fact in the answer is traceable.

Final answer

It returns one complete answer with everything needed to present and trust it.

Final answer

{
  "answer": "Last quarter, revenue was $4.2M in the East, $3.1M in the West, and $1.8M in Central.",
  "sources": ["sales records"],
  "charts": ["revenue-by-region"],
  "confidence": 0.82
}

answer: the natural-language answer shown to the agent or person.
sources: the citations the answer is grounded in.
charts: optional charts or visual breakdowns the brain produced.
confidence: how strongly the answer is supported by your data.

One entry point to everything#

Behind that single call, the Data API spans all of your data so the agent doesn't have to:

🗄️Connected sources

Warehouses, document stores, and SaaS tools connected through connectors.

🧠Shared memory

What your agents have learned and recorded, in the company's shared memory.

🗂️Ontology Graph

The semantic map that lets a plain-English question reach the right data.

Inspect and refine the brain#

Beyond asking questions, an agent or a data team can inspect the Ontology Graph the answers are built on and refine it: correct a definition, add a synonym, or adjust a relationship. Changes take effect immediately and improve every subsequent answer, for every agent. Refinements are reversible, so the meaning of your data can be tuned without ever risking the underlying facts. See the Ontology Graph.

History & audit#

Every question and its grounded answer is stored, so you can review past threads, continue them, or audit exactly how an answer was derived and what data it touched. See SSO & Audit.

⚙️Related: Team Sync→

Manage the fleet of agents that connect to the brain.