logo
API docs by Redocly

Lumoa API (2.0.0)

Download OpenAPI specification:Download

E-mail: [email protected] URL: https://lumoa.me License: Apache 2.0 Terms of Service

Getting started

Lumoa API v2 is based on JSON:API specifications, please check out the specification for general questions on request formats and query params.

With the Lumoa API, you can import data to Lumoa and export data back to other services.

To get started with the API you will need to have an active Lumoa account to aquire an API key.

If you have any questions or catch an error with this documentation, please email us at help@lumoa.me.

API Location

Production URL should primarily be used, stage access can be granted for testing upcoming features.

PRODUCTION: https://feedback-api.lumoa.me/api/v2

STAGING: https://stage-feedback-api.lumoa.me/api/v2

Authentication

Lumoa API requires Authorization-header with value of Bearer <API KEY>. Example for the above formatting:
Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh2

You can generate the required API token in Lumoa from the collections page by clicking the "..." button on the table row and selecting "Manage tokens". Currently tokens can have Read, Write or Read+Write permissions and are always connected to a specific collection.
The API might support other filters, options and fields not mentioned in this documentation but it is not recommended to rely on these as they might change over time.

Conversation

Conversation endpoints are only for collections that are of conversation type.

The flow for conversations is to:

  1. Create a conversation and obtain the conversation id
  2. Create conversation texts to the conversation by using the id obtained in previous step
  3. Close the conversation after all texts have been added

After a conversation is marked as closed it will go through our analysis flow and be shown in the UI

Get conversations

Fetch conversations based on filters.

Authorizations:
Lumoa-API-Key
query Parameters
object

Filter conversations by parameters

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      }
    ]
}

Add conversation

Authorizations:
Lumoa-API-Key
Request Body schema: application/vnd.api+json
required

Creates a new conversation object to which you can add conversation texts

required
object
type
required
string
Value: "conversations"

The type member is used to describe resource objects that share common attributes and relationships.

required
object
date
string <date>

Date of the conversation, defaults to current time

externalId
string <= 100 characters

Unique id of the conversation in an external system

Array of objects <= 15 items

Meta information of the conversation which views can be filtered on

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "string",
    • "attributes": { }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "conversations",
    • "id": "6614d9eff9ede3d2118bca55",
    • "attributes": {
      },
    • "relationships": { },
    • "links": {},
    • "meta": { }
    }
}

Get conversation

Fetch conversations based on filters.

Authorizations:
Lumoa-API-Key
path Parameters
id
required
string

id of the conversation to get

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "conversations",
    • "id": "6614d9eff9ede3d2118bca55",
    • "attributes": {
      },
    • "relationships": { },
    • "links": {},
    • "meta": { }
    }
}

Update conversation

Use this endpoint to update the conversation object, i.e. when you want to mark it as CLOSED. You

Authorizations:
Lumoa-API-Key
path Parameters
id
required
string

id of the conversation to be marked as closed

Request Body schema: application/vnd.api+json
required

Updates the attributes of the conversation

required
object
type
required
string
Value: "conversations"

The type member is used to describe resource objects that share common attributes and relationships.

required
object
textCount
required
integer <= 100

Amount of conversationText objects the conversation has. Only required when closing the conversation.

status
required
string
Value: "CLOSED"

Status of the conversation, update conversation to closed when no more texts or updates will be done. Only required when closing the conversation.

Array of objects <= 15 items

Meta information of the conversation which views can be filtered on. If given this array will is a full update and will overwrite any existing tag values on the conversation.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "string",
    • "attributes": {
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "conversations",
    • "id": "6614d9eff9ede3d2118bca55",
    • "attributes": {
      },
    • "relationships": { },
    • "links": {},
    • "meta": { }
    }
}

Add conversation text

This endpoint is where you create text objects to a conversation object

Authorizations:
Lumoa-API-Key
Request Body schema: application/vnd.api+json
required
required
object
type
required
string
Value: "conversationTexts"

The type member is used to describe resource objects that share common attributes and relationships.

required
object
comment
required
string <= 1000 characters

text of the conversation

actor
required
string <= 50 characters

the actor writing the text, ie. customer, agent, bot etc

index
required
integer <= 100

the position of the text in the conversation

required
object
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "string",
    • "attributes": {
      },
    • "relationships": {
      }
    }
}

Response samples

Content type
application/vnd.api+json
{}

Get conversation texts

Fetch conversations based on filters.

Authorizations:
Lumoa-API-Key
path Parameters
id
required
string

the id of the conversation whose texts are returned

Responses

Response samples

Content type
application/vnd.api+json
{}

Audio Transcription

Creates a conversation from an audio file.

It is highly recommended to provide the audioLanguage parameter for the best results, otherwise the audio language will be automatically detected and the results may vary.

Authorizations:
Lumoa-API-Key
Request Body schema: multipart/form-data
required

Creates a conversation from an audio file

file
required
string <binary>

The audio file of the conversation

audioLanguage
string

The language being spoken in the audio file. An IETF BCP 47 language tag, for example: fi-FI, en-US, sv-SE

date
string <date>

Date of the conversation, defaults to current time

externalId
string <= 100 characters

Unique id of the conversation in an external system

Array of objects <= 15 items

Meta information of the conversation which views can be filtered on

Array (<= 15 items)
name
required
string <= 50 characters
value
required
string or number <= 50 characters

Responses

Request samples

Content type
multipart/form-data
Example

Conversation transcription with cURL

curl --location --request POST 'https://feedback-api.lumoa.me/api/v2/conversations/audio' \
--header 'Authorization: Bearer <Lumoa-API-key>' \
--form 'file=@"/path/to/the/audio/file.wav"' \
--form 'audioLanguage="en-US"' \'
--form 'tags="[{\"name\":\"gender\",\"value\":\"male\"}]"' \
--form 'externalId="8afbe28f-8e09-4ec6-84f7-4557e749af8c"'

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "conversations",
    • "id": "6614d9eff9ede3d2118bca55",
    • "attributes": {
      },
    • "relationships": { },
    • "links": {},
    • "meta": { }
    }
}