Speechmind API Documentation

Welcome to the SpeechMind GraphQL API v2.

This reference document provides detailed information about the endpoints and features of the SpeechMind API v2. It covers the available queries, mutations, types, and input objects, along with usage examples and expected input/output formats.

This updated version of the API introduces enhanced features and improved functionality across the three main processes explained in the next chapters.

Authentication is required to access most API features. Clients must first obtain a JSON Web Token (JWT) through the authentication endpoint and include it in the Authorization header of all subsequent requests:

Contact

hello@speechmind.com

www.speechmind.com

API Endpoints

https://api-v2.speechmind.com/external/v2/graphql

Headers

# // Your API key
x-api-key: <your-api-key>

Version

2.0.0

Authentication Guide for using the API

To access the SpeechMind API, you need to authenticate using an API key. Follow the steps below to generate and use your API key:

🔑 Steps to Generate Your API Key

Log in to your SpeechMind account.
Navigate to Account > Organisation you find a Developers API section.
Click on Generate New API Key.
Copy the generated key and store it securely.

🚀 Using the API Key

Include your API key in the request headers under the x-api-key field when making API calls.

Example Request Header

x-api-key: <your-api-key>

Queries

`getProtocolBySlug`

Description

It validates the user's authentication using an API key passed in the request header and returns the protocol associated with the specified slug.

Response

Returns an EditSpeakerDataTypeWithSpeaker

Arguments

Name	Description
`protocolSlug` - `String!`	ID of the protocol

Example

Query

query getProtocolBySlug($protocolSlug: String!) {
  getProtocolBySlug(protocolSlug: $protocolSlug) {
    protocol {
      ...ApiProtocolTypeFragment
    }
    speakerList
    summaryPerSpeakerList {
      ...ApiSummaryPerSpeakerItemTypeWithSpeakerFragment
    }
  }
}

Variables

{"protocolSlug": "abc123"}

Response

{
  "data": {
    "getProtocolBySlug": {
      "protocol": ApiProtocolType,
      "speakerList": GenericScalar,
      "summaryPerSpeakerList": [
        ApiSummaryPerSpeakerItemTypeWithSpeaker
      ]
    }
  }
}

Mutations

`renameSpeakerInTextsegment`

Description

Rename speaker in text segments for a given protocol. It validates the user's authentication using an API key passed in the request header and processes the provided protocol slug and speaker information.

Response

Returns a RenameSpeakerInTextSegmentMutation

Arguments

Name	Description
`protocolSlug` - `String!`	Name of the protocol
`speakerJson` - `[SpeakerDataInput]!`	List of speakers to rename

Example

Query

mutation renameSpeakerInTextsegment(
  $protocolSlug: String!,
  $speakerJson: [SpeakerDataInput]!
) {
  renameSpeakerInTextsegment(
    protocolSlug: $protocolSlug,
    speakerJson: $speakerJson
  ) {
    textsegmentsForRename {
      ...ApiTextsegmentTypeWithSpeakerFragment
    }
    success
  }
}

Variables

{
  "protocolSlug": "abc123",
  "speakerJson": [SpeakerDataInput]
}

Response

{
  "data": {
    "renameSpeakerInTextsegment": {
      "textsegmentsForRename": [
        ApiTextsegmentTypeWithSpeaker
      ],
      "success": true
    }
  }
}

Types

ApiProtocolType

Fields

Field Name	Description
`slug` - `String`	ID of the protocol
`name` - `String`	Name of the protocol
`date` - `String`	Date of the protocol
`status` - `Boolean`	Status of the protocol, status can be True or False
`editStage` - `Boolean`	Edit stage of the protocol, edit_stage can be True or False
`bucketAws` - `String`	AWS bucket name, Example Object: {'bucket': 'bucket_name', 'key': 'key_name', 'video.mp3': 'video_name.ogg'}

Example

{
  "slug": "xyz789",
  "name": "abc123",
  "date": "abc123",
  "status": false,
  "editStage": true,
  "bucketAws": "abc123"
}

Types

ApiSpeakerType

Fields

Field Name	Description
`slug` - `String`	Slug of the speaker
`gender` - `String`	Gender of the speaker
`givenName` - `String`	Given name of the speaker
`familyName` - `String`	Family name of the speaker
`party` - `String`	Partei Firma of the speaker
`preTitel` - `String`	Pre Titel of the speaker
`posShort` - `String`	Pos Short of the speaker
`posLong` - `String`	Pos Long of the speaker
`postTitel` - `String`	Post Titel of the speaker
`specialCase` - `Boolean`	Special Case of the speaker

Example

{
  "slug": "abc123",
  "gender": "abc123",
  "givenName": "xyz789",
  "familyName": "abc123",
  "party": "xyz789",
  "preTitel": "abc123",
  "posShort": "xyz789",
  "posLong": "xyz789",
  "postTitel": "abc123",
  "specialCase": false
}

Types

ApiSummaryPerSpeakerItemTypeWithSpeaker

Fields

Field Name	Description
`speakerObj` - `ApiSpeakerType`	Object of the speaker
`textList` - `String`	{ "0": ["Die Software funktioniert gut."], "1": ["Bitte fügen Sie eine Chat-Funktion hinzu."], "2": ["Das Login über Google sollte schneller sein."] ... }
`speakerSuggestion` - `String`	Speaker suggestion
`createdAt` - `DateTime`	Creation date of the summary
`updatedAt` - `DateTime`	Last update date of the summary

Example

{
  "speakerObj": ApiSpeakerType,
  "textList": "abc123",
  "speakerSuggestion": "abc123",
  "createdAt": "2007-12-03T10:15:30Z",
  "updatedAt": "2007-12-03T10:15:30Z"
}

Types

ApiTextsegmentTypeWithSpeaker

Fields

Field Name	Description
`id` - `String`	ID of the TextSegment
`speakerObj` - `ApiSpeakerType`	Object of the speaker
`textJson` - `[TranscriptSegment]`	List of transcript segments
`pos` - `Int`	Position of the text segment

Example

{
  "id": "xyz789",
  "speakerObj": ApiSpeakerType,
  "textJson": [TranscriptSegment],
  "pos": 123
}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example

true

Types

DateTime

Description

The DateTime scalar type represents a DateTime value as specified by iso8601.

Example

"2007-12-03T10:15:30Z"

Types

EditSpeakerDataTypeWithSpeaker

Fields

Field Name	Description
`protocol` - `ApiProtocolType`	Protocol object
`speakerList` - `GenericScalar`	{ "Rafiq": { "duration": 77.32, "textsegment": [ { "id": 8, "textsegment_duration": 5.8, "text": "Hello world.", "time": { "start_time": 12.97, "end_time": 14.48 } } ] } }
`summaryPerSpeakerList` - `[ApiSummaryPerSpeakerItemTypeWithSpeaker]`	List of summaries per speaker

Example

{
  "protocol": ApiProtocolType,
  "speakerList": GenericScalar,
  "summaryPerSpeakerList": [
    ApiSummaryPerSpeakerItemTypeWithSpeaker
  ]
}

Types

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example

123.45

Types

GenericScalar

Description

The GenericScalar scalar type represents a generic GraphQL scalar value that could be: String, Boolean, Int, Float, List or Object.

Example

GenericScalar

Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example

Types

RenameSpeakerInTextSegmentMutation

Description

Fields

Field Name	Description
`textsegmentsForRename` - `[ApiTextsegmentTypeWithSpeaker]`	List of text segments with renamed speakers
`success` - `Boolean`	Indicates if the rename operation was successful

Example

{
  "textsegmentsForRename": [
    ApiTextsegmentTypeWithSpeaker
  ],
  "success": false
}

Types

SpeakerDataInput

Fields

Input Field	Description
`oldSlug` - `String!`	Current slug of the speaker
`gender` - `String`	Gender of the new speaker
`givenName` - `String`	Given name of the new speaker
`familyName` - `String`	Family name of the new speaker
`party` - `String`	Party of the new speaker
`preTitel` - `String`	Pre-title of the new speaker
`postTitel` - `String`	Post-title of the new speaker
`posLong` - `String`	Long position of the new speaker
`posShort` - `String`	Short position of the new speaker

Example

{
  "oldSlug": "xyz789",
  "gender": "abc123",
  "givenName": "abc123",
  "familyName": "abc123",
  "party": "xyz789",
  "preTitel": "xyz789",
  "postTitel": "xyz789",
  "posLong": "abc123",
  "posShort": "xyz789"
}

Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example

"xyz789"

Types

TranscriptSegment

Fields

Field Name	Description
`text` - `String`	Transcription text
`startTime` - `Float`	Start time of the segment in seconds
`endTime` - `Float`	End time of the segment in seconds

Example

{
  "text": "abc123",
  "startTime": 123.45,
  "endTime": 987.65
}