Text

Create Text note

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

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.

post/text/create

Request

  • Base URL: https://api.speakai.co/v1
  • URL: https://api.speakai.co/v1/text/create
  • Auth: API key in header x-speakai-key and API key in header x-access-token

Request body

namestring

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.

textstring

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.

rawTextstring

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.

descriptionstring

Adds a short summary shown alongside the note. String. Empty string allowed. Stored trimmed. Defaults to an empty string.

tagsstring

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.

folderIdstring

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.

fieldsobject[]

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.

countobject

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.

createdAtstring

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.

callbackUrlstring

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.

userIdstring

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.

remarkstring

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.

Response

OK

statusstring

Changes

No recorded changes to this operation across all 2 revisions of this API.