Analyze text notes with the Speak AI text endpoints

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.

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.

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

Delete Text Note

DELETE/text/{mediaId}

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:

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

Example request

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'

Response

200 Success

The spec records this status code with no example body.

Create Text note

POST/text/create

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.

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:

{
    "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

Example request

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": ""
    }
  ]
}'

Response

200 OK

Response body, application/json.

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

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

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

Text Insight

GET/text/insight/{mediaId}

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

{
  "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

Example request

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'

Response

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.

{
  "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"
  }
}

Update Text Note

PUT/text/update/{mediaId}

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.

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	Type
`name`	string
`description`	string
`tags`	string[]
`text`	string
`rawText`	string
`remark`	string

Example request

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"
}'

Response

200 Success

The spec records this status code with no example body.

API reference for the base URL, authentication, and the error format.
Authenticate with the Speak AI API using access tokens
Upload audio and video to Speak AI and read insights
Create and update live transcription sessions in Speak AI
Export Speak AI transcripts and insights to a file

Get an API key on the Speak AI developer page.

Analyze text notes with the Speak AI text endpoints

What can you do with the text endpoints?

Delete Text Note

DELETE Request to Remove a Text Resource

Request Parameters

Response Structure

Example

Parameters

Create Text note

PARAMETERS

Webhook Callback URL:

Response

Request body

Text Insight

Response

Parameters

Update Text Note

PARAMETERS

Parameters

Request body

Related pages