Agent integrations

Audream provides a standard Agent Skill, a remote MCP server, a cross-platform CLI, and a REST/OpenAPI contract. Choose the narrowest interface that fits the workflow: MCP for interactive agents, the CLI for local files and automation, and REST for application integrations.

Agent entry points

Agent Skill

Install reusable Audream workflow and safety instructions in an Agent Skills-compatible host.

Remote MCP

Connect an agent with OAuth 2.1 and expose scoped Audream tools without copying an API key.

Audream CLI

Upload local audio, poll processing jobs, query Notes, and generate artifacts from scripts.

OpenAPI specification

Import the complete tool contract, request schemas, and response schemas.

LLM index

Discover the most important human-readable and machine-readable resources.

Complete agent context

Load all Audream guides as a single text document for retrieval or coding agents.

Ask across notes

Answer questions from processed notes and return the supporting note IDs.

Install the Agent Skill

The complete skill directory is public at:

https://github.com/audream-ai/audream-api-docs/tree/main/skills/audream

Machine-readable entry points:

https://docs.audream.ai/skill.md
https://docs.audream.ai/skill.json

Install the skills/audream directory in an Agent Skills-compatible host. The skill selects MCP, CLI, or REST based on the task and loads detailed references only when needed.

Connect the remote MCP server

Use this Streamable HTTP URL:

https://audream-api.tulingbc.com/mcp

Audream publishes OAuth authorization-server and protected-resource metadata. Compatible MCP clients discover OAuth automatically, open Audream Web for account authorization, use authorization code with PKCE, and receive a resource-bound access token. Default authorization grants read and processing access. Additional scopes are requested when the client needs them:

Scope	Access
`notes:read`	Read Notes, transcripts, Insights, and artifacts
`notes:write`	Rename and organize Notes
`notes:process`	Ask questions and generate Insights or artifacts
`notes:delete`	Run confirmed permanent deletion operations

The MCP server exposes Note discovery, retrieval, workspace Ask, updates, Insights, artifacts, and confirmed deletion. Local audio upload is intentionally excluded because passing large audio as base64 through model context is inefficient and unsafe; use the CLI for local files.

Install the CLI

The CLI requires Node.js 20 or newer and has no runtime package dependencies:

npm install --global github:audream-ai/audream-cli
export AUDREAM_API_KEY="audream_sk_..."

audream auth status
audream notes list
audream transcribe ./meeting.m4a --title "Planning meeting" --wait
audream insights generate NOTE_ID --wait

It emits JSON to stdout and diagnostics to stderr. Permanent deletion commands require an exact --confirm NOTE_ID value.

Import the OpenAPI contract

Use this URL when an agent platform accepts an OpenAPI document:

https://docs.audream.ai/openapi.yaml

For direct REST tools, configure bearer authentication with an Audream API key stored in the agent runtime’s secret manager:

Authorization: Bearer audream_sk_...

The OpenAPI operationId values are stable tool identifiers. Prefer them over generating names from URL paths.

Recommended tool surface

Do not expose every mutation to an autonomous agent by default. Start with the smallest tool set required by the workflow.

Operation ID	Mode	Agent use
`getCurrentAccount`	Read	Validate the configured API key and account
`listNotes`	Read	Discover available note IDs and titles
`getNote`	Read	Retrieve one note with completed transcription and Insights
`askWorkspace`	Read and inference	Ask a grounded question across all or selected processed notes
`submitTranscription`	Create	Upload user-selected audio for transcription
`getTranscription`	Read	Poll an asynchronous transcription job
`generateInsights`	Create	Generate structured Insights after transcription
`getInsights`	Read	Poll an asynchronous Insights job
`generateNoteArtifact`	Create	Generate epiphany, deep research, or podcast content
`updateNote`	Mutate	Rename or move a note to trash
`deleteTranscription`	Destructive	Remove generated results while preserving the note
`deleteNote`	Destructive	Permanently delete a note

Require explicit user confirmation immediately before deleteTranscription or deleteNote. Do not treat an earlier general request as deletion approval.

Define a compact Ask tool

Agents that only need knowledge retrieval can expose a single tool instead of the complete API:

{
  "name": "ask_audream_notes",
  "description": "Answer a question using processed Audream notes and return supporting note IDs.",
  "input_schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["question"],
    "properties": {
      "question": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2000
      },
      "note_ids": {
        "type": ["array", "null"],
        "maxItems": 100,
        "items": {
          "type": "string",
          "format": "uuid"
        }
      }
    }
  }
}

The tool executor calls POST /v1/ask and returns the API response without discarding citations:

import os

import requests


def ask_audream_notes(question: str, note_ids: list[str] | None = None) -> dict:
    response = requests.post(
        "https://audream-api.tulingbc.com/v1/ask",
        headers={
            "Authorization": f"Bearer {os.environ['AUDREAM_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={"question": question, "note_ids": note_ids},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

Preserve the returned note_ids in the final answer so the user can inspect the source notes.

Handle asynchronous tools

Transcription, Insights, and artifact generation can return 202 Accepted. A tool executor must keep the job state outside the language model and poll the corresponding GET operation.

Return a durable note_id from the initial tool call.
Poll at intervals of at least 2 seconds.
Stop on 200 or a documented terminal error.
Apply a bounded deadline and exponential backoff for transient failures.
Never let the agent interpret 202 as a completed result.

See Processing status for response handling and idempotency rules.

Agent execution policy

Use these rules in the agent’s system instructions or tool middleware:

Use Audream only when the user asks about their recordings, notes, transcripts,
Insights, or generated artifacts. List notes before selecting a note ID unless
the user supplied a valid ID. Prefer askWorkspace for cross-note questions.
Treat 202 responses as incomplete and poll the documented status endpoint.
Never expose the API key. Ask for explicit confirmation immediately before a
permanent deletion or removal of generated results. Include supporting note IDs
when an Audream answer returns them.

Context and privacy

Keep the API key and Audream responses in a trusted server-side agent runtime.
Send only the note content needed for the current task to any additional model provider.
Prefer askWorkspace when the agent needs an answer rather than complete transcripts.
Do not log bearer headers, raw audio, transcripts, or generated artifacts by default.
Rotate the key immediately if it appears in a prompt, trace, repository, or client bundle.

Remote MCP tokens are audience-bound to the Audream MCP resource and must not be forwarded to REST endpoints or other services. REST API keys remain the appropriate credential for the CLI and server-side application integrations.

Get started

Build with Audream

Build agents

Agent entry points

Agent Skill

Remote MCP

Audream CLI

OpenAPI specification

LLM index

Complete agent context

Ask across notes

Install the Agent Skill

Connect the remote MCP server

Install the CLI

Import the OpenAPI contract

Recommended tool surface

Define a compact Ask tool

Handle asynchronous tools

Agent execution policy

Context and privacy

​Agent entry points

Agent Skill

Remote MCP

Audream CLI

OpenAPI specification

LLM index

Complete agent context

Ask across notes

​Install the Agent Skill

​Connect the remote MCP server

​Install the CLI

​Import the OpenAPI contract

​Recommended tool surface

​Define a compact Ask tool

​Handle asynchronous tools

​Agent execution policy

​Context and privacy

Agent entry points

Install the Agent Skill

Connect the remote MCP server

Install the CLI

Import the OpenAPI contract

Recommended tool surface

Define a compact Ask tool

Handle asynchronous tools

Agent execution policy

Context and privacy