Fluentic API v1 (2025-03-12)

Download OpenAPI specification:Download

Fluentic API v1 Documentation

Category Detection

Create category detection batch

Create a batch job for detecting categories of text documents.

The response will contain a signed URL for uploading the batch input file. Use the upload URL to upload the input file.

The file to upload should be a valid JSON file containing an array of category detection content objects containing the content string, use case name, and an optional external identifier, for example:

[
  {
    "content": "My package was delivered late",
    "external_id": "123456",
  },
  {
    "content": "Thank you for the fast delivery",
    "external_id": "234567",
  },
  {
    "content": "The microwave oven works great!",
    "external_id": "345678",
  }
]

You have 2 options for getting the results:

Polling: You can call the /v1/categories/batch/{id}/status endpoint to check the status of the batch job. When the job is completed, you can download the results using the signed download URL provided in the response.
Webhook: You can provide a callback URL in the request body to receive a POST request with the results when the job is completed. The webhook POST request will contain the same payload as the response of /v1/categories/batch/{id}/status endpoint.

When the job is completed, you can download the results using the signed download URL provided in the response.

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

use_case

required

string

Name of the categorization use case

callback_url

string or null <uri>

URL to send the result to

source_language

string

Source language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

external_id

string

Deprecated

Deprecated: Use meta.external_id instead.

External ID provided by the API user. This ID can be used to identify the job in external systems.

suggest_labels

boolean

If true, the API will suggest new categorization labels.

Responses

Response Schema: application/json

id

required

string <uuid>

ID of the category detection job

required

object

Generated URL to upload the file to

url required	string Signed URL to AWS S3
valid_until required	string URL expiration date (ISO format)

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

Request samples

Payload

Content type

application/json

{"use_case": "Products and Delivery",
"callback_url": "https://example.com",
"source_language": "en-gb",
"meta": {"external_id": "123456789"
},
"suggest_labels": true
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"upload_url": {"url": "https://example.com",
"valid_until": "2022-01-01T00:00:00Z"
},
"meta": {"external_id": "123456789"
}
}

Get category detection batch job status

Get the status of a category detection batch job. When the job is done, the response will contain the status of the job and a signed URL for downloading the results. If the suggest_categories parameter was set to true in the Create Batch request, the response will also contain a list of suggested categories.

Example of the downloaded results:

{
  "detection_results": [
    {
      "content": "My package was delivered late",
      "external_id": "123456",
      "categories": ["Delivery"],
      "suggested_categories": [],
    },
    {
      "content": "Thank you for the fast delivery",
      "external_id": "234567",
      "categories": ["Delivery"],
      "suggested_categories": [],
    },
    {
      "content": "The microwave oven works great!",
      "external_id": "345678",
      "categories": [],
      "suggested_categories": ["Product Quality"],
    }
  ],
  "suggested_categories": ["Product Quality"]
}

path Parameters

id

required

string <uuid>

ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response Schema: application/json

id

required

string <uuid>

ID of the category detection job

status

required

string

Enum: "AWAITING_UPLOAD" "PROCESSING" "DONE" "ERROR"

Status of the category detection job

required

object or null

URL to download the result

url required	string Signed URL to AWS S3
valid_until required	string URL expiration date (ISO format)

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "DONE",
"download_url": {"url": "https://example.com",
"valid_until": "2022-01-01T00:00:00Z"
},
"meta": {"external_id": "123456789"
}
}

Detect categories

This API endpoint is designed to detect categories within the provided text content based on specified interests. It requires authentication and allows clients to submit text for analysis against a list of categories.

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

content

required

string

Content to be categorized

use_case

required

string

Identifier of the categorization use case. Must be a valid use case name and must match the name that it was added with (case-sensitive). Use the Category Detection Management APIs to manage use cases.

source_language

string

Source language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).

minimum_confidence

integer [ 0 .. 100 ]

Minimum confidence level for the detected categories

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

external_id

string

Deprecated

Deprecated: Use meta.external_id instead.

External ID provided by the API user. This ID can be used to identify the job in external systems.

Responses

Response Schema: application/json

id

required

string <uuid>

ID of the category detection job

Request samples

Payload

Content type

application/json

{"content": "I love this product!",
"use_case": "Customer Feedback",
"source_language": "en-gb",
"minimum_confidence": 60,
"meta": {"external_id": "123456789"
},
"external_id": "123456"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"categories": ["string"
],
"source_language": "en-gb",
"meta": {"external_id": "123456789"
},
"error": "string"
}

Category Detection Management

List use cases

List category detection use cases

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response Schema: application/json

required

Array of objects

List of use cases

Array

id required	string <uuid> The ID of the use case
name required	string Name of the use case
description required	string or null Description of the use case

Response samples

Content type

application/json

{"use_cases": [{"id": "f7b3b3b4-3b7b-4b3b-8b3b-3b7b3b7b3b7b",
"name": "Customer Feedback",
"description": "Feedback from customers"
}
]
}

Create a use case

Create a new category detection use case

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

name required	string Name of the use case
description	string or null Description of the use case

Responses

Response Schema: application/json

id required	string <uuid> The ID of the added use case
name required	string Name of the use case
description required	string or null Description of the use case

Request samples

Payload

Content type

application/json

{"name": "Customer Feedback",
"description": "Feedback from customers"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Customer Feedback",
"description": "Feedback from customers"
}

Get use case

Get category detection use case details

path Parameters

id

required

string <uuid>

ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response Schema: application/json

id

required

string <uuid>

The ID of the use case

name

required

string

Name of the use case

description

required

string or null

Description of the use case

required

Array of objects

List of label details for the use case

Array

id required	string <uuid> The ID of the label
use_case_id required	string <uuid> The ID of the use case
label required	string Name of the label
description required	string or null Description of the label
examples required	Array of strings or null Examples for the label
rules	Array of strings or null Rules for the use case label

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Customer Feedback",
"description": "Feedback from customers",
"labels": [{"id": "f7b3b3b4-3b7b-4b3b-8b3b-3b7b3b7b3b7b",
"use_case_id": "f7b3b3b4-3b7b-4b3b-8b3b-3b7b3b7b3b7b",
"label": "Late Delivery",
"description": "Delivery was late",
"examples": ["Delivery was late",
"I had to wait for the package"
]
}
]
}

Update use case

Update category detection use case details

path Parameters

id

required

string <uuid>

ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

name	string Name of the use case
description	string or null Description of the use case

Responses

Response Schema: application/json

id required	string <uuid> The ID of the use case
name required	string Name of the use case
description required	string or null Description of the use case

Request samples

Payload

Content type

application/json

{"name": "Customer Feedback",
"description": "Feedback from customers"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Customer Feedback",
"description": "Feedback from customers"
}

Delete use case

Delete category detection use case

path Parameters

id

required

string <uuid>

ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response samples

Content type

application/json

{"error": "Validation error: Invalid uuid at \"id\"",
"statusCode": 400
}

Add use case label

Add category detection use case label

path Parameters

id

required

string <uuid>

ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

label required	string <= 255 characters Name of the label
description	string or null <= 255 characters Description of the label
rules	Array of strings or null Additional rules for the label matching
examples	Array of strings or null Examples for the label

Responses

Response Schema: application/json

id required	string <uuid> The ID of the label
use_case_id required	string <uuid> The ID of the use case
label required	string Name of the label
description required	string or null Description of the label
examples required	Array of strings or null Examples for the label
rules	Array of strings or null Rules for the use case label

Request samples

Payload

Content type

application/json

{"label": "Late Delivery",
"description": "Delivery was late",
"rules": ["Applies to any messages mentioning late delivery",
"Should not match if the delivery was failed completely"
],
"examples": ["Delivery was late",
"I had to wait for the package"
]
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"use_case_id": "a1c46a91-0cf6-4c46-86d4-5a282022bcea",
"label": "Late Delivery",
"description": "Delivery was late",
"rules": ["Applies to any messages mentioning late delivery"
],
"examples": ["Delivery was late",
"I had to wait for the package"
]
}

Update use case

Update category detection use case details

path Parameters

id required	string <uuid> ID (UUID v4)
label_id required	string <uuid> Label ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

label required	string <= 255 characters Name of the label
description	string or null <= 255 characters Description of the label
rules	Array of strings or null Additional rules for the label matching
examples	Array of strings or null Examples for the label

Responses

Response Schema: application/json

id required	string <uuid> The ID of the label
use_case_id required	string <uuid> The ID of the use case
label required	string Name of the label
description required	string or null Description of the label
examples required	Array of strings or null Examples for the label
rules	Array of strings or null Rules for the use case label

Request samples

Payload

Content type

application/json

{"label": "Late Delivery",
"description": "Delivery was late",
"rules": ["Applies to any messages mentioning late delivery",
"Should not match if the delivery was failed completely"
],
"examples": ["Delivery was late",
"I had to wait for the package"
]
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"use_case_id": "a1c46a91-0cf6-4c46-86d4-5a282022bcea",
"label": "Late Delivery",
"description": "Delivery was late",
"rules": ["Applies to any messages mentioning late delivery"
],
"examples": ["Delivery was late",
"I had to wait for the package"
]
}

Delete use case

Delete category detection use case

path Parameters

id required	string <uuid> ID (UUID v4)
label_id required	string <uuid> Label ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response samples

Content type

application/json

{"error": "Validation error: Invalid uuid at \"id\"",
"statusCode": 400
}

Languages

Get languages

Get languages supported by Fluentic API

Responses

Response Schema: application/json

required

Array of objects

Array of supported languages

Array

code required	string ISO 639-1 language code
name required	string Language name (in English)
direction required	string Enum: "ltr" "rtl" Text direction
source	boolean or null Whether the language is a source language
target	boolean or null Whether the language is a target language

Response samples

Content type

application/json

{"languages": [{"code": "fi-fi",
"name": "Finnish",
"direction": "ltr",
"source": true,
"target": true
}
]
}

Sentiment Analysis

Analyse sentiment

This API endpoint performs sentiment analysis on the provided text content, delivering insights into the overall sentiment expressed in the text. It requires authentication and supports analysis in various languages as specified by the source language code.

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

content

required

string

Content to be analyzed

source_language

string

Source language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

external_id

string

Deprecated

Deprecated: Use meta.external_id instead.

External ID provided by the API user. This ID can be used to identify the job in external systems.

Responses

Response Schema: application/json

id

required

string <uuid>

ID of the sentiment analysis job

required

object

Overall sentiment of the text

label

string

Enum: "positive" "neutral" "negative" "mixed"

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

error

string

Error message in case of an error

Request samples

Payload

Content type

application/json

{"content": "I love this product!",
"source_language": "en-gb",
"meta": {"external_id": "123456789"
},
"external_id": "123456"
}

Response samples

Content type

application/json

{"id": "f7b3b3b4-3b7b-4b3b-8b3b-3b7b3b7b3b7b",
"overall_sentiment": {"label": "positive"
},
"meta": {"external_id": "123456789"
}
}

Create sentiment analysis batch

Create a batch job for sentiment analysis.

The response will contain a signed URL for uploading the batch input file. Use the upload URL to upload the input file, then call the /v1/sentiment/batch/{id}/status endpoint to check the status of the batch job. When the job is completed, you can download the results using the signed download URL provided in the response.

The file to upload should be a valid JSON file containing an array of content objects to analyze containing the content string, and an optional external identifier, for example:

[
  {
    "content": "My package was delivered late",
    "external_id": "123-abc-34567",
  },
  {
    "content": "Thank you for the fast delivery",
    "external_id": "432-dfe-98765",
  }
]

You have 2 options for getting the results:

Polling: You can call the /v1/sentiment/batch/{id}/status to check the status of the batch job. When the job is completed, you can download the results using the signed download URL provided in the response.
Webhook: You can provide a callback URL in the request body to receive a POST request with the results when the job is completed. The webhook POST request will contain the same payload as the response of /v1/sentiment/batch/{id}/status endpoint.

When the job is completed, you can download the results using the signed download URL provided in the response.

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

callback_url

string or null <uri>

URL to send the result to

source_language

string

Source language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

external_id

string

Deprecated

Deprecated: Use meta.external_id instead.

External ID provided by the API user. This ID can be used to identify the job in external systems.

Responses

Response Schema: application/json

id

required

string <uuid>

ID of the sentiment analysis job

required

object

Generated URL to use for uploading the file to AWS S3

url required	string Signed URL to AWS S3
valid_until required	string URL expiration date (ISO format)

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

Request samples

Payload

Content type

application/json

{"callback_url": "https://example.com",
"source_language": "en-gb",
"meta": {"external_id": "123456789"
}
}

Response samples

Content type

application/json

{"id": "f7b3b3b4-3b7b-4b3b-8b3b-3b7b3b7b3b7b",
"upload_url": {"url": "https://example.com",
"valid_until": "2022-01-01T00:00:00Z"
},
"meta": {"external_id": "123456789"
}
}

Get sentiment analysis batch status

path Parameters

id

required

string <uuid>

ID (UUID v4)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response Schema: application/json

id

required

string <uuid>

ID of the sentiment analysis job

status

required

string

Enum: "AWAITING_UPLOAD" "PROCESSING" "DONE" "ERROR"

Status of the sentiment analysis job

required

object or null

Signed URL to download the result file from AWS S3

url required	string Signed URL to AWS S3
valid_until required	string URL expiration date (ISO format)

object

Additional metadata to be passed through to the response.

property name*

additional property

any or null

Response samples

Content type

application/json

{"id": "f7b3b3b4-3b7b-4b3b-8b3b-3b7b3b7b3b7b",
"status": "DONE",
"download_url": {"url": "https://example.com",
"valid_until": "2022-01-01T00:00:00Z"
},
"meta": {"external_id": "123456789"
}
}

Translation

Translate text

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Request Body schema: application/json

required

Array of objects

Array of content items to be translated

Array

id required	string Unique identifier for the content item
text required	string Text to be translated

required

object

target required	string Target language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).
source	string Source language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).

formality

string

Enum: "FORMAL" "INFORMAL" "PREFER_FORMAL" "PREFER_INFORMAL" "DEFAULT"

callback_url

string

Callback URL to be called for 'Done' and 'Error' statuses

object

Translation metadata

property name*

additional property

any or null

Responses

Response Schema: application/json

job_id

required

string

Translation job id (uuid)

status

required

string

Enum: "Analyzing" "Translating" "ImprovingQuality" "Done" "Error" "Canceled" "LanguageNotDetected"

Translation job status

required

object

get_translation

required

string

URL to get translation result

object

Translation metadata

property name*

additional property

any or null

Request samples

Payload

Content type

application/json

{"contents": [{"id": "title",
"text": "Hello world"
},
{"id": "text-field",
"text": "This is a translation"
}
],
"language": {"source": "en-gb",
"target": "fi-fi"
},
"formality": "FORMAL",
"callback_url": "string",
"meta": {"external_id": "abc123def456",
"all_key_value_pairs": "are allowed"
}
}

Response samples

Content type

application/json

{"job_id": "09e4ba01-d604-4dc2-88f4-490245c9bbe2",
"status": "Done",
"links": {"get_translation": "https://api.fluentic.com/v1/translation/09e4ba01-d604-4dc2-88f4-490245c9bbe2"
},
"meta": {"external_id": "abc123def456",
"all_key_value_pairs": "are allowed"
}
}

Get translation results

Get translation results or status of a translation job

path Parameters

jobId

required

string

Example: 09e4ba01-d604-4dc2-88f4-490245c9bbe2

Translation job id (uuid)

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response Schema: application/json

job_id

required

string

Translation job id (uuid)

required

object

source required	string Source language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).
target required	string Target language code. Consists of language code (ISO 639-1) and country code (ISO 3166-1 alpha-2).

status

required

string

Enum: "Analyzing" "Translating" "ImprovingQuality" "Done" "Error" "Canceled" "LanguageNotDetected"

Translation job status

Array of objects

Array of translated content items

Array

id required	string Unique identifier for the content item
text required	string Text to be translated

object

Translation metadata

property name*

additional property

any or null

Response samples

Content type

application/json

{"job_id": "09e4ba01-d604-4dc2-88f4-490245c9bbe2",
"translations": [{"id": "title",
"text": "Hei maailma"
},
{"id": "text-field",
"text": "Tämä on käännös"
}
],
"language": {"source": "en-gb",
"target": "fi-fi"
},
"status": "Done",
"meta": {"external_id": "abc123def456",
"all_key_value_pairs": "are allowed"
}
}

Usage Report

Get usage report

Get usage report of the translation service. If no date range is provided, the default range is the last 24 months.

query Parameters

type	string Default: "monthly" Enum: "daily" "monthly" Example: type=monthly Report type, one of: 'daily', 'monthly'
start_date	string^\d{4}-\d{2}-\d{2}$ Example: start_date=2021-01-01 Report start date (inclusive), format: 'YYYY-MM-DD'
end_date	string^\d{4}-\d{2}-\d{2}$ Example: end_date=2021-01-31 Report end date (inclusive), format: 'YYYY-MM-DD'
source_language	string Example: source_language=en-gb Source language code
	Array of strings or string Example: order_type=email&order_type=chat The usage can be filtered based on `order_type` parameter: `email` for normal translation orders, such as outgoing emails `chat` for chat translations, `batch` for batch translations, `pdf` for PDF translations, `nlp` for NLP services such as sentiment analysis and categorization.

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response Schema: application/json

columns

required

Array of strings

Report columns

required

Array of objects

Report data

Array

source_lang required	string or null Source language
target_lang required	string or null Target language
order_type required	string Order type
year required	integer > 0 Year
month required	integer > 0 Month of year
day required	integer or null > 0 Day of month (null for monthly reports)
count required	integer >= 0 Total count of orders
quantity_sum required	integer >= 0 Total quantity of billed items in orders

Response samples

Content type

application/json

{"columns": ["source_lang",
"target_lang",
"order_type",
"year",
"month",
"day",
"count",
"quantity_sum"
],
"data": [{"source_lang": "de-de",
"target_lang": "en-gb",
"order_type": "email",
"year": 2021,
"month": 9,
"day": 17,
"count": 123,
"quantity_sum": 582
}
]
}

Get current usage

Returns a report of credits used in the current billing period

header Parameters

Authorization

required

string

Example: 123abc456def789abc012def345abc678

Authorization header containing the API key

Responses

Response Schema: application/json

required

Array of objects

Array

product required	string Product name
current_tier_credits required	number Amount of credits included in the current tier
credits_used required	number Credits used

period_start

required

string

Billing period start date

period_end

required

string

Billing period end date

Response samples

Content type

application/json

{"usage": [{"product": "Sentiment Analysis & Categorization Plan",
"current_tier_credits": 2500,
"credits_used": 4
},
{"product": "Messages",
"current_tier_credits": 200,
"credits_used": 2
}
],
"period_start": "2024-09-23T12:45:16.000Z",
"period_end": "2024-10-23T12:45:16.000Z"
}