Feelback API Reference

General information

API Client

For Javascript or Typescript environments, the preferred way to interact with the Feelback API is via the client package @feelback/api-client.


You can install it with your preferred package manager:

npm install @feelback/api-client

It’s a very lightweight package, fully typed, useful to call the Feelback API with a smooth and idiomatic javascript syntax.

import createClient from "@feelback/api-client";

const client = createClient({ endpoint: "https://api.feelback.dev/v0" });

const projects = await client.projects.list();
const feelbacks = await client.feelbacks.list({
  projectId: projects[0].id,
  state: "active"
});

Configure the api-key for the authentication:

import createClient, { AuthHeader } from "@feelback/api-client";

const client = createClient({ endpoint: "https://api.feelback.dev/v0" });
client.use(AuthHeader("API-KEY", "your-api-key"));

API Endpoint

The current API endpoint to use in your calls:

https://api.feelback.dev/v0

Plain HTTP requests

For other environments or if you prefer to call the Feelback API with a technology of your choice, you can call the HTTP endpoints directly.


The Feelback API is an httpc API. An httpc API follows the httpc call convention which is a way to structure the HTTP request in a way to resemble a function call.


The short summary of the convention is:


Some code examples to see the convention in use:

const endpoint = "https://api.feelback.dev/v0";

function listProject() {
  return apiCall("/projects/list");
}

function getProject(id) {
  return apiCall("/projects/get", id);
}

function saveProject(id, data) {
  return apiCall("/projects/save", id, data);
}

/** General helper to make any api call */
async function apiCall(path, ...params) {
  const response = await fetch(endpoint + path, {
      method: "POST",
      headers: {
          "content-type": "application/json"
      },
      body: JSON.stringify(params) // <-- parameters are sent as JSON array
  });

  return await response.json();
}

Permissions

The Feelback API defines 3 permission levels:

Authentication

The Feelback API support authentication via the API-KEY scheme.

//
// IMPORTANT
//
// Do not use this code on the browser
// as it will leak your key to anyone
// Call protected endpoints with an api-key only server-side
//

import createClient, { AuthHeader } from "@feelback/api-client";

const apiKey = "your api key";

const client = createClient({ endpoint: "https://api.feelback.dev/v0" });
client.use(AuthHeader("API-KEY", apiKey));

Endpoints

/projects

/projects/get

Retrieve a {@link Project} by id

authorization viewer
parameters
#0: id

The project id

type string
required Yes
returns Project

/projects/list

authorization none
parameters
#0: query
required No
returns
object {
items
type
Array< Project >
required Yes
count
type number
required Yes
}

/projects/lookup

authorization none
parameters
#0: text
type string
required Yes
#1: filters
required No
returns any

/projects/create

authorization none
parameters
#0: data
type
object {
name
type string
required Yes
min length 1
max length 50
description
type string
required No
max length 255
}
required Yes
returns Project

/projects/save

authorization none
parameters
#0: id
type string
required Yes
#1: data
type
object {
name
type string
required No
min length 1
max length 50
description
type string
required No
max length 255
}
required Yes
returns Project

/projects/archive

authorization none
parameters
#0: id
type string
required Yes
returns Project

/projects/getStats

authorization none
parameters
#0: id
type string
required Yes
#1: filter
required No

/sets

/sets/get

authorization none
parameters
#0: id
type string
required Yes
returns ContentSet

/sets/list

authorization none
parameters
#0: query
required No
returns
object {
items
type
Array< ContentSet >
required Yes
count
type number
required Yes
}

/sets/lookup

authorization none
parameters
#0: text
type string
required Yes
#1: filters
required No
returns any

/sets/create

authorization none
parameters
#0: data
type
object {
projectId
type string
required Yes
key
type string
required Yes
min length 1
max length 30
schema
type string
required Yes
schemaConfig
type any
required Yes
metadata
required Yes
}
required Yes
returns ContentSet

/sets/save

authorization none
parameters
#0: id
type string
required Yes
#1: data
required Yes
returns ContentSet

/sets/archive

authorization none
parameters
#0: id
type string
required Yes
returns ContentSet

/sets/exists

authorization none
parameters
#0: key
type
string | ContentSetKey
required Yes
returns boolean

/sets/top

authorization none
parameters
#0: query
required No
returns
Array<
object {
stats
required Yes
id
type string
required Yes
name
type string
required Yes
key
type string
required Yes
accountId
type string
required Yes
projectId
type string
required Yes
createdAt
type Date
required Yes
updatedAt
type Date
required Yes
state
required Yes
schema
type string
required Yes
schemaConfig
type object
required No
metadata
required No
}
>

/sets/getStats

authorization none
parameters
#0: id
type string
required Yes
#1: filter
required No

/contents

/contents/get

authorization none
parameters
#0: id
type string
required Yes
returns ContentItem

/contents/list

authorization none
parameters
#0: query
required No
returns
object {
items
type
Array< ContentItem >
required Yes
count
type number
required Yes
}

/contents/lookup

authorization none
parameters
#0: text
type string
required Yes
#1: filters
required No
returns

/contents/create

authorization none
parameters
#0: data
type
object {
contentSetId
type string
required Yes
key
type string
required Yes
min length 1
max length 1024
metadata
required No
}
required Yes
returns ContentItem

/contents/save

authorization none
parameters
#0: id
type string
required Yes
#1: data
required Yes
returns ContentItem

/contents/archive

authorization none
parameters
#0: id
type string
required Yes
returns ContentItem

/contents/exists

authorization none
parameters
#0: key
type
string | ContentKey
required Yes
returns boolean

/contents/top

authorization none
parameters
#0: query
required No
returns
Array<
object {
stats
required Yes
id
type string
required Yes
key
type string
required Yes
accountId
type string
required Yes
projectId
type string
required Yes
contentSetId
type string
required Yes
createdAt
type Date
required Yes
updatedAt
type Date
required Yes
state
required Yes
metadata
required No
}
>

/contents/getStats

authorization none
parameters
#0: id
type string
required Yes
#1: filter
required No

/feelbacks

/feelbacks/get

Returns a feelback

authorization none
parameters
#0: id
type string
required Yes
returns Feelback

/feelbacks/list

authorization none
parameters
#0: query
type
object {
$size
type number
required No
default 10
$page
type number
required No
projectId
type string
required No
contentSetId
type string
required No
contentId
type string
required No
}
required Yes
returns
object {
items
type
Array< Feelback >
required Yes
count
type undefined
required Yes
}

/feelbacks/create

authorization none
parameters
#0: params
type
{
contentSetId string
key string
value any
context? object
}
|
{
contentId string
value any
context? object
}
required Yes
returns
object {
feelbackId
type string
required Yes
revokable
type
object {
token
type string
required Yes
expireAt
type Date
required Yes
}
required No
}

/feelbacks/edit

authorization none
parameters
#0: params
type
object {
feelbackId
type string
required Yes
revokeToken
type string
required Yes
value
type any
required Yes
}
required Yes
returns
object {
feelbackId
type string
required Yes
revokable
type
object {
token
type string
required Yes
expireAt
type Date
required Yes
}
required No
}

/feelbacks/remove

authorization none
parameters
#0: params
type
object {
feelbackId
type string
required Yes
revokeToken
type string
required Yes
}
required Yes
returns void

/feelbacks/getAggregates

authorization none
parameters
#0: content
type
string | ContentKey |
{
contentId string
}
required Yes
#1: period
type
dayweekmonthyearlifetimerolling7drolling28drolling12m
required No
returns
Array< number >

Common types

ProjectState literal

Include the project state

values
active project is active
archived project is archived

ProjectMetadata object

property
description
type string
required No

Project object

property
id
type string
required Yes
name
type string
required Yes
accountId
type string
required Yes
createdAt
type Date
required Yes
updatedAt
type Date
required Yes
state
required Yes
metadata
required No

ProjectQueryModel object

property
$size
type number
required No
default 10
$page
type number
required No
state

Filter based on project state

type
allactivearchived
required No
default active

ProjectFilters object

property
state

Filter based on project state

type
allactivearchived
required No
default active

StatAggregatedPeriod literal

values
dayweekmonthyearlifetimerolling7drolling28drolling12m

StatsFilter object

property
period
required No
reference
type
string | Date
required No
shift
type number
required No

AggregatedEntity literal

values
projectcontentSetcontentItem

AggregatedPeriod literal

values
dayweekmonthyearlifetimerolling7drolling28drolling12m

FeelbackPulseAggregation object

property
period
type any
required Yes
values
type
Array< number >
required Yes
count
type number
required Yes
schema
type
pulse
required Yes

FeelbackYesNoAggregation object

property
period
type any
required Yes
values
type
Array< number >
required Yes
count
type number
required Yes
schema
type
yes-no
required Yes
points

pair of yes/no per single data point

type
Array<
Tuple[ number , number ]
>
required Yes
counts

count of y and n in this period

type
Tuple[ number , number ]
required Yes
summary

sentiment: a value in range [-1, 1] where -1 is all no, +1 is all yes, 0 is yes=no

type number
required Yes

FeelbackReactionAggregation object

property
period
type any
required Yes
values
type
Array< number >
required Yes
count
type number
required Yes
schema
type
reaction
required Yes
points

[count[] of each reaction, avg sentiment, avg intensity] per single data point

type
Array<
Tuple[
Array< number >
, number , number ]
>
required Yes
counts

count of each item in this period

type
Array< number >
required Yes
summary

sentiment: a value in range [-1, 1] where -1 is all no, +1 is all yes, 0 is neutral

type number
required No
intensity

intensity: a value in range [0, 1] where 0 is no intensity, 1 is max intensity

type number
required No

FeelbackRatingAggregation object

property
period
type any
required Yes
values
type
Array< number >
required Yes
count
type number
required Yes
schema
type
rating
required Yes
points

pair of [count, average] per single data point

type
Array<
Tuple[ number , number ]
>
required Yes
summary

average in this period

type number
required Yes

FeelbackMessageAggregation object

property
period
type any
required Yes
values
type
Array< number >
required Yes
count
type number
required Yes
schema
type
message
required Yes

FeelbackTaggedMessageAggregation object

property
period
type any
required Yes
values
type
Array< number >
required Yes
count
type number
required Yes
schema
type
tagged-message
required Yes
points

[count[] of each tag, avg sentiment] per single data point

type
Array<
Tuple[
Array< number >
, number ]
>
required Yes
counts

count of each item in this period

type
Array< number >
required Yes
summary

sentiment: a value in range [-1, 1] where -1 is all no, +1 is all yes, 0 is neutral

type number
required No

AggregatedData object

property
id
type string
required Yes
accountId
type string
required Yes
projectId
type string
required Yes
contentSetId
type string
required No
createdAt
type Date
required Yes
updatedAt
type Date
required Yes
entity
required Yes
entityId
type string
required Yes
period
required Yes
referenceDate
type Date
required Yes
data
required Yes
count
type number
required Yes
summary
type number
required No

ContentItemState literal

values
activearchivedinactive

ContentSetMetadata object

property
description
type string
required No
disallowAutoContentCreation
type boolean
required No
publicAggregates
type boolean
required No

ContentSet object

property
id
type string
required Yes
name
type string
required Yes
key
type string
required Yes
accountId
type string
required Yes
projectId
type string
required Yes
createdAt
type Date
required Yes
updatedAt
type Date
required Yes
state
required Yes
schema
type string
required Yes
schemaConfig
type object
required No
metadata
required No

ContentSetQueryModel object

property
$size
type number
required No
default 10
$page
type number
required No
state
type
allactivearchivedinactive
required No
projectId
type string
required No
schema
type
string |
Array< string >
required No

ContentSetFilters object

property
state
type
allactivearchivedinactive
required No
projectId
type string
required No
schema
type
string |
Array< string >
required No

ContentSetMetadataModel object

property
name
type string
required Yes
description
type string
required No
disallowAutoContentCreation
type boolean
required No
publicAggregates
type boolean
required No

ContentSetSaveModel object

property
name
type string
required No
description
type string
required No
disallowAutoContentCreation
type boolean
required No
publicAggregates
type boolean
required No
key
type string
required No

ContentSetKey object

property
projectId
type string
required Yes
key
type string
required Yes

TopAggregatedPeriod literal

values
weekmonthyearrolling7drolling28drolling12m

ContentSetTopQueryModel object

property
$size
type number
required No
default 10
projectId
type string
required No
period
required No

ContentItemMetadata object

property
title
type string
required No
url
type string
required No

ContentItem object

property
id
type string
required Yes
key
type string
required Yes
accountId
type string
required Yes
projectId
type string
required Yes
contentSetId
type string
required Yes
createdAt
type Date
required Yes
updatedAt
type Date
required Yes
state
required Yes
metadata
required No

ContentQueryModel object

property
$size
type number
required No
default 10
$page
type number
required No
state
type
allactivearchivedinactive
required No
projectId
type string
required No
contentSetId
type string
required No

ContentFilters object

property
state
type
allactivearchivedinactive
required No
projectId
type string
required No
contentSetId
type string
required No

ContentItemLookupEntry object

property
projectId
type string
required Yes
key
type string
required Yes
metadata
required No
contentSetId
type string
required Yes
id
type string
required Yes

ContentMetadataModel object

property
title
type string
required No
description
type string
required No
url
type string
required No

ContentSaveModel object

property
title
type string
required No
description
type string
required No
url
type string
required No
key
type string
required No

ContentKey object

property
contentSetId
type string
required Yes
key
type string
required Yes

ContentTopQueryModel object

property
$size
type number
required No
default 10
projectId
type string
required No
contentSetId
type string
required No
period
required No

FeelbackState literal

values
activerevoked

FeelbackValue union

types
string | number | object

ProfilingData object

property
userId
type string
required No
sessionId
type string
required No
os
type string
required No
osVersion
type string
required No
formFactor
type string
required No
device
type string
required No
deviceBrand
type string
required No
browser
type string
required No
browserVersion
type string
required No
country
type string
required No
city
type string
required No
language
type string
required No

Feelback object

property
id
type string
required Yes
accountId
type string
required Yes
contentSetId
type string
required Yes
contentItemId
type string
required Yes
createdAt
type Date
required Yes
state
required Yes
value
required Yes
context
type object
required No
profiling
required No

ApiError object

property
error

Represents the error code. Examples are: "unauthorized", "bad-request", "not-found", ...

type string
required Yes
message
type string
required Yes
data
type object
required No