---
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 body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `name` | string |
| `folderId` | string |
| `description` | string |
| `tags` | string[] |
| `text` | string |
| `rawText` | string |
| `remark` | string |
| `fields` | object[] |
| `fields[].id` | string |
| `fields[].value` | string |

<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 '{
  "name": "text file 1",
  "folderId": "",
  "description": "description",
  "tags": [
"tag1",
"tag2"
  ],
  "text": "<b>This is my sample text. Please provide the proper text with some entities included in it. For example: Apple, Canada, Fruits, $50,000.</b>",
  "rawText": "This is my sample text. Please provide the proper text with some entities included in it. For example: Apple, Canada, Fruits, $50,000.",
  "remark": "add any remarks",
  "fields": [
{
  "id": "",
  "value": ""
}
  ]
}'
```

</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
```

### Parameters

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

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `name` | string |
| `description` | string |
| `tags` | string[] |
| `text` | string |
| `rawText` | string |
| `remark` | string |

<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 '{
  "name": "text file",
  "description": "description",
  "tags": [
"tag1",
"tag2"
  ],
  "text": "<b>this is my sample text 2</b>",
  "rawText": "this is my sample text 2. Sample code format. Happy.",
  "remark": "update any remarks"
}'
```

</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