Agent integrations

Audream exposes a REST API and an OpenAPI 3.1 specification that agent frameworks can use to create tools. An agent can search processed notes, retrieve grounded context, upload audio, and run Audream processing workflows.

Agent entry points

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.

Import the OpenAPI contract

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

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

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.

Audream currently publishes REST and OpenAPI interfaces. It does not advertise a public MCP endpoint; an MCP host can wrap these REST operations as local tools while preserving the policies above.

Get started

Build with Audream

Build agents

Agent entry points

OpenAPI specification

LLM index

Complete agent context

Ask across notes

Import the OpenAPI contract

Recommended tool surface

Define a compact Ask tool

Handle asynchronous tools

Agent execution policy

Context and privacy

​Agent entry points

OpenAPI specification

LLM index

Complete agent context

Ask across notes

​Import the OpenAPI contract

​Recommended tool surface

​Define a compact Ask tool

​Handle asynchronous tools

​Agent execution policy

​Context and privacy

Agent entry points

Import the OpenAPI contract

Recommended tool surface

Define a compact Ask tool

Handle asynchronous tools

Agent execution policy

Context and privacy