{
"openapi": "3.0.4",
"info": {
"title": "Kimola API",
"description": "All the public API methods related to your Kimola services. Don't forget to authenticate with your API Key first.",
"version": "v1"
},
"paths": {
"/v1/Agents/appsumo/authentication": {
"post": {
"tags": [
"Agents"
],
"parameters": [
{
"name": "username",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "password",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Agents/appsumo/cognitive/notification": {
"post": {
"tags": [
"Agents"
],
"parameters": [
{
"name": "plan_id",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "uuid",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "activation_email",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "invoice_item_uuid",
"in": "query",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string"
}
}
},
"encoding": {
"action": {
"style": "form"
}
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Airsets/sources": {
"get": {
"tags": [
"Airsets"
],
"parameters": [
{
"name": "host",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Airsets": {
"get": {
"tags": [
"Airsets"
],
"parameters": [
{
"name": "pageIndex",
"in": "query",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
},
"post": {
"tags": [
"Airsets"
],
"parameters": [
{
"name": "index",
"in": "query",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "code",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "url",
"in": "query",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json-patch+json": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
},
"application/*+json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Feeds/{code}": {
"get": {
"tags": [
"Feeds"
],
"summary": "Retrieves a Feed by its unique code.",
"description": "A Feed in Kimola represents a stream of customer feedback gathered around a defined topic, keyword set, brand, or link.\n\nThis endpoint returns the details of a single Feed when the provided code matches an existing Feed.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "The unique identifier of the Feed.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns the requested Feed."
},
"404": {
"description": "No Feed was found for the specified code."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Feeds": {
"get": {
"tags": [
"Feeds"
],
"summary": "Retrieves a paginated list of Feeds for the authenticated client.",
"description": "This endpoint returns the Feeds available to the current client account.\n\nResults can be filtered by Feed name and paginated using the optional `pageSize` and `pageIndex` parameters.",
"parameters": [
{
"name": "pageSize",
"in": "query",
"description": "Optional number of Feeds to return per page.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "pageIndex",
"in": "query",
"description": "Optional zero-based page index.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "name",
"in": "query",
"description": "Optional Feed name filter.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns the total count and the list of matching Feeds."
},
"406": {
"description": "The Feeds could not be retrieved."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Feeds/{code}/reports": {
"get": {
"tags": [
"Feeds"
],
"summary": "Retrieves a paginated list of Reports generated for a specific Feed.",
"description": "Reports in Kimola are generated outputs derived from a Feed and provide structured insight into the collected customer feedback.\n\nThis endpoint returns the Reports associated with the specified Feed and supports optional pagination.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "The unique identifier of the Feed.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "pageSize",
"in": "query",
"description": "Optional number of Reports to return per page.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "pageIndex",
"in": "query",
"description": "Optional zero-based page index.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns the total count and the list of Reports for the Feed."
},
"406": {
"description": "The Reports could not be retrieved."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Feeds/{code}/reports/recent": {
"get": {
"tags": [
"Feeds"
],
"summary": "Retrieves the most recent Report generated for a specific Feed.",
"description": "This is a convenient endpoint for accessing the latest available Report of a Feed with a single request,\nwithout listing and sorting all associated Reports.\n\nIt is especially useful when the current state of a Feed is needed quickly.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "The unique identifier of the Feed.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns the most recent Report for the Feed."
},
"404": {
"description": "The Feed does not have any Reports."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/livez": {
"get": {
"tags": [
"GoldenBridge.API.Public"
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Presets": {
"get": {
"tags": [
"Presets"
],
"summary": "Retrieves a paginated list of pretrained AI models (Presets).",
"description": "Presets represent pretrained AI models available in Kimola. Results can be filtered by `type` and `category`.\n\nSupported `type` values: `Extractor`, `Classifier`.\n \nSupported `category` values: `Sentiment Classifier`, `Content Classifier`.",
"parameters": [
{
"name": "pageSize",
"in": "query",
"description": "Number of presets per page. Defaults to 10 and cannot be larger than 10.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "pageIndex",
"in": "query",
"description": "Zero-based page index. Defaults to 0.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "type",
"in": "query",
"description": "Optional filter by type of preset (e.g., `Extractor` or `Classifier`).",
"schema": {
"type": "string"
}
},
{
"name": "category",
"in": "query",
"description": "Optional filter by category of Preset (e.g., `Sentiment Classifier` or `Content Classifier`).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns an object with `total` and `items[]`."
},
"404": {
"description": "No presets found for the given criteria."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Presets/{key}": {
"get": {
"tags": [
"Presets"
],
"summary": "Retrieves a single pretrained AI model (Preset) by its unique key.",
"description": "Presets represent pretrained AI models available in Kimola. Each preset is identified by a 24‑character key.",
"parameters": [
{
"name": "key",
"in": "path",
"description": "The 24‑character unique key that identifies the preset.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns the requested Preset object."
},
"404": {
"description": "No preset found with the given key."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Presets/{key}/labels": {
"get": {
"tags": [
"Presets"
],
"summary": "Retrieves the list of labels defined for a pretrained AI model (Preset).",
"description": "Labels represent the possible outputs when the AI model predicts a label based on an input text. \n \nEach label consists of a `name` and a `description`.\nThe `name` provides a short identifier, while the `description` explains the classification context in more detail. \n\nFor AI models that do not have labels by nature (e.g., Extractors), this method returns `null`. \nIf labels are expected for a given preset type but none are defined, it returns an empty array.",
"parameters": [
{
"name": "key",
"in": "path",
"description": "The 24‑character unique key that identifies the preset.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns an array of labels with `name` and `description`."
},
"404": {
"description": "No preset or labels found for the given key."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Presets/{key}/predictions": {
"post": {
"tags": [
"Presets"
],
"summary": "Predicts labels for a given text using the specified pretrained AI model (Preset).",
"description": "This endpoint returns the AI model’s predicted labels for the provided `text`.\n \nlanguage (optional) — Two‑letter, lowercase ISO 639‑1 language code for the input text\n(e.g., `\"en\"`, `\"tr\"`, `\"es\"`, `\"de\"`, `\"fr\"`). Providing this lets Kimola skip\nautomatic language detection and apply the most accurate prediction pipeline for that language. This is\nespecially helpful for short texts or texts with typos. If omitted, Kimola handles language detection internally. \n\naspectBased (optional) — When `true`, analyzes the text by topics/aspects and returns multiple\nlabels with their sentiment values (aspect‑based classification). When `false` or omitted, returns the dominant\nlabel prediction. Note: setting `aspectBased=true` consumes 2 queries (classification + sentiment),\notherwise it consumes 1 query. \n\ntext (required) — The raw input text to classify. \nIf the AI model finds none of the labels relevant to the given text, it returns a special label `None`.",
"parameters": [
{
"name": "key",
"in": "path",
"description": "The 24‑character unique key of the preset to use for prediction.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "language",
"in": "query",
"description": "Optional ISO 639‑1 two‑letter lowercase language code (e.g., `\"en\"`, `\"tr\"`, `\"es\"`).",
"schema": {
"type": "string"
}
},
{
"name": "aspectBased",
"in": "query",
"description": "Optional flag to enable aspect‑based classification with per‑label sentiment.",
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"description": "The input text to classify.",
"content": {
"application/json-patch+json": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
},
"application/*+json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation. Returns predicted label results."
},
"400": {
"description": "Invalid request (e.g., missing or empty `text`)."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Queries": {
"get": {
"tags": [
"Queries"
],
"summary": "Retrieves a paginated list of Queries consumed within the specified date range.",
"description": "In Kimola, a `Query` represents a unit of package consumption (e.g., text classification,\nscraping, or tracking tasks such as collecting customer feedback). \n\nThis endpoint allows developers to review Queries spent by their account over a given period,\nwith optional pagination parameters. \n \npageIndex: Defaults to `0` if not provided. \npageSize: Defaults to `10` and cannot exceed `10`. \nstartDate: If `null`, defaults to one month before the current UTC time. \nendDate: If `null`, defaults to the current UTC time.",
"parameters": [
{
"name": "pageIndex",
"in": "query",
"description": "Zero-based page index. Defaults to 0.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "pageSize",
"in": "query",
"description": "Number of queries per page. Defaults to 10 and cannot be larger than 10.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "startDate",
"in": "query",
"description": "Optional UTC start date for filtering queries. Defaults to one month before now if not provided.",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "endDate",
"in": "query",
"description": "Optional UTC end date for filtering queries. Defaults to current time if not provided.",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns a paginated array of Queries."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Queries/statistics": {
"get": {
"tags": [
"Queries"
],
"summary": "Returns Query consumption statistics grouped by category within the specified date range.",
"description": "In Kimola, a `Query` is the unit of package consumption (e.g., text classification, tracking, scraping).\nThis endpoint aggregates Queries into the categories `Classification`, `Tracking`, and `Scraping`\nand returns their counts and shares for the given period.\n\nstartDate: if `null`, defaults to one month before the current UTC time. \nendDate: if `null`, defaults to the current UTC time.\n\nAll dates are interpreted as UTC.",
"parameters": [
{
"name": "startDate",
"in": "query",
"description": "Optional UTC start date. Defaults to one month before now when `null`.",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "endDate",
"in": "query",
"description": "Optional UTC end date. Defaults to current UTC time when `null`.",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns an array of category statistics."
},
"500": {
"description": "An unexpected error occurred."
}
}
}
},
"/v1/Reports/{code}": {
"get": {
"tags": [
"Reports"
],
"summary": "Retrieves a single Report by its unique identifier.",
"description": "A Report represents the structured analysis generated from a Feed in Kimola. This endpoint returns the report metadata and core properties used to inspect the research output before accessing its analyses.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "The unique identifier of the Report.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Reports": {
"get": {
"tags": [
"Reports"
],
"summary": "Retrieves a paginated list of Reports available to the authenticated client.",
"description": "This endpoint lets you browse the Reports in your account and optionally filter them by name.",
"parameters": [
{
"name": "pageSize",
"in": "query",
"description": "The number of Reports to return per page.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "pageIndex",
"in": "query",
"description": "The zero-based index of the results page.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "name",
"in": "query",
"description": "An optional name filter to narrow the returned Reports.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Reports/{code}/analyses": {
"get": {
"tags": [
"Reports"
],
"summary": "Retrieves the Analyses available for a specific Report.",
"description": "This endpoint returns the analysis items associated with the specified Report, such as Executive Summary, Motivations, Pain Points, Unmet Needs, and similar analytical outputs.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "The unique identifier of the Report.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Reports/{code}/analyses/{slug}": {
"get": {
"tags": [
"Reports"
],
"summary": "Retrieves a single Analysis for a specific Report by its slug.",
"description": "Analyses are the structured insight sections generated within a Report in Kimola.\nThis endpoint returns a single Analysis identified by its slug, such as Executive Summary, Motivations, Pain Points, Unmet Needs, or other analytical sections available in the Report.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "The unique identifier of the Report.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "slug",
"in": "path",
"description": "The unique slug identifier of the Analysis within the Report.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Reports/{code}/analyses/{slug}/data": {
"get": {
"tags": [
"Reports"
],
"summary": "Retrieves the structured data produced by a specific Analysis within a Report.",
"description": "Analyses in Kimola generate structured outputs such as Executive Summary, Motivations, Pain Points, Unmet Needs, and other insight datasets. This endpoint returns the full structured result contained in the `data` field of the specified Analysis.",
"parameters": [
{
"name": "code",
"in": "path",
"description": "The unique identifier of the Report.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "slug",
"in": "path",
"description": "The unique slug identifier of the Analysis within the Report.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Reports/{code}/statistics": {
"get": {
"tags": [
"Reports"
],
"parameters": [
{
"name": "code",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v1/Subscription/usage": {
"get": {
"tags": [
"Subscription"
],
"summary": "Retrieves the current subscription usage for the logged-in user.",
"description": "This endpoint returns how many subscription resources have been consumed within the user's plan.\n\nUsage is reported for items such as Queries, Models, Keywords, and Links. \n\nThe `date` parameter is optional.\nIf `null`, defaults to the current UTC time and shows usage for the active subscription period.\nIf provided, allows fetching usage information for previous subscription periods.",
"parameters": [
{
"name": "date",
"in": "query",
"description": "Optional UTC date indicating which subscription period to check. \nDefaults to `DateTime.UtcNow` if not specified.",
"schema": {
"type": "string",
"format": "date-time"
}
}
],
"responses": {
"200": {
"description": "Successful operation. Returns subscription usage data for the specified period."
},
"500": {
"description": "An unexpected error occurred while retrieving usage data."
}
}
}
}
},
"components": {
"securitySchemes": {
"Bearer": {
"type": "apiKey",
"description": "Kimola API's Authorization header using the Bearer scheme. Enter your API key as shown \"Bearer \"",
"name": "Authorization",
"in": "header"
}
}
},
"security": [
{
"Bearer": [ ]
}
]
}