---
title: "Agent integrations"
description: "Connect AI agents to Audream with OpenAPI-compatible tools and safe execution policies."
---
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
Install reusable Audream workflow and safety instructions in an Agent Skills-compatible host.
Connect an agent with OAuth 2.1 and expose scoped Audream tools without copying an API key.
Upload local audio, poll processing jobs, query Notes, and generate artifacts from scripts.
Import the complete tool contract, request schemas, and response schemas.
Discover the most important human-readable and machine-readable resources.
Load all Audream guides as a single text document for retrieval or coding agents.
Answer questions from processed notes and return the supporting note IDs.
## Install the Agent Skill
The complete skill directory is public at:
```text
https://github.com/audream-ai/audream-api-docs/tree/main/skills/audream
```
Machine-readable entry points:
```text
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:
```text
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:
```bash
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:
```text
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:
```text
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:
```json
{
"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:
```python
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.
1. Return a durable `note_id` from the initial tool call.
2. Poll at intervals of at least 2 seconds.
3. Stop on `200` or a documented terminal error.
4. Apply a bounded deadline and exponential backoff for transient failures.
5. Never let the agent interpret `202` as a completed result.
See [Processing status](/guides/processing-status) for response handling and idempotency rules.
## Agent execution policy
Use these rules in the agent's system instructions or tool middleware:
```text
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.