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
pnpm add @feelback/api-client
yarn add @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:
- the API uses JSON to transmit data, thus requests must use
"content-type: application/json"
header, and responses will send the same header back along with a JSON body. - all requests use the
POST
verb - for requests, function arguments are sent with the body as a JSON array
- all successful responses return the
200
status code - for error responses, although the API follows the common http convention about status codes, you should not rely on it. Instead your should read the response body which is an
ApiError
with the error info. In other words, a response with a status code equal or greater than400
is an error, and you should check the bodyerror
property to know the specific error.
Some code examples to see the convention in use:
import createClient from "@feelback/api-client";
const client = createClient({ endpoint: "https://api.feelback.dev/v0" });
// parameters are just vanilla js function arguments
const projects = await client.projects.list({
state: "active",
$size: 10
});
// you can use multiple arguments like a standard function
const project = await client.projects.save("project-id", {
name: "New project name",
description: "A project description"
});
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();
}
# no parameter function
curl -X POST https://api.feelback.dev/v0/projects/list
# single parameter function
# the parameter is wrapped in a JSON array
curl -X POST -H "Content-Type: application/json" \
-d "[\"project-id\"]" \
https://api.feelback.dev/v0/projects/get
# multiple parameter function
# parameters are sent as JSON array
curl -X POST -H "Content-Type: application/json" \
-d "[\"project-id\", {\"name\":\"new project name\"}]" \
https://api.feelback.dev/v0/projects/save
Permissions
The Feelback API defines 3 permission levels:
anonymous
viewer
admin
Authentication
The Feelback API support authentication via the API-KEY scheme.
curl -X POST -H "Authorization: API-KEY {your-api-key}" https://api.feelback.com/v0/projects/list
//
// 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));
//
// 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
//
const endpoint = "https://api.feelback.dev/v0";
const apiKey = "your api key";
const response = await fetch(endpoint, {
method: "POST",
headers: {
authorization: "API-KEY " + apiKey
}
});
Endpoints
/projects
/projects
/projects/get
/projects/get
Retrieve a {@link Project} by id
The project id
string
Project
/projects/lookup
/projects/lookup
string
ProjectFilters
any
/projects/create
/projects/create
name | type string required Yes min length 1 max length 50 |
description | type string required No max length 255 |
Project
/projects/save
/projects/save
string
name | type string required No min length 1 max length 50 |
description | type string required No max length 255 |
Project
/projects/getStats
/projects/getStats
string
StatsFilter
AggregatedData
/sets
/sets
/sets/lookup
/sets/lookup
string
ContentSetFilters
any
/sets/create
/sets/create
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 |
ContentSet
/sets/save
/sets/save
string
ContentSetSaveModel
ContentSet
/sets/exists
/sets/exists
boolean
/sets/top
/sets/top
Array<
stats | type AggregatedData 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 | type ContentItemState required Yes |
schema | type string required Yes |
schemaConfig | type object required No |
metadata | type ContentSetMetadata required No |
>
/sets/getStats
/sets/getStats
string
StatsFilter
AggregatedData
/contents
/contents
/contents/lookup
/contents/lookup
string
ContentFilters
/contents/create
/contents/create
contentSetId | type string required Yes |
key | type string required Yes min length 1 max length 1024 |
metadata | type ContentMetadataModel required No |
ContentItem
/contents/save
/contents/save
string
ContentSaveModel
ContentItem
/contents/exists
/contents/exists
boolean
/contents/top
/contents/top
ContentTopQueryModel
Array<
stats | type AggregatedData 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 | type ContentItemState required Yes |
metadata | type ContentItemMetadata required No |
>
/contents/getStats
/contents/getStats
string
StatsFilter
AggregatedData
/feelbacks
/feelbacks
/feelbacks/get
/feelbacks/get
Returns a feelback
string
Feelback
/feelbacks/list
/feelbacks/list
$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 |
/feelbacks/create
/feelbacks/create
string
string
any
object
string
any
object
feelbackId | type string required Yes | ||||
revokable | type object {
required No |
/feelbacks/edit
/feelbacks/edit
feelbackId | type string required Yes |
revokeToken | type string required Yes |
value | type any required Yes |
feelbackId | type string required Yes | ||||
revokable | type object {
required No |
/feelbacks/remove
/feelbacks/remove
feelbackId | type string required Yes |
revokeToken | type string required Yes |
void
/feelbacks/getAggregates
/feelbacks/getAggregates
day
week
month
year
lifetime
rolling7d
rolling28d
rolling12m
Array<
number
>
Common types
ProjectState
literal
Include the project state
active
project is activearchived
project is archivedProjectMetadata
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 | type ProjectState required Yes |
metadata | type ProjectMetadata required No |
ProjectQueryModel
object
property | |
---|---|
$size | type number required No default 10 |
$page | type number required No |
state | Filter based on project state type all active archived required No default active |
ProjectFilters
object
property | |
---|---|
state | Filter based on project state type all active archived required No default active |
StatAggregatedPeriod
literal
day
week
month
year
lifetime
rolling7d
rolling28d
rolling12m
StatsFilter
object
property | |
---|---|
period | type StatAggregatedPeriod required No |
reference | type string | Date required No |
shift | type number required No |
AggregatedEntity
literal
project
contentSet
contentItem
AggregatedPeriod
literal
day
week
month
year
lifetime
rolling7d
rolling28d
rolling12m
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 |
FeelbackAggregation
union
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 | type AggregatedEntity required Yes |
entityId | type string required Yes |
period | type AggregatedPeriod required Yes |
referenceDate | type Date required Yes |
data | type FeelbackAggregation required Yes |
count | type number required Yes |
summary | type number required No |
ContentItemState
literal
active
archived
inactive
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 | type ContentItemState required Yes |
schema | type string required Yes |
schemaConfig | type object required No |
metadata | type ContentSetMetadata required No |
ContentSetQueryModel
object
property | |
---|---|
$size | type number required No default 10 |
$page | type number required No |
state | type all active archived inactive required No |
projectId | type string required No |
schema | type string |Array< string > required No |
ContentSetFilters
object
property | |
---|---|
state | type all active archived inactive 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
week
month
year
rolling7d
rolling28d
rolling12m
ContentSetTopQueryModel
object
property | |
---|---|
$size | type number required No default 10 |
projectId | type string required No |
period | type TopAggregatedPeriod 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 | type ContentItemState required Yes |
metadata | type ContentItemMetadata required No |
ContentQueryModel
object
property | |
---|---|
$size | type number required No default 10 |
$page | type number required No |
state | type all active archived inactive required No |
projectId | type string required No |
contentSetId | type string required No |
ContentFilters
object
property | |
---|---|
state | type all active archived inactive 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 | type ContentItemMetadata 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 | type TopAggregatedPeriod required No |
FeelbackState
literal
active
revoked
FeelbackValue
union
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 | type FeelbackState required Yes |
value | type FeelbackValue required Yes |
context | type object required No |
profiling | type ProfilingData 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 |