Agents API
v0.5.0Multi-agent runtime, working groups, threads, workflows, KGs, RAG.
229 operationsBase URL:
https://agents.yieldfabric.comHealth
Liveness / readiness.
Working Groups
Multi-human multi-agent collaboration scopes. Owns workflows, threads, KGs, documents, members, federation policies.
- getList working groups the caller belongs to
/working-groups - postCreate a new working group
/working-groups - getFetch a single working group
/working-groups/{id} - patchUpdate mutable working-group metadata
/working-groups/{id} - deleteArchive a working group (soft-delete)
/working-groups/{id} - getList an agent's working-group-scoped memory entries
/working-groups/{id}/agent_memory/{agent_id} - postWrite (upsert) a working-group-scoped agent memory entry
/working-groups/{id}/agent_memory/{agent_id} - deleteDelete one working-group-scoped agent memory entry
/working-groups/{id}/agent_memory/{agent_id}/{key} - postGet or create a private deal-composer thread
/working-groups/{id}/deal-composer-thread - postMerge KGs in a working group into a single canonical KG
/working-groups/{id}/merge-kgs - postRun a RAG query against the group's documents
/working-groups/{id}/query - postRAG query that fans out across federated groups
/working-groups/{id}/query/federated - postGet or create the caller's private "Solo Terminal" thread
/working-groups/{id}/solo-thread - getResolve (or create) the thread topic for a workflow / step
/working-groups/{id}/topics
Members
Group membership and roles.
Group Documents
Documents attached to a working group (used as RAG sources).
- getList documents owned by the working group
/working-groups/{id}/documents - patchUpdate a document's title or content (re-chunk if content changed)
/working-groups/{id}/documents/{docid} - deleteDelete a document and its derived substrate
/working-groups/{id}/documents/{docid} - getStream the document's bytes back to the caller
/working-groups/{id}/documents/{docid}/download
Audit
Audit-event timeline for a working group.
Federation
Cross-group RAG access grants.
Feedback
User feedback on agent outputs.
Workflows
YAML-defined multi-step workflows; create, start, stream, complete, approve, reject, reassign steps.
- postExecute an ad-hoc YAML-defined workflow
/workflow - getList workflows for a working group
/working-groups/{id}/workflows - postCreate a workflow from a DAG of steps
/working-groups/{id}/workflows - getFetch a workflow plus its current step rows
/working-groups/{id}/workflows/{wid} - postActivate a pending workflow
/working-groups/{id}/workflows/{wid}/start - postApprove an approval-gate step
/working-groups/{id}/workflows/{wid}/steps/{step_key}/approve - postMark a human / agent / notification step complete
/working-groups/{id}/workflows/{wid}/steps/{step_key}/complete - postExecute a payment / signature step (sign-then-op flow)
/working-groups/{id}/workflows/{wid}/steps/{step_key}/execute - postFail a workflow step with a reason
/working-groups/{id}/workflows/{wid}/steps/{step_key}/fail - postReassign a human-task step to another entity
/working-groups/{id}/workflows/{wid}/steps/{step_key}/reassign - postRegister a child pipeline as a requirement on the sender's account
/working-groups/{id}/workflows/{wid}/steps/{step_key}/register-child - postReject an approval-gate step
/working-groups/{id}/workflows/{wid}/steps/{step_key}/reject - postSign a step within a child pipeline
/working-groups/{id}/workflows/{wid}/steps/{step_key}/sign-child - getSSE stream of workflow step events
/working-groups/{id}/workflows/{wid}/stream - postCreate a workflow from a saved template
/working-groups/{id}/workflows/from-template
Workflow Templates
Reusable workflow definitions.
Threads
Conversation threads within a working group; messages, typing, weaver sub-threads.
- getList visible threads in the working group
/working-groups/{id}/threads - postCreate a new discussion thread
/working-groups/{id}/threads - getList messages in a thread (cursor-paginated, newest-first when older requested)
/working-groups/{id}/threads/{tid}/messages - postPost a human message to a thread
/working-groups/{id}/threads/{tid}/messages - postAdvance the caller's last-read cursor
/working-groups/{id}/threads/{tid}/read - postBroadcast that the caller is typing
/working-groups/{id}/threads/{tid}/typing - postOpen (or create) the caller's private Weaver subthread
/working-groups/{id}/threads/{tid}/weaver
Chat
Per-group chat session + SSE stream.
Intents
Agent-proposed actions awaiting user confirmation.
- getList financial intents proposed in the group
/working-groups/{id}/intents - getFetch a single financial intent
/working-groups/{id}/intents/{intent_id} - patchUpdate an intent's arguments before confirmation
/working-groups/{id}/intents/{intent_id} - getFull lifecycle audit trail for an intent
/working-groups/{id}/intents/{intent_id}/audit - postCancel a proposed or executing intent
/working-groups/{id}/intents/{intent_id}/cancel - postConfirm an intent and dispatch its execution
/working-groups/{id}/intents/{intent_id}/confirm - postRetry a failed intent (Failed → Staged)
/working-groups/{id}/intents/{intent_id}/retry
Pipeline Drafts
Scratch workflows being authored before submission.
- getList pipeline drafts (scratch workflows) for a working group
/working-groups/{id}/pipeline-drafts - postCreate or upsert a pipeline draft for a working-group thread
/working-groups/{id}/pipeline-drafts - getGet a single pipeline draft
/working-groups/{id}/pipeline-drafts/{draft_id} - patchPatch a pipeline draft's fields
/working-groups/{id}/pipeline-drafts/{draft_id} - postReject and cancel a pipeline draft
/working-groups/{id}/pipeline-drafts/{draft_id}/reject - postSubmit a draft as a reusable workflow template
/working-groups/{id}/pipeline-drafts/{draft_id}/submit
Agents
Agent definitions, versions, memory, studio (conversational authoring).
- getList agents visible to the caller (latest version of each)
/agents - postCreate a new agent or publish a new version
/agents - getGet the latest version of an agent's full spec
/agents/{id} - getList the agent's global memories (cross-KG, cross-group)
/agents/{id}/memory - postUpsert a global-scope memory entry for an agent
/agents/{id}/memory - deleteDelete a global-scope memory entry for an agent
/agents/{id}/memory/{key} - postCopy all memories from this agent to a target agent id
/agents/{id}/migrate_memory - getList the 10 most recent pipeline runs this agent participated in
/agents/{id}/runs - postSend a message to an agent in Studio mode and get its reply
/agents/{id}/studio/chat - getList Studio proposals raised by the agent (optionally filtered by status)
/agents/{id}/studio/proposals - postAccept a Studio proposal and dispatch its side effect
/agents/{id}/studio/proposals/{key}/apply - postReject a Studio proposal with a reason
/agents/{id}/studio/proposals/{key}/reject - postNudge the agent to emit improvement proposals
/agents/{id}/studio/request_proposal - getRetrieve the Studio conversation thread for an agent
/agents/{id}/studio/thread - getList all versions of an agent (newest first)
/agents/{id}/versions - deleteSoft-retire a specific version of an agent
/agents/{id}/versions/{version} - postDiscover active agents matching a free-text query
/agents/discover - postDry-run validation of an AgentSpec without persisting
/agents/validate - getList agents available inside a working group
/working-groups/{id}/agents - postCreate a persistent agent scoped to this working group
/working-groups/{id}/agents - getFetch a single persistent agent
/working-groups/{id}/agents/{aid} - patchUpdate an existing persistent agent
/working-groups/{id}/agents/{aid}
Pipelines
Unified transform framework — run, resume, rewind, compose, reason-over.
- getGet the persisted record for a pipeline run
/pipelines/{run_id} - postCancel an in-flight pipeline run
/pipelines/{run_id}/cancel - getServer-Sent Events stream of pipeline progress
/pipelines/{run_id}/events - postDeliver per-turn human input to a paused pipeline
/pipelines/{run_id}/input - getList agent invocations recorded for a pipeline run
/pipelines/{run_id}/invocations - getFetch the full prompt text for a single agent invocation
/pipelines/{run_id}/invocations/{invocation_id}/prompt - getFetch the raw LLM response text for a single agent invocation
/pipelines/{run_id}/invocations/{invocation_id}/response - postResume a paused, failed-orphaned, or apparently-stale running pipeline
/pipelines/{run_id}/resume - postBranch a new run from an earlier named step of an existing pipeline
/pipelines/{run_id}/rewind - postIngest a document (text, PDF, or URL) into a KG via file-extraction pipeline
/pipelines/ingest-document - postStart a named pipeline (file_extraction, reasoning, or extract_then_reason)
/pipelines/run
Knowledge Graphs
KG CRUD, chunks, lexicons, frames.
- getFetch a chunk in context for the provenance modal.
/chunks/{chunk_id} - postEdit a chunk's text and trigger re-extraction across cited KGs.
/chunks/{chunk_id} - getList knowledge graphs the caller can see.
/kgs - getLoad a knowledge graph snapshot for rendering.
/kgs/{id} - postSeed a zero-seed KG's lexicon from raw sample text.
/kgs/{id}/bootstrap - getLoad the composed KG over its lineage parent chain.
/kgs/{id}/composed - postRun Phase-B consolidation over the KG's untyped frame residue.
/kgs/{id}/consolidate - postInterpret a transcript into speech-act + mental frames on the KG.
/kgs/{id}/conversation/interpret - postRun end-to-end document extraction into the KG.
/kgs/{id}/extract - getList frames in a KG with optional kind/lifecycle filters.
/kgs/{id}/frames - getDrill-down view of a single frame and its slot edges.
/kgs/{id}/frames/{frame_id} - getCompute consensus state over SpeechAct frames targeting a frame.
/kgs/{id}/frames/{frame_id}/consensus - getRead the KG's persisted lexicon and metrics.
/kgs/{id}/lexicon - getReturn the parent chain metadata for a KG.
/kgs/{id}/lineage - postMerge a source KG's lexicon into a target KG and report conflicts.
/kgs/{id}/merge_into/{target_id} - postStart a reasoning pipeline whose lineage parent is the given KG.
/kgs/{id}/reason-over - getLatest pipeline run for a KG, with thread linkage.
/kgs/{id}/run - getAggregate frame counts plus lexicon health for the KG.
/kgs/{id}/summary - getList KG-scoped memory entries for an agent.
/kgs/{kg_id}/agent_memory/{agent_id} - postUpsert a KG-scoped memory entry for an agent.
/kgs/{kg_id}/agent_memory/{agent_id} - deleteDelete a single KG-scoped memory entry for an agent.
/kgs/{kg_id}/agent_memory/{agent_id}/{key} - getList agents that have produced invocations on a KG.
/kgs/{kg_id}/agents - getList every chunk linked to a KG, with citations attached.
/kgs/{kg_id}/chunks - postAppend a manual note as a new chunk on an existing KG.
/kgs/{kg_id}/chunks - getStitched document view — title plus chunks in position order.
/kgs/{kg_id}/documents/{doc_id}/stitched - postDelete document-layer frames that no longer have chunk provenance.
/kgs/{kg_id}/prune-orphans
Knowledge Documents
Document ingestion for KGs.
- getPaginated list of knowledge documents with optional filters.
/knowledge/documents - getFetch a single knowledge document by id.
/knowledge/documents/{id} - postAttach a knowledge document to a KG node as supporting evidence.
/knowledge/documents/{id}/link - postFetch an RSS feed and chunk articles into the KG's RAG index.
/knowledge/documents/fetch-news - getList documents linked to a specific KG node.
/knowledge/documents/for-node/{node_id} - postEnd-to-end RAG query — retrieve, rerank, generate.
/knowledge/documents/query - getEmbedding-based document similarity search.
/knowledge/documents/search
Notebook
Notebook surface for observations, entities, relationships.
- getList long-tail concept_type buckets discovered by extraction.
/api/notebook/concepts - getList entities under a long-tail concept_type bucket.
/api/notebook/concepts/{concept_type} - getList the observer's entities of a given kind.
/api/notebook/entities/{kind} - postCreate an entity of the given kind in the observer's notebook KG.
/api/notebook/entities/{kind} - getGet an entity + its rendered observation profile.
/api/notebook/entities/{kind}/{id} - patchPartial update of an entity's identity, tags, and properties.
/api/notebook/entities/{kind}/{id} - deleteArchive (soft-delete) an entity.
/api/notebook/entities/{kind}/{id} - getACH (Analysis of Competing Hypotheses) matrix for a hypothesis.
/api/notebook/entities/{kind}/{id}/ach - getList subthread messages for an entity's agent chat.
/api/notebook/entities/{kind}/{id}/chat - postPost a message to an entity's agent subthread.
/api/notebook/entities/{kind}/{id}/chat - patchWrite the classification slot on an entity frame.
/api/notebook/entities/{kind}/{id}/classification - getEvidence view for an RFI (accepted + pending `<doc> answers <rfi>` relations).
/api/notebook/entities/{kind}/{id}/evidence - postManually link a claim to a hypothesis as supports / contradicts.
/api/notebook/entities/{kind}/{id}/links - postAccept a pending `<doc> answers <rfi>` match (lifecycle pending_review → typed).
/api/notebook/entities/{kind}/{id}/matches/{relation_frame_id}/accept - postSoft-archive a pending `<doc> answers <rfi>` match.
/api/notebook/entities/{kind}/{id}/matches/{relation_frame_id}/reject - getCompose a deterministic tear-line memo draft for the hypothesis.
/api/notebook/entities/{kind}/{id}/memo - postPersist the deterministic memo draft as a SpeechAct on the hypothesis.
/api/notebook/entities/{kind}/{id}/memo - deleteDrop every observation on this entity.
/api/notebook/entities/{kind}/{id}/observations - deleteDelete a single observation from an entity's profile.
/api/notebook/entities/{kind}/{id}/observations/{frame_id} - patchStamp temporal validity (valid_from / valid_to) on a SpeechAct.
/api/notebook/entities/{kind}/{id}/observations/{frame_id}/validity - postPersist an inline suggestion card as a typed SpeechAct observation.
/api/notebook/entities/{kind}/{id}/observations/accept - postHeuristically extract object_label + org links on legacy observations.
/api/notebook/entities/{kind}/{id}/observations/backfill - postPromote a single PendingReview entity to Typed.
/api/notebook/entities/{kind}/{id}/promote - postReject a single PendingReview entity (record + soft-delete).
/api/notebook/entities/{kind}/{id}/reject - postManually link a document as evidence for an RFI.
/api/notebook/entities/{kind}/{id}/rfi-links - postLLM-score a hypothesis given its ACH matrix (emits a fresh SpeechAct).
/api/notebook/entities/{kind}/{id}/score - getList PendingReview entities of this kind, grouped by source document.
/api/notebook/entities/{kind}/pending - postBulk-promote PendingReview entities of a kind to Typed.
/api/notebook/entities/{kind}/pending/promote-all - postBulk-reject PendingReview entities scoped to a single document.
/api/notebook/entities/{kind}/pending/reject-all - postArchive entities whose labels fail the proper-noun heuristic.
/api/notebook/entities/{kind}/sweep-junk - getKind-agnostic entity lookup by frame_id.
/api/notebook/entities/by-frame-id/{id} - getDebug dump of every slot edge into or out of the entity.
/api/notebook/entities/by-frame-id/{id}/edges - getTyped-entity neighbours discovered by walking slot edges.
/api/notebook/entities/by-frame-id/{id}/neighbours - postFlip an entity's concept_type to a new bucket.
/api/notebook/entities/by-frame-id/{id}/reclassify - getEvery chunk + document the entity has provenance to.
/api/notebook/entities/by-frame-id/{id}/sources - getCached LLM-synthesised paragraph about the entity.
/api/notebook/entities/by-frame-id/{id}/summary - postForce-regenerate the entity summary regardless of cache state.
/api/notebook/entities/by-frame-id/{id}/summary - getPer-kind counts of PendingReview entities in the notebook.
/api/notebook/entities/pending/summary - getGet the observer's id + personal workspace + notebook KG ids.
/api/notebook/me - getList the observer's saved notes (most recent first).
/api/notebook/notes - postCreate a free-form prose note in the notebook.
/api/notebook/notes - patchEdit a note's prose, metadata, and pinned mentions.
/api/notebook/notes/{frame_id} - deletePermanently delete a note + its extracted SpeechActs.
/api/notebook/notes/{frame_id} - postRun the Weaver auto-matcher over one document against every open RFI.
/api/notebook/rfi-match/{document_frame_id} - getResolve (and lazy-mint) the notebook KG id for a team workspace.
/api/notebook/workspaces/{workspace_id}/notebook-kg
CRM
Contact/account/entity surface.
- getList the observer's contacts (CRM Person convenience wrapper).
/api/crm/contacts - postCreate a contact in the observer's notebook KG (CRM Person convenience wrapper).
/api/crm/contacts - getGet a contact + their rendered observation profile.
/api/crm/contacts/{id} - patchUpdate a contact's identity fields, tags, no_auto_link, or platform_entity_id.
/api/crm/contacts/{id} - deleteArchive (soft-delete) a contact.
/api/crm/contacts/{id} - getList messages in the contact's private agent-chat subthread.
/api/crm/contacts/{id}/chat - postPost a message to the contact's agent subthread and dispatch mentions.
/api/crm/contacts/{id}/chat - deleteDrop every observation on this contact.
/api/crm/contacts/{id}/observations - deleteDelete a single observation from a contact's profile.
/api/crm/contacts/{id}/observations/{frame_id} - postPersist an inline suggestion card as a typed SpeechAct observation on this contact.
/api/crm/contacts/{id}/observations/accept - postHeuristically extract object_label + org/contact links on legacy observations.
/api/crm/contacts/{id}/observations/backfill
Conversation
Conversation analysis (LLM-driven extraction).
Presence
Presence join/heartbeat/disconnect for live collaboration.
Tools & Skills
Tool and skill catalogs.
Domain
Domain extraction utilities.
Economies & Usage
Economy manifest catalog and usage metering.
- postForce-refresh the in-process asset catalog
/api/catalog/invalidate - getList active registered economies.
/api/economies - postRegister a new economy (or update an existing one by slug).
/api/economies - getGet one registered economy by id.
/api/economies/{id} - getRaw LLM-usage events with per-call provenance.
/api/usage/detail - getAggregated daily LLM-usage totals (call count, tokens, latency).
/api/usage/summary
Authoring
- postProse → LLM → YAML → import pipeline
/api/authoring/bootstrap - postStructural delta between two KGs
/api/authoring/diff - postApply a batch of FrameMutations to a draft KG
/api/authoring/draft/apply - postConversational schema authoring (LLM-driven mutation suggestions)
/api/authoring/elicit - getList bundled fork-able example manifests
/api/authoring/examples - postFork a bundled example into a fresh persistent KG
/api/authoring/examples/{id}/fork - postExport a schema-bearing KG as YAML
/api/authoring/export - postSchema graph view (nodes + edges) for visualization
/api/authoring/graph - postImport a YAML manifest into a fresh persistent KG
/api/authoring/import - getVerb + clause lexicon palette for the Ideator
/api/authoring/lexicon/{kg_id} - postRun composition against an arbitrary YAML manifest + sample chat
/api/authoring/playground/compose