Amdahl Platform API

List sessions

Create a new session

Creates a substrate session for accumulating data across multiple API calls.

Delete a session

Explore available data

Discover schema columns, sample values, cluster availability, and KB inventory.

Execute SQL query

Run a SQL query against the BigQuery interactions table.

Search knowledge base

Hybrid semantic + keyword search over knowledge base documents.

Search conversation clusters

Semantic search over pre-computed ML conversation clusters.

Get Cluster Detail

Full detail for a single pre-computed conversation cluster: label, description, insight, statistical measures (JSD, size anomaly), full feature distribution, representative quotes, temporal snapshots, and entity signals. Use after `data.cluster_search` has surfaced a cluster_id worth drilling into. Quotes are real but the selection and grouping are ML-generated.

Ask SQL (natural language → SQL)

Use when a caller wants SQL but does not know the schema. Takes a plain-English question plus optional prior turns and returns a read-only SELECT against the `interactions` table with a one-sentence explanation. SELECT-only by construction (system prompt + post-validation reject DML/DDL). Stateless: pass last N turns in `priorTurns` for follow-ups like "break that down by company". Caller runs the SQL via data.query; this op only writes the query.

Upload Knowledge Base Document

Upload a document into the business knowledge bank (PDF/DOCX/PPTX/markdown). Use when adding an asset the KB should index. Accepts base64 file_content (Datalab Marker conversion) or raw markdown_content (straight to chunk + embed). Returns the new document id plus conversion + embedding status; files are async, so poll knowledge_base.get until ready. When appending a new version of a living document, also pass version_changes (per-section change notes) for the version-review UI.

Update Knowledge Base Document

Patch metadata on an existing knowledge bank document. Use when the user asks to rename a doc, retag a doc, archive or unarchive, edit the description or notes, or flip visibility between private and public. Accepts any subset of description, document_type, filename, user_notes, is_archived, visibility; the row content (chunks, embeddings, storage files) is immutable through this path. To change content, hard-delete and re-upload.

Delete Knowledge Base Document

Remove a knowledge bank document. Use when retiring stale content from the knowledge base. Default mode is a soft archive (sets is_archived=true) so the row, storage files, and embeddings remain intact and reversible. Pass hard_delete=true to permanently remove storage files, chunk embeddings, and the document row; hard delete requires the knowledge_base:delete scope in addition to knowledge_base:write.

Search Knowledge Base

Hybrid semantic + keyword search across knowledge bank chunks. Use when looking up qualitative evidence, precedent, or supporting quotes from ingested documents. Defaults to knowledge_bank source_type; pass source_types to widen into saved_research or content_creation documents, or document_ids to restrict to specific documents. Returns chunks with document titles, heading context, and a combined similarity score.

Chat With Knowledge Base

Ask a natural-language question against the knowledge bank and get a synthesized answer. Use when you need a composed answer drawing from multiple documents rather than raw chunks. Pass one document_id to chat with a single document; omit or pass several to chat across the bank. Streams status + source progress events; final payload contains the answer and cited sources when include_sources is true.

Star Knowledge Base Document

Pin a knowledge bank document as workspace canon. Read when reviewing reference material (messaging frameworks, brand pillars, market research) the agent should always cite. Knowledge bank docs come from file uploads with extracted summaries already populated; pinning them surfaces the pre-extracted summary into every copilot turn for free. Idempotent. Cap 20 across all canon items workspace-wide. Admin-only.

Unstar Knowledge Base Document

Remove a knowledge bank doc from workspace canon. Use when a previously authoritative reference (messaging deck, brand pillars) is now stale or replaced. The KB document itself stays intact — only the system-prompt pre-load is dropped. Idempotent. Admin-only.

List Knowledge Base Version Comments

List the Level 3 review threads on a living-doc version (:id, a knowledge_bank_documents id). Use when rendering the version-review panel: agent rationale comments anchored to changed blocks plus human replies, grouped into threads with a resolved flag, with the version’s persisted block anchors. Same per-document read ACL as the version diff; null when missing or cross-business.

Create Knowledge Base Version Comment

Add a review comment to a living-doc version. Use when a reviewer replies to the agent’s rationale or opens a new thread anchored to a changed block. Pass body (required); optionally block_id (the block the thread anchors to) and thread_root_id (when replying). versioning:write + editor, mirroring the human-gated promote write.

Resolve Knowledge Base Version Comment

Mark a living-doc review thread resolved (or reopen it with resolved=false). Use when a reviewer finishes acting on a thread. Operates on the thread root; passing a reply id resolves its root. versioning:write + editor, mirroring the human-gated promote write.

External Search (fused market + tenant research)

Use when answering market / competitive / industry / topic-positioning questions. Returns a divergence_map flagging where market chatter (web+news+reddit+twitter) disagrees with the tenant's own customer voice (interactions) — the unique signal vs vanilla web search. Actions: search (free-text), enrich_company (domain/name + LinkedIn+Crunchbase), enrich_person (linkedin_url/email/name), enrich_topic (topic). Tenant-aware query rewrite runs first.

Verify Social Connection

Resolve a social handle to its live account plus most recent post, or a typed reason it couldn't be confirmed (not_found / no_posts / private / provider_error). Use when a tenant is hooking up a profile for social tracking and you must confirm the handle points at the right account before anything is saved. Read-only probe against the channel provider; writes nothing.

List Social Connections

Return every tracked social account (social connection) for the tenant, newest first, excluding ones that have been disconnected. Use when the user wants to see which profiles are currently hooked up for social tracking, or before connecting a new one to check what's already there. Read-only; touches nothing.

Connect Social Account

Save an already-verified social account as a tracked social connection for the tenant. Use when the user has confirmed the right profile (typically right after verify_connection) and wants it tracked going forward. Dedup is automatic: re-connecting an account that is already tracked returns an already_connected marker with the existing id instead of creating a duplicate. Persists one first-party data_sources row.

Get Social Connection

Fetch a single tracked social account (social connection) by its id for the tenant. Use when you already have a connection id and need its current details — handle, display name, follower snapshot, status, last sync time. Returns one connection or a not-found error. Read-only; scoped to the calling tenant.

Update Social Connection

Update a tracked social account (social connection) in place: set or clear its nickname, pause or resume tracking, and/or set the per-connection lookback window (how far back posts are snapshotted). Use when the user wants to rename a connection, toggle whether it syncs, or change its history window. Identify the connection by its id; only the fields you pass are changed. Returns the updated connection, or a not-found error if it is not in the tenant.

Disconnect Social Account

Stop tracking a social account by removing its social connection (soft delete: the row is kept for audit but no longer synced or listed). Use when the user wants to untrack a profile they previously connected. The raw metrics history is owned by amdahl-data and is not purged here.

Refresh Social Connection Metrics

Kick off a background metrics refresh for one tracked social account: ask amdahl-data to sync its source now and return immediately with a syncing acknowledgement (it does not wait). Call when the user wants fresh numbers on demand. Identify the connection by its id; poll the connection until is_syncing clears. Ingestion is owned by amdahl-data, not an in-app fetch.

List Social Post Metrics

Read the latest engagement snapshot per post for one tracked social account: likes, reposts, replies, quotes, bookmarks, and views, newest post first, capped at 25. Read when rendering a connection’s social view or answering how its recent posts are doing. Identify the connection by its id; returns the metrics plus the sync state, or null when the connection is not in the tenant.

Get Social Metric Trend

Read a bucketed metric trend for one tracked social account: the follower series over time (scope=connection, default) or a single post's engagement trajectory (scope=post + post_id). Read when rendering an over-time chart or answering how a metric moved. One series per channel metric; tune the window_days + granularity (hour/day/week). Returns null when the connection is not in the tenant; empty series when nothing is captured yet.

Get Social Connection Summary

Read aggregate stats for one tracked social account: current followers + growth over the window (both null when the channel does not expose followers — LinkedIn personal profiles do not via the current actor), total engagement, post count, top post, and last sync. Read when rendering the summary header or answering how an account is doing. Identify by id; tune window_days for the growth figures. Returns null when the connection is not in the tenant.

Get Social Portfolio Summary

Read aggregate stats across every active tracked account in the tenant: total followers + growth (null when no in-scope connection reports followers — LinkedIn personal profiles do not via the current actor), total engagement, post count, the best post across all accounts, and last sync. Read when rendering the connectors index header or answering how the whole portfolio is doing. No id — rolls up the tenant. Tune window_days for the growth figures.

List Social Channel Capabilities

Read the per-channel capability map: for each supported social channel (X / Twitter, LinkedIn), which entities (post / profile) it reports on and which metric keys + labels + formats each carries. Read when rendering metric toggles, legends, or column headers so the UI stays descriptor-driven and a new channel needs no front-end change. No id - it is the static, tenant-agnostic capability catalog.

List Tracked Subjects

Read every tracked subject for the tenant, newest first - the people and orgs being followed, each with the social handles grouped under it. Read when showing who is tracked, or before creating / linking to check what already exists. Filter by relationship (internal / external). A subject with no handles yet returns an empty handles list.

Create Tracked Subject

Create a tracked subject - a person or org you follow - that groups one or more social handles under one identity. Use when the user wants to start tracking someone (mark external) or register their own / a teammate's presence (mark internal). External subjects cannot have a member_user_id; an internal one may name a workspace member or be brand-owned. Link handles to it afterward.

Get Tracked Subject

Read a single tracked subject by id for the tenant, with the social handles grouped under it. Read when you have a subject id and need its details - relationship tag, the member it represents, its linked handles. Returns one subject or null when it is not in the tenant. Scoped to the calling tenant.

Update Tracked Subject

Patch a tracked subject - rename it, retag internal/external, set or clear the workspace member it represents, edit notes or the CRM link. Use when subject details change. Only the fields you pass are touched. Rejects a change that would leave an external subject owning a member, or a member who is not in this workspace. A non-existent id is a clean not-found.

Delete Tracked Subject

Delete a tracked subject by id. Use when the user wants to stop tracking a person/org as a grouped identity. The social connections grouped under it are kept - they just become ungrouped (their handle data and metrics history are untouched). A non-existent or cross-tenant id is a clean not-found.

Link Handle to Subject

Group a tracked social connection under a subject by linking it - e.g. attach a person's X account to the subject that already holds their LinkedIn. Use when consolidating multiple handles for one person/org under a single tracked identity. Both must be in the tenant and the connection must be a live social handle. Missing either side is a clean not-found.

Unlink Handle from Subject

Ungroup a social connection from its subject by clearing the link - the reverse of linking a handle. Use when a handle was grouped under the wrong subject, or to detach it. The connection itself is kept (handle data and metrics untouched); it just stops belonging to any subject. A non-existent or non-social connection id is a clean not-found.

Get Tracked Subject Summary

Read aggregate stats across every social handle grouped under a tracked subject: total followers (null when no handle reports a count), total engagement, post count, a per-channel breakdown, and last sync. Read when answering how a tracked person/org is doing across all their accounts at once. Identify by subject id; tune window_days. Returns null when the subject is not in the tenant; a zeroed summary when it has no handles.

List Connector Catalog

Read the catalog of integrations a workspace can hook up - CRM, calls, comms, docs, support, and social - with each entry's connect flow, ownership, and the data streams it brings in. Read when rendering the "add a connection" picker or answering which providers are supported. Describes what CAN be connected, not what is already connected. Optional kind / category filters narrow the menu.

List Established Connections

Read every integration a workspace has actually established, newest first, merging first-party data sources and tracked social accounts into one normalized list with a uniform status, scope, and last-synced field. Read when rendering the connections inventory or answering which integrations are live for the tenant. This is the established-instances view, distinct from the catalog of available providers.

Connect an Integration

Establish a new integration for a workspace, routing on the connector type: collect an API key, kick off an OAuth redirect, or track a social handle. Use when a user picks a provider from the catalog and wants it connected. Returns the created connection, or an OAuth authorize URL to redirect to. Creates and stores the connection without starting a sync.