Speechmind API Documentation

Welcome to the SpeechMind GraphQL API.

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

The main focus of the initial API version are 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/v1/graphql

Headers

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

Version

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

`checkAnalysisResults`

Response

Returns a CheckAnalysisResultsReturn

Arguments

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

Example

Query

query checkAnalysisResults($protocolSlug: String!) {
  checkAnalysisResults(protocolSlug: $protocolSlug) {
    currentDepth
    classType
  }
}

Variables

{"protocolSlug": "xyz789"}

Response

{
  "data": {
    "checkAnalysisResults": {
      "currentDepth": 987,
      "classType": "xyz789"
    }
  }
}

Queries

`getAllProjects`

Description

It returns all projects for a user.

Response

Returns [ApiProjectType]

Example

Query

query getAllProjects {
  getAllProjects {
    slug
    name
  }
}

Response

{
  "data": {
    "getAllProjects": [
      {
        "slug": "abc123",
        "name": "abc123"
      }
    ]
  }
}

Queries

`getPresignedAwsUrl`

Description

It validates the user's authentication using an API key passed in the request header and returns a presigned URL for uploading files to AWS S3.

Response

Returns an AWSUrlObject

Arguments

Name	Description
`uniqueObjName` - `String!`	Unique name of the object

Example

Query

query getPresignedAwsUrl($uniqueObjName: String!) {
  getPresignedAwsUrl(uniqueObjName: $uniqueObjName) {
    url
    fields
  }
}

Variables

{"uniqueObjName": "xyz789"}

Response

{
  "data": {
    "getPresignedAwsUrl": {
      "url": "abc123",
      "fields": GenericScalar
    }
  }
}

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 EditSpeakerDataType

Arguments

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

Example

Query

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

Variables

{"protocolSlug": "xyz789"}

Response

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

Queries

`getProtocolsByProjectSlug`

Description

It returns all the documents from a project.

Response

Returns [ApiProtocolType]

Arguments

Name	Description
`slug` - `String!`	Slug of the project

Example

Query

query getProtocolsByProjectSlug($slug: String!) {
  getProtocolsByProjectSlug(slug: $slug) {
    slug
    name
    date
    status
    editStage
    bucketAws
  }
}

Variables

{"slug": "xyz789"}

Response

{
  "data": {
    "getProtocolsByProjectSlug": [
      {
        "slug": "xyz789",
        "name": "xyz789",
        "date": "xyz789",
        "status": false,
        "editStage": true,
        "bucketAws": "xyz789"
      }
    ]
  }
}

Queries

`getResultItemsByProtocol`

Description

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

Response

Returns an AgendaItemListType

Arguments

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

Example

Query

query getResultItemsByProtocol($protocolSlug: String!) {
  getResultItemsByProtocol(protocolSlug: $protocolSlug) {
    agendaItemList {
      ...ApiAgendaItemTypeFragment
    }
    taskList {
      ...ApiTaskTypeFragment
    }
  }
}

Variables

{"protocolSlug": "abc123"}

Response

{
  "data": {
    "getResultItemsByProtocol": {
      "agendaItemList": [ApiAgendaItemType],
      "taskList": [ApiTaskType]
    }
  }
}

Queries

`getTextsegmentsByProtocolAndPage`

Description

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

Response

Returns a TextsegmentListType

Arguments

Name	Description
`protocolSlug` - `String!`	ID of the protocol
`page` - `String!`	Page number

Example

Query

query getTextsegmentsByProtocolAndPage(
  $protocolSlug: String!,
  $page: String!
) {
  getTextsegmentsByProtocolAndPage(
    protocolSlug: $protocolSlug,
    page: $page
  ) {
    textsegmentList {
      ...ApiTextsegmentTypeFragment
    }
  }
}

Variables

{
  "protocolSlug": "abc123",
  "page": "xyz789"
}

Response

{
  "data": {
    "getTextsegmentsByProtocolAndPage": {
      "textsegmentList": [ApiTextsegmentType]
    }
  }
}

Mutations

`createAnalysis`

Description

Create a new analysis 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.

Response

Returns a CreateAnalysisMutation

Arguments

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

Example

Query

mutation createAnalysis($protocolSlug: String!) {
  createAnalysis(protocolSlug: $protocolSlug) {
    success
  }
}

Variables

{"protocolSlug": "xyz789"}

Response

{"data": {"createAnalysis": {"success": true}}}

Mutations

`createProject`

Description

Create a new project. User can upload files into a project. Pass the resulting slug into the import audio mutation.

Response

Returns a CreateProjectMutation

Arguments

Name	Description
`name` - `String!`	Name of the project

Example

Query

mutation createProject($name: String!) {
  createProject(name: $name) {
    project {
      ...ApiProjectTypeFragment
    }
  }
}

Variables

{"name": "xyz789"}

Response

{"data": {"createProject": {"project": ApiProjectType}}}

Mutations

`importAudio`

Description

Mutation to upload and register an audio file for processing. This mutation allows users to upload an audio file and register it for further processing. It validates the user's authentication using an API key passed in the request header and processes the provided audio metadata.

Response

Returns an ImportAudioMutation

Arguments

Name	Description
`date` - `Date!`	Date of the audio file
`duration` - `String!`	Duration of the audio file
`language` - `String!`	Language of the audio file
`name` - `String!`	Name of the audio file
`projectSlug` - `String!`	Slug of the project
`topList` - `String!`	Agenda list of the audio file
`typeOfDocument` - `String!`	Type of the document
`uniqueObjName` - `String!`	Unique Name of the audio file

Example

Query

mutation importAudio(
  $date: Date!,
  $duration: String!,
  $language: String!,
  $name: String!,
  $projectSlug: String!,
  $topList: String!,
  $typeOfDocument: String!,
  $uniqueObjName: String!
) {
  importAudio(
    date: $date,
    duration: $duration,
    language: $language,
    name: $name,
    projectSlug: $projectSlug,
    topList: $topList,
    typeOfDocument: $typeOfDocument,
    uniqueObjName: $uniqueObjName
  ) {
    protocol {
      ...ApiProtocolTypeFragment
    }
    success
  }
}

Variables

{
  "date": "2007-12-03",
  "duration": "abc123",
  "language": "abc123",
  "name": "abc123",
  "projectSlug": "xyz789",
  "topList": "abc123",
  "typeOfDocument": "abc123",
  "uniqueObjName": "xyz789"
}

Response

{
  "data": {
    "importAudio": {
      "protocol": ApiProtocolType,
      "success": false
    }
  }
}

Mutations

`recreateProtocolAfterSpeakerChange`

Response

Returns a RecreateProtocolMutation

Arguments

Name	Description
`protocolSlug` - `String!`	Name of the protocol to be recreated

Example

Query

mutation recreateProtocolAfterSpeakerChange($protocolSlug: String!) {
  recreateProtocolAfterSpeakerChange(protocolSlug: $protocolSlug) {
    success
  }
}

Variables

{"protocolSlug": "abc123"}

Response

{"data": {"recreateProtocolAfterSpeakerChange": {"success": true}}}

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` - `[SpeakerInput]!`	List of speakers to rename

Example

Query

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

Variables

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

Response

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

Mutations

`updateAgendaItemById`

Description

Update a specific agenda item by its ID. It validates the user's authentication using an API key passed in the request header and processes the provided agenda item data.

Response

Returns an UpdateAgendaItemByIdMutation

Arguments

Name	Description
`agendaItem` - `String!`	Agenda item to be updated

Example

Query

mutation updateAgendaItemById($agendaItem: String!) {
  updateAgendaItemById(agendaItem: $agendaItem) {
    agendaItem {
      ...ApiAgendaItemTypeFragment
    }
  }
}

Variables

{"agendaItem": "xyz789"}

Response

{
  "data": {
    "updateAgendaItemById": {
      "agendaItem": ApiAgendaItemType
    }
  }
}

Types

AWSUrlObject

Fields

Field Name	Description
`url` - `String`	AWS Url bucket name
`fields` - `GenericScalar`	{ "Content-Type": "multipart/form-data", "key": "test-audio.ogg", "x-amz-algorithm": "AWS4-HMAC-SHA256", "x-amz-credential": "", "x-amz-date": "20250512T105036Z", "policy": "", "x-amz-signature": "" }

Example

{
  "url": "xyz789",
  "fields": GenericScalar
}

Types

AgendaItemListType

Fields

Field Name	Description
`agendaItemList` - `[ApiAgendaItemType]`	List of agenda items
`taskList` - `[ApiTaskType]`	List of tasks

Example

{
  "agendaItemList": [ApiAgendaItemType],
  "taskList": [ApiTaskType]
}

Types

ApiAgendaItemType

Fields

Field Name	Description
`id` - `String`	ID of the agenda item
`classType` - `String`	Class type of the agenda item
`title` - `String`	Title of the agenda item
`textList` - `String`	{ "0": ["Die Software funktioniert gut."], "1": ["Bitte fügen Sie eine Chat-Funktion hinzu."], "2": ["Das Login über Google sollte schneller sein."] ... }
`resolutionList` - `[ResolutionInput]`	List of resolutions
`createdAt` - `DateTime`	Creation date of the agenda item
`updatedAt` - `DateTime`	Last update date of the agenda item

Example

{
  "id": "xyz789",
  "classType": "abc123",
  "title": "abc123",
  "textList": "xyz789",
  "resolutionList": [ResolutionInput],
  "createdAt": "2007-12-03T10:15:30Z",
  "updatedAt": "2007-12-03T10:15:30Z"
}

Types

ApiProjectType

Fields

Field Name	Description
`slug` - `String`	Slug of the project
`name` - `String`	Name of the project

Example

{
  "slug": "abc123",
  "name": "abc123"
}

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": "xyz789",
  "date": "abc123",
  "status": true,
  "editStage": false,
  "bucketAws": "xyz789"
}

Types

ApiSummaryPerSpeakerItemType

Fields

Field Name	Description
`speaker` - `String`	Name 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

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

Types

ApiTaskType

Fields

Field Name	Description
`id` - `String`	ID of the task
`text` - `String`	Text of the task
`date` - `String`	Date of the task
`assignedTo` - `String`	Assigned person for the task
`done` - `Boolean`	Task completion status
`createdAt` - `DateTime`	Creation date of the task
`updatedAt` - `DateTime`	Last update date of the task

Example

{
  "id": "abc123",
  "text": "abc123",
  "date": "abc123",
  "assignedTo": "abc123",
  "done": true,
  "createdAt": "2007-12-03T10:15:30Z",
  "updatedAt": "2007-12-03T10:15:30Z"
}

Types

ApiTextsegmentType

Fields

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

Example

{
  "id": "abc123",
  "speaker": "abc123",
  "textJson": [TranscriptSegment],
  "pos": 123
}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Types

CheckAnalysisResultsReturn

Fields

Field Name	Description
`currentDepth` - `Int`
`classType` - `String`

Example

{"currentDepth": 987, "classType": "xyz789"}

Types

CreateAnalysisMutation

Description

Create a new analysis 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.

Fields

Field Name	Description
`success` - `Boolean`

Example

{"success": false}

Types

CreateProjectMutation

Description

Create a new project. User can upload files into a project. Pass the resulting slug into the import audio mutation.

Fields

Field Name	Description
`project` - `ApiProjectType`

Example

{"project": ApiProjectType}

Types

Date

Description

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

Example

"2007-12-03"

Types

DateTime

Description

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

Example

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

Types

EditSpeakerDataType

Fields

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

Example

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

Types

Float

Description

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

Example

987.65

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

ImportAudioMutation

Description

Fields

Field Name	Description
`protocol` - `ApiProtocolType`	Protocol object
`success` - `Boolean`	Indicates if import audio was successful

Example

{"protocol": ApiProtocolType, "success": true}

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

RecreateProtocolMutation

Fields

Field Name	Description
`success` - `Boolean`	Indicates if recreation of protocol was successful

Example

{"success": false}

Types

RenameSpeakerInTextSegmentMutation

Description

Fields

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

Example

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

Types

ResolutionInput

Fields

Field Name	Description
`resolution` - `String`	Resolution text
`decision` - `String`	Decision text

Example

{
  "resolution": "abc123",
  "decision": "abc123"
}

Types

SpeakerInput

Fields

Input Field	Description
`old` - `String!`	Current name of the speaker
`new` - `String!`	New name for the speaker

Example

{
  "old": "xyz789",
  "new": "abc123"
}

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

"abc123"

Types

TextsegmentListType

Fields

Field Name	Description
`textsegmentList` - `[ApiTextsegmentType]`	List of text segments

Example

{"textsegmentList": [ApiTextsegmentType]}

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": 987.65,
  "endTime": 987.65
}

Types

UpdateAgendaItemByIdMutation

Description

Update a specific agenda item by its ID. It validates the user's authentication using an API key passed in the request header and processes the provided agenda item data.

Fields

Field Name	Description
`agendaItem` - `ApiAgendaItemType`	Updated agenda item

Example

{"agendaItem": ApiAgendaItemType}

Documentation by Anvil SpectaQL