# Transcripts

> Manage conversation transcripts and ingest externally-generated messages.

`divinci.transcripts` manages conversation transcripts in a workspace — listing
them, adding messages, and **batch-ingesting** conversations that were generated
elsewhere (for example, inference you ran with a local or third-party model).

## Creating and reading transcripts

```typescript
const transcript = await divinci.transcripts.create({
  workspaceId: "ws_123",
  releaseId: "rel_abc123", // optional
});

const { data } = await divinci.transcripts.list("ws_123", { limit: 20 });
const one = await divinci.transcripts.get(transcript._id);

await divinci.transcripts.delete(transcript._id);
```

## Adding a single message

```typescript
const message = await divinci.transcripts.addMessage(transcript._id, {
  role: "user",
  content: "How do I reset my password?",
});
```

## Batch ingestion

`ingestBatch` records a whole conversation in one call. This is the canonical path
for persisting messages produced by inference performed outside Divinci.

```typescript
const result = await divinci.transcripts.ingestBatch({
  workspaceId: "ws_123",
  transcriptId: transcript._id,
  defaults: {
    release: "rel_abc123",
    metadata: { channel: "local-llm" },
  },
  items: [
    { role: "user", content: "Hi" },
    { role: "assistant", content: "Hello! How can I help?", name: "support-bot" },
  ],
});

console.log(result.inserted);   // number of messages stored
console.log(result.messageIds); // ids in order
```

<Aside type="tip">
  `defaults` are applied to every item that doesn't override them — set the
  `release` and shared `metadata` once instead of repeating them per message.
</Aside>

## Method reference

| Method | Description |
|--------|-------------|
| `list(workspaceId, options?)` | Paginated transcripts. |
| `get(transcriptId)` | Fetch a transcript. |
| `create(options)` | Create a transcript (`workspaceId`, optional `releaseId`). |
| `addMessage(transcriptId, options)` | Append a single message. |
| `ingestBatch(options)` | Bulk-insert messages with shared defaults. |
| `delete(transcriptId)` | Delete a transcript. |