API

Discovery and ops

Search

Results are claims plus the evidence behind them. Everyone sees the claim. An insight hit includes the claim body. The body is cut only past a page budget, and body_truncated says when that happened. It also includes one supporting quotation — the strongest citation that still counts as support and that this caller may read — with who said it, when the source occurred, and where it sits. A citation the verifier has already rejected is not offered as that quotation. support is verified or unverified. One quotation can cover only part of a multi-sentence claim.

citation_omitted explains a missing quotation: restricted means this person cannot read the source, unavailable means the access check failed and the quote was left out, and none means nothing eligible supports the claim. Fetch the insight when the body was cut, the quotation was omitted, or you need every citation.

The quote is only shown to a caller who can read the source it came from. That check is the workspace object the citation points at — a conversation, an evidence record, a file, or a project artifact — and a failed check leaves the quote out. If workspace cannot be reached, search still answers from the claims and says that the evidence half is missing. Insight quotations are left out in that case as well.

One list holds claims, quotes, and saved files. result_type says which a hit is — insight, evidence, or output. The kinds carry different fields, because they are different things:

Filters and the three times

since, until, and entity_id are optional.

• since and until are RFC 3339 instants, such as 2026-09-01T00:00:00Z. since is inclusive and until is exclusive. They apply to occurrence time. A bad value is a 400, and so is an until that is not after since.
• entity_id keeps claims that are connected to that entity in the graph, in either direction. It also keeps evidence written by that person, matched on the person's work email. For an entity that is not a person, or a person with no email on record, no evidence is kept. An unknown id is a 404.
• A hit with no known time never matches a time window. The service does not guess that an undated claim is recent.
• The filters are applied before the lists are fused, so a hit outside the window cannot take a position from one inside it. Evidence hits that a filter removes are counted in excluded_by_filter. Workspace is not asked to filter, so a narrow window over a busy topic can return fewer than limit.

A claim carries three times, and each means one thing:

Reindexing, re-embedding, or re-reading a source changes none of these. An old note that is indexed again today still has its old occurred_at, and still falls outside a recent window.

result_type used to be called kind, which shadowed a claim's own kind and left a reader unable to tell a decision from a hypothesis. Evidence search also reads all four of workspace's lists now — turns, project artifacts, records, and utterances — where it previously read the first two, so notes and meeting lines reach search for the first time.

Ordering is relevance first, then how far each claim is trusted. A claim several independent people have confirmed ranks above one nobody has corroborated; a stale, disputed, or still-unreviewed claim ranks below it. The adjustment is small by design — it separates two claims that both answer the question, and cannot lift a well-supported claim about something else over a precise answer.

Nothing is filtered out on trust. A disputed claim that answers the question still appears, carrying the state that says why it is doubted. Hiding it would leave the reader thinking nothing was ever said on the subject, which is worse than showing them the doubt. The context pack is the opposite case and does exclude stale and disputed claims, because an agent treats what it is given as true rather than reading a label.

Objections

This is the other half of the context pack. The pack gives an agent only live claims; this returns only claims that give someone a reason to think again: a disputed claim, a claim recorded as contradicting one near the plan, a decision that was replaced, an unanswered open question, or a reported problem. A claim near the plan that agrees with it is never returned, and an empty list is the usual answer.

A claim that stops being live loses its vectors, so meaning alone cannot find disputed or replaced claims. The endpoint searches by meaning, by keyword over published and superseded claims, and then one step out along contradicts links and supersession. Only embedding the plan calls a model. Quotes are returned only when audience is private, and only from sources the caller can read. In a shared conversation citation_omitted is shared_conversation, because the agent's reply is saved where other people will read it. The design and the reasons are in docs/intelligence/agent-desktop-objections.md↗.

Related claims

The panel is for the person, not the agent (ADR 0110). Only live claims are returned, and only claims the meaning search puts within a strict closeness cut-off; matching words reorder those claims but never add one. Claims already returned to the caller for the same conversation are left out, so most messages return nothing. Each claim carries the strongest quote the caller can read. people lists up to three active people quoted behind at least two of the claims, never the caller. When the message cannot be embedded the lists are empty and semantic_available is false. The cut-off is scored with the relatedeval command; see docs/intelligence/agent-desktop-related-claims.md↗.

Insights

A claim is opened on the evidence it quotes. handoff is work one person is giving to another. unblock is one short question keeping that work from moving. Both are read out of a meeting, note, or thread the same way an open_question is. A case does not create either one. commitment is a next step from a meeting summary. Only the promote_commitments job writes one; see Architecture.

Anyone can challenge a claim, on purpose. Letting people weaken a claim is cheap and stopping them is expensive. Asserting a new claim is the other way round.

A claim written by hand still needs a quote to point at. POST /v1/knowledge/insights without one is refused with its own error code rather than a generic validation error, because "you have to point at evidence" is different advice from "this field is the wrong shape".

The review queue

Most candidates never reach a person. Claims with solid quotes and more than one source publish automatically. Claims whose quotes did not hold up are rejected automatically. Anything nobody reviews before its deadline expires.

Company-wide signals

Duplicated effort means similar work being done by people who share no project. Similar work inside one team is just that team working, not a finding. Reporting it would teach people to ignore the alert.

Everything except the pulse reads from a summary built overnight. Working these out per request means scanning most of the knowledge base, which is a query of several seconds sitting inside a page load.

Areas

An area is a group of related decisions and facts. Most are found by a nightly clustering job; a reviewer can also create one by hand. How both kinds are built is covered under architecture.

The graph

A removed or dismissed office stops showing, and reading the same document again does not bring it back. Once the person holds no office at the company, their officer_of edge to it is deleted. | /v1/graph/subgraph | GET | What is around a starting point, up to a given number of hops | | /v1/graph/overview | GET | The most connected nodes in the whole graph, and the edges among them. limit is how many nodes, from 1 to 10,000, and defaults to 200. No starting point | | /v1/graph/area/{areaId} | GET | One area's part of the graph: its member insights (marked inArea), and with connected (the default) the nodes one edge away from them. Only edges that touch a member are returned. limit caps the members, from 1 to 2,000, default 500, nearest the centre first. 404 when the area does not exist |

People

Any signed-in caller can read the two lookups, and so can a service acting for a person (the service token plus X-Flow-On-Behalf-Of). People are company-wide, like claims. This service does not use Cedar. Its routes check that the caller is authenticated, and a reviewer role for the write routes.

The response is snake_case inside the usual data envelope:

{
  "person_id": "uuid",
  "name": "Sara Garner",
  "email": "[email protected]",
  "title": "Senior Engineer",
  "title_source": "directory",
  "effective_from": "2026-09-04T00:00:00Z",
  "manager": { "person_id": "uuid", "name": "AJ Nead", "email": "[email protected]", "title": "Product Manager" },
  "reports": [],
  "links": [{ "system": "login", "external_id": "[email protected]", "status": "accepted" }],
  "ambiguous": false
}

• An email that no one has is a 404.
• title_source is directory (an org import), user (the person corrected it), or inferred. effective_from is when the current title took effect. Earlier titles and managers are kept with their dates in the database but are not returned here.
• links lists the accounts a person is known by: slack, github, azure_devops, zoom, hr, and login (the work email). accepted means the link was confirmed, either exactly or by a reviewer. Only accepted links attribute activity to the person. review means a possible match is waiting for a reviewer. It is shown so a caller can see it exists, and nothing is attributed through it.
• ambiguous is true when the lookup cannot tell which person is meant: two people share the name, or a different person has a pending link for the same email. In that case the response has no title, no manager, and no reports. Treat it as "not known", not as "has no title".
• The roster is every person with a work email, a current title, or a place in the reporting structure. A name that only appeared in a transcript is not on it.

Titles and managers come from the org import. See Org import.

Each person on the roster and in the lookup also carries practices, the same tags the practices route returns. How tags are inferred is under Authority and practices.

Authority

Company model

See Company model for the layers and write rules.

For workspace

This is served from a cache. Ingest marks the cache out of date as the project moves on, and a job rebuilds it. Working it out on every request would put a vector search in front of every single agent reply.

Each insight carries a source: project when the project's own evidence produced it, related when it came from elsewhere in the corpus and merely resembles the project, fact when it came from something a platform admin settled about the business. Anything rendering these has to keep them apart, or a reader is told their project decided something another project decided.

The companyFacts section is compiled once for the whole company rather than per project, and served whether or not this project's own pack is rebuilding. A stale company section is not served, the same rule the project pack follows: its contents are known to be wrong, and a withdrawn fact in a prompt is worse than no facts in that prompt, because the citation makes it look checked.

Admin

Reviewer only. The scheduled enqueues Kestra posts to /internal/jobs/*, reached with a person's credential rather than the scheduler secret, plus the per-project and corpus-wide repairs that have no schedule. The batch worker still does the work, except where noted. The harness tool list_queue_errors reads the dead-letter list and the failing rows of the health table. See Operations.

Every admin path needs a reviewer, with one exception. The job reads (depth, health, dead) and the dead-job actions (both requeues and expire) also answer a service-token call made on behalf of an address in INTELLIGENCE_QUEUE_OPERATORS. That setting covers every Foundry agent mailbox, so an agent can read a dead job, and put it back once the cause is fixed, with list_queue_errors, requeue_queue_jobs, and expire_queue_job. Running a job and the other admin paths still need a reviewer.

Beyond the scheduled kinds, /v1/admin/jobs takes rebuild_packs, reclaim, compile_pack, compile_company_facts, backfill_artifacts, link_projects, relink_authorship, promote_commitments, and clear_all_derived. relink_authorship with an evidence_id relinks one workspace record. Without one, it queues a relink for every record workspace says a model wrote, so claims extracted from those records stop counting as a person's. promote_commitments with an evidence_id promotes one meeting's next steps. Without one, it queues that for every meeting with a ready summary, which catches up summaries written before intelligence read them. Running it again does not duplicate claims. reclaim runs inline, because a queue whose workers are stuck cannot repair itself through the queue. backfill_artifacts and compile_pack need a project_id; compile_company_facts takes none, because there is one company section for every project. See Operations for when each is the right one.

Enveloped All /v1/* JSON uses the Response envelopeResponse envelope: The template service wraps every JSON response in {header, payload}. A success payload is {data} (a record or a list) plus optional meta.pagination; accounting still returns bare bodies and RFC 9457 errors until the divergence is resolved., and every mutation is a CommandCommand: An HTTP POST that changes state, recorded with an Idempotency-Key so retries do not double-apply; not CQRS or a command bus.: POST, an Idempotency-KeyIdempotency-Key: A caller-supplied header, stable across retries, that lets command.Execute claim the operation once and replay the same response on duplicate requests., and a body of {data, why}.

Error codes worth handling

Not in the spec

/internal/jobs/* belongs to the scheduler. It is protected by a shared secret and left out of the OpenAPI document (ADR 0026). Those endpoints queue the work and return straight away. See Operations.

Investigation runs

GET /v1/discovery/investigation-runs lists the reading principal's scheduled discovery runs, newest first. It accepts pagination[page] and pagination[pageSize] (default 5, maximum 20). The response uses the standard envelope with payload.data and payload.meta.pagination. Source permissions are checked again; a run's diagnostic text is withheld if a consulted record is no longer readable.

Each run identifies its model, algorithm version, trigger window and state (running, complete, partial, or failed). Its report includes source counts, selection limits, model calls and token usage, search steps, and each considered pair's decision. An empty packet list alone does not establish that a successful investigation found nothing. The discovery page's Runs tab exposes this report; older sweeps did not record it.

Packet detail also returns challenge_search. When no opposing passage was found, this explains what was checked and what remains unknown. It is a search account, not an opposing quotation. Each passage includes utterance_seq when the source line has one. occurred_at is when that line was spoken. The packet's created_at and updated_at are properties of the investigation record.

Company questions

GET /v1/discovery/questions lists questions the daily job proposed. status filters the queue: proposed (the shortlist), needs_data, held, investigating, investigated, deferred, already_answered, or not_useful. A question is omitted entirely when the caller cannot read every record it cites. The title is not returned on its own.

GET /v1/discovery/questions/{id} returns the current version: why it was raised, why it matters, the passages, what would disprove it, the next step, the six reasons it was kept, and earlier review actions. Those reasons are sentences. There is no score. An already answered question includes answer, at most two sentences. Text that contains markup or table characters is omitted. A Slack reply is that text. A pointer at a note is the note's prose, when the caller can read the note. The list includes the same reply when it was written on the review.

assignee=me on the list returns questions assigned to the caller, in any status. assignee also takes a work email for any one person, and assignee_person_id takes a person's entity id instead (use one or the other). state=open lists every question still waiting for an answer. state=answered lists questions marked already answered, and each carries answered_at, the time it was last marked answered. A question closed as not useful is neither open nor answered. state combines with status and the assignee filters. The job sets assignee and assignee_name from the cited lines: the person who spoke the most of them and already has an email on the line. The status stays where it was. The Mine queue on the Questions tab is that list. Once a day the assignee also receives each open question as a Slack direct message. The message names the channel, meeting, or thread the question was drawn from. A reply in that thread marks the question already answered and saves the reply as a note. A message in the direct message does the same for the latest question there that is still open.

GET /v1/discovery/slack-replies counts that traffic for any signed-in caller. since and until are a half-open window and default to the last thirty days. One row per person: sent is questions posted in the window, replies are Slack answers that arrived in the window, and waiting is questions posted in the window that are still open. Counts only. GET /v1/discovery/slack-questions lists the questions for one person over the same window, including a question posted earlier when a Slack reply arrived in the window. A question the caller cannot fully read is omitted, including its title. The analytics page shows the counts on the Slack tab, and selecting a person lists those questions.

POST /v1/discovery/questions/{id}/review takes a command envelope. assign requires assignee (an email) and assignee_name. investigate freezes that version and queues question_investigate, which passes the question into the existing discovery sweep with origin generated. refine writes a new version and leaves a frozen version alone. already_answered requires answer_ref. not_useful requires a reason: duplicate, wrong_premise, low_value, or needs_data. revisit requires revisit_at.

The Questions tab on the discovery page is this queue. A generated investigation says so on the card. It is not a finding the sources volunteered, and it is not evidence for the question.

Attention briefs

GET /v1/attention/profiles lists active profiles the caller may see. A reviewer sees every profile. Anyone else sees a profile only when the recipient is their own email. The role label is not an access grant.

POST /v1/attention/profiles creates one. POST /v1/attention/profiles/{id}/versions confirms a new version. A version needs one to five priorities. Briefs already approved keep the profile version they were built from.

GET /v1/attention/briefs lists briefs, newest period first. GET /v1/attention/briefs/{id} returns the selected items, the short unchanged watchlist, and the candidates that were left out. An item is omitted, wording included, when the caller cannot read one of its sources. withheld counts those omissions. reading says which feeds were observed. A feed that was not read is named. "No significant changes" does not mean the whole company was covered.

POST /v1/attention/briefs/{id}/review with approve freezes the wording and prepares one email. It does not send. reject retires that draft so another can be written for the same day.

POST /v1/attention/briefs/{id}/deliver sends the prepared email. If a send was attempted and no receipt was stored, the route refuses another send. POST /v1/attention/briefs/{id}/delivery/reconcile records whether that attempt arrived. not_sent is what allows one later send.

POST /v1/attention/items/{id}/feedback records an explicit action: tell_me_more, already_handled, keep_watching, not_relevant, matters_more, or assign_follow_up. already_handled requires a resolution link or a note, and it keeps the issue. assign_follow_up creates a task on a workspace project the caller can edit. Opening an item does not resolve it.

The Attention tab on the discovery page is this queue.

GET /v1/discovery/packets accepts inquiry, entity, created_after, and updated_after in addition to status, lens, page, and limit. created_after and updated_after are exclusive RFC3339 instants. entity is a case-insensitive match against the title, consequence, scope, inquiry, speaker, or channel. Access is still checked before a card is counted or returned.