---
title: "Analyze text notes with the Speak AI text endpoints"
description: "Create a text note in Speak AI, read the insights generated from it, update the note when its content changes, and delete it when you are finished."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze text notes with the Speak AI text endpoints


import EndpointIndex from "@/components/api/EndpointIndex.astro";

The Speak AI API exposes 4 text endpoints under the base URL `https://api.speakai.co/v1`. Every request needs the `x-speakai-key` and `x-access-token` headers described in [Authentication](/api/authentication/).

Text notes are operable as well, complete listing of media can be requested, insight to particular analyzed media, analytics on top of our analysis, and of course, you can delete your note !

Attention:
`id` is the required parameter here instead of `mediaId` as in Media functionalities

Re-analyzing a text note runs through `GET /media/reanalyze/{mediaId}`, which covers text notes and uploaded files alike. It is documented on the [Media](/api/media/) page.

## What can you do with the text endpoints?

Speak AI groups these 4 endpoints under the text resource. Each entry below links to the full reference for that endpoint further down this page.

| Method | Path | What it does |
| --- | --- | --- |
| `DELETE` | [`/text/{mediaId}`](#delete-text-media-id) | Delete Text Note |
| `POST` | [`/text/create`](#post-text-create) | Create Text note |
| `GET` | [`/text/insight/{mediaId}`](#get-text-insight-media-id) | Text Insight |
| `PUT` | [`/text/update/{mediaId}`](#put-text-update-media-id) | Update Text Note |

<h2 id="delete-text-media-id">Delete Text Note</h2>

#### DELETE Request to Remove a Text Resource

This endpoint is used to delete a specific text resource identified by its unique `mediaId`. By sending a DELETE request to this endpoint, the client can remove the text resource from the server.

##### Request Parameters

- **mediaId** (path parameter): A unique identifier for the text resource that you wish to delete. This is a required parameter and should be included in the URL.

##### Response Structure

Upon successful deletion of the text resource, the server will respond with a status code indicating the outcome of the request:

- **204 No Content**: Indicates that the resource was successfully deleted and there is no additional content to return.

- **404 Not Found**: Indicates that the specified `mediaId` does not correspond to any existing resource.

##### Example

To delete a text resource with a specific `mediaId`, the request would look like:

```text
DELETE https://api.speakai.co/v1/text/12345

```

This request would attempt to delete the text resource with the ID `12345`.

Make sure to handle the response appropriately to confirm the deletion or to manage any errors that may arise.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mediaId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X DELETE 'https://api.speakai.co/v1/text/3722e7826784' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="delete-text-media-id" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="post-text-create">Create Text note</h2>

#### PARAMETERS

The difference between `rawText` and `text.`

`text` (required): Text is an HTML field to display content on the editor. It helps users to identify `bold,` `italic` or any other editor functionality.

**Important:** If you don't have an HTML editor in your application, you can pass normal text content.

`rawText` (required): This helps Speak AI to analyze text notes.

`remark`: If you want to pass any remarks from the user to display on Speak and also in your application.

``` json
userId: String; // optional
folderId: String, // optional
name: String, // required,
description: string, // optional
tags: [], // optional
text: "HTML content", // required
rawText: "raw text content", // required
remark: "string", // optional

```

##### Webhook Callback URL:

- If you created a webhook for text events and want to receive a callback to a specific URL for this text note, you can assign `callbackUrl` - `string` in a `req.body`.
- Speak will consider the `callbackUrl` and will skip the callbackUrl created via Webhook API.

---

#### Response

You can select from the examples attached to this API endpoint or find below:

```text
{
 "status": "success",
 "data": {
 "mediaId": "xxxxxxxxx",
 "folderId": ""
 }
}

```

**Request rules.** Nothing in the body is unconditionally required. The body is validated, and any property not listed below is rejected with a 400, so do not send extra keys.

In practice: send name, text and rawText. If you omit name, the note is titled with the creation timestamp in YYYY-MM-DD HH:mm:ss form. If rawText is missing or empty the note is saved but never analyzed, so you get no insights, sentiment, keywords or search embeddings for it.

folderId: if you omit it or send an empty string, the note goes into the first folder belonging to the note owner, and one is created for them if they have none. The folder actually used comes back in the response.

count: if you omit it, word and character counts are calculated from rawText. If you send it, your numbers are stored as given and no counting is done.

tags: only the comma separated string form is saved on this endpoint. An array passes validation and is then discarded, leaving the note with no tags.

uploadType: send zapier to have analysis run in the background and to run your automations against the new note. With any other value, Speak finishes analyzing before it answers, so the request takes longer and a note analyzed webhook fires before you get the response.

Billing: if the workspace has no text note credit left, the request still returns HTTP 200, but the body carries a failed status with code 402 and no note is created.

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Names the note. Surrounding whitespace is removed. If you leave it out, Speak titles the note with the creation timestamp in YYYY-MM-DD HH:mm:ss form. String. Optional. Stored trimmed. Falls back to a generated timestamp title. |
| `text` | string | Holds the display copy of the note. It can contain HTML so an editor keeps bold, italic and other formatting. If your application has no rich text editor, send the same plain content you send in rawText. This copy is stored and shown, but it is not what gets analyzed. String. Empty string allowed. Stored trimmed. Stored as an empty string if you omit it. |
| `rawText` | string | Carries the plain text that Speak analyzes. This is what produces insights, sentiment, keywords and the search index for the note, so send it whenever you want the note analyzed. If it is empty, the note is saved but no analysis runs. String. Empty string allowed. Stored trimmed. Stored as an empty string if you omit it. |
| `description` | string | Adds a short summary shown alongside the note. String. Empty string allowed. Stored trimmed. Defaults to an empty string. |
| `tags` | string | Labels the note. Send a comma separated string such as "sales,q3" and Speak splits it into separate tags. A string with no comma becomes a single tag. An array passes validation on this endpoint but is not saved, so use the string form when you create a note. String or array. Only the string form is stored on create. Split on commas. An empty string leaves the note with no tags. |
| `folderId` | string | Files the note in one of your folders. Leave it out or send an empty string and Speak puts the note in the first folder belonging to the owner, creating one if they have none. The folder that was used comes back in the response. String. Empty string allowed. |
| `fields` | object[] | Sets values for the custom fields on the note. Each entry takes an id and a value. Entries whose id does not match a custom field in your workspace are dropped and the remaining ones are saved. If none of the ids match, no custom field values are saved. Array of objects shaped \{id, value\}. Every entry must carry an id. Value can be any JSON type. Unknown ids are silently removed. |
| `count` | object | Overrides the word and character counts stored on the note. Send wordCount, characterCount and characterCountWithoutSpace. Leave it out and Speak counts them from rawText for you. Object. Keys read: wordCount, characterCount, characterCountWithoutSpace, all numbers. Any object shape is accepted, and keys you leave out are stored as empty. |
| `createdAt` | string | Sets the creation date recorded on the note, so you can backdate content you are importing. Defaults to the time of the request. Date. Accepts an ISO 8601 date string or a timestamp. |
| `callbackUrl` | string | Stores a webhook delivery URL on the note. Speak uses it in place of the URL configured on your webhook only for deliveries that carry the whole note record, which on this endpoint means the failure event sent if the note cannot be saved. The note created and note analyzed events from this endpoint always go to the URL configured on your webhook. String. Empty string allowed. Stored exactly as sent, without trimming. Stored as an empty string if you omit it. |
| `userId` | string | Assigns the new note to another user in your workspace, using that user's 24 character id. Leave it out and the note belongs to the account making the request. The owner also decides which folder is used when you do not name one. String. Must be the 24 character id of a user. Any other value fails the save and returns a 500. |
| `uploadType` | string | Records where the note came from. Send zapier to have analysis run in the background and to run your automations against the new note. With any other value, Speak analyzes the note before it answers. If you leave it out, the note records web. String. Defaults to web. Only the value zapier changes behavior. |
| `remark` | string | A free text remark on the note. Postman's example sends this on create, but the value is not saved at creation time. Add a remark by updating the note afterwards. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/text/create' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

</CodePanel>

<ResponsePanel id="post-text-create" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.mediaId` | string |

Example response (Create Text note), `application/json`.

```json
{
  "status": "success",
  "data": {
"mediaId": "c55125c7cc32"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-text-insight-media-id">Text Insight</h2>

You need to call this API to find the insights from your text note.

Please check an example find the return response and an object.

#### Response

```text
{
 "status": "success",
 "data": {
 "count": {
 "wordCount": 0,
 "characterCount": 0,
 "characterCountWithoutSpace": 0
 },
 "insight": {
 "intents": {
 "needs": [
 {
 "id": 32,
 "text": "Sentence 1"
 }
 ],
 "wants": [
 {
 "id": 50,
 "text": "Sentence 1"
 }
 ]
 },
 "state": "processed",
 "updatedAt": "2021-04-13T00:30:26.720Z",
 "arts": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 512,
 "startChar": 489
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 },
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 1397,
 "startChar": 1386
 }
 ],
 "isCustom": false,
 "name": "xxxxxxx",
 "id": 1
 }
 ],
 "brands": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 202,
 "startChar": 198
 },
 {
 "endChar": 356,
 "startChar": 352
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 },
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 333,
 "startChar": 310
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 1
 },
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 721,
 "startChar": 713
 },
 {
 "endChar": 3009,
 "startChar": 3001
 },
 {
 "endChar": 6074,
 "startChar": 6066
 },
 {
 "endChar": 6391,
 "startChar": 6383
 },
 {
 "endChar": 6615,
 "startChar": 6607
 },
 {
 "endChar": 6854,
 "startChar": 6846
 },
 {
 "endChar": 6914,
 "startChar": 6906
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 2
 }
 ],
 "cardinals": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 1797,
 "startChar": 1794
 },
 {
 "endChar": 1850,
 "startChar": 1847
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 },
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 3028,
 "startChar": 3022
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 1
 }
 ],
 "dates": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 755,
 "startChar": 739
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "events": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 755,
 "startChar": 739
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "facs": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 755,
 "startChar": 739
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "geopolitical": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 172,
 "startChar": 163
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "keywords": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 172,
 "startChar": 163
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "languages": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 172,
 "startChar": 163
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "laws": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 172,
 "startChar": 163
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "locations": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 172,
 "startChar": 163
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "money": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 172,
 "startChar": 163
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "nationalities": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 1284,
 "startChar": 1275
 }
 ],
 "isCustom": false,
 "name": "Republish",
 "id": 0
 }
 ],
 "ordinals": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 2812,
 "startChar": 2807
 },
 {
 "endChar": 2851,
 "startChar": 2846
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "people": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 196,
 "startChar": 188
 },
 {
 "endChar": 350,
 "startChar": 342
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "percentages": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 196,
 "startChar": 188
 },
 {
 "endChar": 350,
 "startChar": 342
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "products": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 4930,
 "startChar": 4926
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "quantities": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 4930,
 "startChar": 4926
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "times": [
 {
 "isDeleted": false,
 "instances": [
 {
 "endChar": 4930,
 "startChar": 4926
 }
 ],
 "isCustom": false,
 "name": "xxxxx",
 "id": 0
 }
 ],
 "topics": []
 },
 "description": "xxxxx",
 "tags": [
 "tag1",
 "tag2"
 ],
 "text": "<strong class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27;>Hello, This is sample text</b>",
 "rawText": "Hello, This is sample text",
 "state": "processed",
 "assignTo": "",
 "remark": "",
 "sentiment": [
 {
 "document": {
 "Negative": 0.00000,
 "Neutral": 0.00000,
 "Positive": 0.00000
 },
 "sentences": [
 {
 "id": 1,
 "instances": [],
 "score": {
 "compound": 0,
 "neg": 0,
 "neu": 1,
 "pos": 0
 },
 "text": "Sentence 1"
 },
 {
 "id": 2,
 "instances": [],
 "score": {
 "compound": 0,
 "neg": 0,
 "neu": 1,
 "pos": 0
 },
 "text": "Sentence 2"
 },
 {
 "id": 3,
 "instances": [],
 "score": {
 "compound": 0.7269,
 "neg": 0.037,
 "neu": 0.809,
 "pos": 0.154
 },
 "text": "Sentence 3"
 }
 ]
 }
 ],
 "createdAt": "2021-04-13T00:30:26.721Z",
 "originalCreatedAt": "2021-04-13T00:30:26.721Z",
 "name": "xxxxx"
 }
}

```

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mediaId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/text/insight/c1f4c82dec47' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-text-insight-media-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.count` | object |
| `data.insight` | object |
| `data.description` | string |
| `data.tags` | string[] |
| `data.text` | string |
| `data.rawText` | string |
| `data.state` | string |
| `data.assignTo` | string |
| `data.remark` | string |
| `data.sentiment` | object[] |
| `data.createdAt` | string (date-time) |
| `data.originalCreatedAt` | string (date-time) |
| `data.name` | string |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Text Insight), `application/json`. Arrays are shortened to one entry and long strings are cut.

```json
{
  "status": "success",
  "data": {
"count": {
  "wordCount": 0,
  "characterCount": 0,
  "characterCountWithoutSpace": 0
},
"insight": {
  "intents": {
    "needs": [
      {
        "id": 32,
        "text": "Sentence 1"
      }
    ],
    "wants": [
      {
        "id": 50,
        "text": "Sentence 1"
      }
    ]
  },
  "state": "processed",
  "updatedAt": "2021-04-13T00:30:26.720Z",
  "arts": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 512,
          "startChar": 489
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "brands": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 202,
          "startChar": 198
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "cardinals": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 1797,
          "startChar": 1794
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "dates": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 755,
          "startChar": 739
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "events": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 755,
          "startChar": 739
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "facs": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 755,
          "startChar": 739
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "geopolitical": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 172,
          "startChar": 163
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "keywords": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 172,
          "startChar": 163
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "languages": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 172,
          "startChar": 163
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "laws": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 172,
          "startChar": 163
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "locations": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 172,
          "startChar": 163
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "money": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 172,
          "startChar": 163
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "nationalities": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 1284,
          "startChar": 1275
        }
      ],
      "isCustom": false,
      "name": "Republish",
      "id": 0
    }
  ],
  "ordinals": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 2812,
          "startChar": 2807
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "people": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 196,
          "startChar": 188
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "percentages": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 196,
          "startChar": 188
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "products": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 4930,
          "startChar": 4926
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "quantities": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 4930,
          "startChar": 4926
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "times": [
    {
      "isDeleted": false,
      "instances": [
        {
          "endChar": 4930,
          "startChar": 4926
        }
      ],
      "isCustom": false,
      "name": "xxxxx",
      "id": 0
    }
  ],
  "topics": []
},
"description": "xxxxx",
"tags": [
  "tag1"
],
"text": "<b>Hello, This is sample text</b>",
"rawText": "Hello, This is sample text",
"state": "processed",
"assignTo": "",
"remark": "",
"sentiment": [
  {
    "document": {
      "Negative": 0,
      "Neutral": 0,
      "Positive": 0
    },
    "sentences": [
      {
        "id": 1,
        "instances": [],
        "score": {
          "compound": 0,
          "neg": 0,
          "neu": 1,
          "pos": 0
        },
        "text": "Sentence 1"
      }
    ]
  }
],
"createdAt": "2021-04-13T00:30:26.721Z",
"originalCreatedAt": "2021-04-13T00:30:26.721Z",
"name": "xxxxx"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="put-text-update-media-id">Update Text Note</h2>

#### PARAMETERS

If you want to update your customer unique `medicalId` key then you can pass as a `string`.

The difference between `rawText` and `text`

`text` (required): Text is an HTML field to display content on the editor. It helps users to identify `bold`, `italic` or any other editor functionality.

**Important:** If you don't have HTML editor in your application then you can pass normal text content.

`rawText` (required): This helps Speak AI to analyze text notes.

`remark`: If you want to pass any remarks from the user to display on Speak and also in your application.

```text
medicalId: String, // optional
name: String, // required,
description: string, // optional
tags: [], // optional
text: "HTML content", // required
rawText: "raw text content", // required
remark: "string", // optional
```

**Request rules.** The mediaId in the path is required and must belong to a note in your workspace that is not deleted. If it does not, you get a 404 before the controller runs. Body validation happens first, so a bad body returns a 400 before that check.

Nothing in the body is unconditionally required, but any property not listed below is rejected with a 400, so do not send extra keys.

This endpoint replaces the note body rather than patching it. rawText drives the whole write: Speak counts the words in the rawText you send, and if that count is zero, both rawText and text are cleared on the note and the stored sentiment is emptied. That happens whether you sent an empty rawText or left it out entirely, and it happens even if you sent a count object with a non-zero wordCount. Always send the full note body you want to keep.

description, manageBy, remark, status and createdAt are only written when you send a value that is not empty. Sending an empty string for any of them leaves the current value in place instead of clearing it. tags behaves differently: an empty string leaves the current tags alone, but an empty array is written and clears them.

Omitting name leaves the stored title unchanged.

Set isAutoSave to true for background editor saves. That skips reanalysis and skips the in-app update notification. On a normal save, Speak reanalyzes the note only if it has not been processed before, and a note analyzed webhook is attempted when it does.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mediaId` | path | string | Yes |  |

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `rawText` | string | Replaces the plain text that Speak analyzes. This endpoint replaces rather than patches, so if you send nothing here, or send text with no words in it, Speak clears both the analyzed text and the display text on the note and empties its stored sentiment. Always send the complete note body you want to keep. String. Empty string allowed. Stored trimmed. The word count derived from this value decides whether text and rawText are stored or cleared. |
| `text` | string | Replaces the display copy of the note, which can contain HTML so an editor keeps bold, italic and other formatting. If the rawText you send has no words, Speak clears this instead. If the rawText you send has words but you leave text out, the current display copy stays as it is. String. Empty string allowed. Stored trimmed. Cleared whenever the rawText you send has no words. |
| `name` | string | Replaces the note title. It also appears in the success message and in the in-app update notification. Leave it out and the current title stays as it is. String. Stored trimmed. |
| `description` | string | Replaces the short summary shown alongside the note. An empty string leaves the current summary in place rather than clearing it. String. Empty string allowed but treated as no change. Stored trimmed. |
| `tags` | string[] | Replaces the tags on the note. Send an array of strings. A comma separated string is accepted but is stored as one tag on this endpoint, so use the array form here. Leave it out to keep the existing tags, or send an empty array to remove them all. String or array. Stored as sent. An empty array clears the tags; an empty string is treated as no change. |
| `remark` | string | Replaces the free text remark on the note. An empty string or null leaves the current remark in place rather than clearing it. String. Empty string and null allowed but treated as no change. |
| `status` | string | Sets the status recorded on the note. An empty string leaves the current status in place. String. Empty string allowed but treated as no change. Values outside the listed set are stored as sent but are not recognized anywhere in the product, so stay within the list. One of: ``, `pending`, `progress`, `completed`, `pendingPayment`. |
| `manageBy` | string | Assigns the note to a user in your workspace, using that user's 24 character id. An empty string leaves the current assignee in place. String. Must be the 24 character id of a user. Empty string allowed but treated as no change. Any other value fails the update and returns a 500. |
| `isAutoSave` | boolean | Marks the request as a background save from an editor. Send true and Speak skips reanalyzing the note and skips the in-app update notification, which keeps frequent autosaves cheap. Send false or leave it out for a normal save. Boolean. Defaults to a normal save when absent. |
| `count` | object | Overrides the word and character counts stored on the note. Send wordCount, characterCount and characterCountWithoutSpace. Leave it out and Speak recounts from the rawText you sent. These numbers do not decide whether the body is kept: only the rawText you send does that. Object. Keys read: wordCount, characterCount, characterCountWithoutSpace, all numbers. Any object shape is accepted, and the counts are rewritten on every update. |
| `createdAt` | string | Changes the creation date recorded on the note. Leave it out to keep the current date. Date. Accepts an ISO 8601 date string or a timestamp. Only written when present. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X PUT 'https://api.speakai.co/v1/text/update/2b12351c8146' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

</CodePanel>

<ResponsePanel id="put-text-update-media-id" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Export Speak AI transcripts and insights to a file](/api/exports/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-text).

Source: https://docs.speakai.co/api/text/index.mdx