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-clientpnpm add @feelback/api-clientyarn add @feelback/api-clientIt’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/v0Plain 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
POSTverb - for requests, function arguments are sent with the body as a JSON array
- all successful responses return the
200status 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
ApiErrorwith the error info. In other words, a response with a status code equal or greater than400is an error, and you should check the bodyerrorproperty 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/savePermissions
The Feelback API defines 3 permission levels:
anonymousvieweradmin
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
stringProject/projects/lookup
/projects/lookup stringProjectFiltersany/projects/create
/projects/create | name | type stringrequired Yes min length 1 max length 50 |
| description | type stringrequired No max length 255 |
Project/projects/save
/projects/save string| name | type stringrequired No min length 1 max length 50 |
| description | type stringrequired No max length 255 |
Project/projects/getStats
/projects/getStats stringStatsFilterAggregatedData/sets
/sets /sets/lookup
/sets/lookup stringContentSetFiltersany/sets/create
/sets/create | projectId | type stringrequired Yes |
| key | type stringrequired Yes min length 1 max length 30 |
| schema | type stringrequired Yes |
| schemaConfig | type anyrequired Yes |
| metadata | required Yes |
ContentSet/sets/save
/sets/save stringContentSetSaveModelContentSet/sets/exists
/sets/exists boolean/sets/top
/sets/top Array<| stats | type AggregatedDatarequired Yes |
| id | type stringrequired Yes |
| name | type stringrequired Yes |
| key | type stringrequired Yes |
| accountId | type stringrequired Yes |
| projectId | type stringrequired Yes |
| createdAt | type Daterequired Yes |
| updatedAt | type Daterequired Yes |
| state | type ContentItemStaterequired Yes |
| schema | type stringrequired Yes |
| schemaConfig | type objectrequired No |
| metadata | type ContentSetMetadatarequired No |
>/sets/getStats
/sets/getStats stringStatsFilterAggregatedData/contents
/contents /contents/lookup
/contents/lookup stringContentFilters/contents/create
/contents/create | contentSetId | type stringrequired Yes |
| key | type stringrequired Yes min length 1 max length 1024 |
| metadata | type ContentMetadataModelrequired No |
ContentItem/contents/save
/contents/save stringContentSaveModelContentItem/contents/exists
/contents/exists boolean/contents/top
/contents/top ContentTopQueryModelArray<| stats | type AggregatedDatarequired Yes |
| id | type stringrequired Yes |
| key | type stringrequired Yes |
| accountId | type stringrequired Yes |
| projectId | type stringrequired Yes |
| contentSetId | type stringrequired Yes |
| createdAt | type Daterequired Yes |
| updatedAt | type Daterequired Yes |
| state | type ContentItemStaterequired Yes |
| metadata | type ContentItemMetadatarequired No |
>/contents/getStats
/contents/getStats stringStatsFilterAggregatedData/feelbacks
/feelbacks /feelbacks/get
/feelbacks/get Returns a feelback
stringFeelback/feelbacks/list
/feelbacks/list | $size | type numberrequired No default 10 |
| $page | type numberrequired No |
| projectId | type stringrequired No |
| contentSetId | type stringrequired No |
| contentId | type stringrequired No |
/feelbacks/create
/feelbacks/create stringstringanyobjectstringanyobject| feelbackId | type stringrequired Yes | ||||
| revokable | type object {
required No |
/feelbacks/edit
/feelbacks/edit | feelbackId | type stringrequired Yes |
| revokeToken | type stringrequired Yes |
| value | type anyrequired Yes |
| feelbackId | type stringrequired Yes | ||||
| revokable | type object {
required No |
/feelbacks/remove
/feelbacks/remove | feelbackId | type stringrequired Yes |
| revokeToken | type stringrequired Yes |
void/feelbacks/getAggregates
/feelbacks/getAggregates dayweekmonthyearlifetimerolling7drolling28drolling12mArray< number >Common types
ProjectState literal
Include the project state
active project is activearchived project is archivedProjectMetadata object
| property | |
|---|---|
| description | type stringrequired No |
Project object
| property | |
|---|---|
| id | type stringrequired Yes |
| name | type stringrequired Yes |
| accountId | type stringrequired Yes |
| createdAt | type Daterequired Yes |
| updatedAt | type Daterequired Yes |
| state | type ProjectStaterequired Yes |
| metadata | type ProjectMetadatarequired No |
ProjectQueryModel object
| property | |
|---|---|
| $size | type numberrequired No default 10 |
| $page | type numberrequired No |
| state | Filter based on project state type allactivearchivedrequired No default active |
ProjectFilters object
| property | |
|---|---|
| state | Filter based on project state type allactivearchivedrequired No default active |
StatAggregatedPeriod literal
dayweekmonthyearlifetimerolling7drolling28drolling12mStatsFilter object
| property | |
|---|---|
| period | type StatAggregatedPeriodrequired No |
| reference | type string | Daterequired No |
| shift | type numberrequired No |
AggregatedEntity literal
projectcontentSetcontentItemAggregatedPeriod literal
dayweekmonthyearlifetimerolling7drolling28drolling12mFeelbackPulseAggregation object
| property | |
|---|---|
| period | type anyrequired Yes |
| values | type Array< number >required Yes |
| count | type numberrequired Yes |
| schema | type pulserequired Yes |
FeelbackYesNoAggregation object
| property | |
|---|---|
| period | type anyrequired Yes |
| values | type Array< number >required Yes |
| count | type numberrequired Yes |
| schema | type yes-norequired 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 numberrequired Yes |
FeelbackReactionAggregation object
| property | |
|---|---|
| period | type anyrequired Yes |
| values | type Array< number >required Yes |
| count | type numberrequired Yes |
| schema | type reactionrequired 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 numberrequired No |
| intensity | intensity: a value in range [0, 1] where 0 is no intensity, 1 is max intensity type numberrequired No |
FeelbackRatingAggregation object
| property | |
|---|---|
| period | type anyrequired Yes |
| values | type Array< number >required Yes |
| count | type numberrequired Yes |
| schema | type ratingrequired Yes |
| points | pair of [count, average] per single data point type Array<Tuple[ number , number ]>required Yes |
| summary | average in this period type numberrequired Yes |
FeelbackMessageAggregation object
| property | |
|---|---|
| period | type anyrequired Yes |
| values | type Array< number >required Yes |
| count | type numberrequired Yes |
| schema | type messagerequired Yes |
FeelbackTaggedMessageAggregation object
| property | |
|---|---|
| period | type anyrequired Yes |
| values | type Array< number >required Yes |
| count | type numberrequired Yes |
| schema | type tagged-messagerequired 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 numberrequired No |
FeelbackAggregation union
AggregatedData object
| property | |
|---|---|
| id | type stringrequired Yes |
| accountId | type stringrequired Yes |
| projectId | type stringrequired Yes |
| contentSetId | type stringrequired No |
| createdAt | type Daterequired Yes |
| updatedAt | type Daterequired Yes |
| entity | type AggregatedEntityrequired Yes |
| entityId | type stringrequired Yes |
| period | type AggregatedPeriodrequired Yes |
| referenceDate | type Daterequired Yes |
| data | type FeelbackAggregationrequired Yes |
| count | type numberrequired Yes |
| summary | type numberrequired No |
ContentItemState literal
activearchivedinactiveContentSetMetadata object
| property | |
|---|---|
| description | type stringrequired No |
| disallowAutoContentCreation | type booleanrequired No |
| publicAggregates | type booleanrequired No |
ContentSet object
| property | |
|---|---|
| id | type stringrequired Yes |
| name | type stringrequired Yes |
| key | type stringrequired Yes |
| accountId | type stringrequired Yes |
| projectId | type stringrequired Yes |
| createdAt | type Daterequired Yes |
| updatedAt | type Daterequired Yes |
| state | type ContentItemStaterequired Yes |
| schema | type stringrequired Yes |
| schemaConfig | type objectrequired No |
| metadata | type ContentSetMetadatarequired No |
ContentSetQueryModel object
| property | |
|---|---|
| $size | type numberrequired No default 10 |
| $page | type numberrequired No |
| state | type allactivearchivedinactiverequired No |
| projectId | type stringrequired No |
| schema | type string |Array< string >required No |
ContentSetFilters object
| property | |
|---|---|
| state | type allactivearchivedinactiverequired No |
| projectId | type stringrequired No |
| schema | type string |Array< string >required No |
ContentSetMetadataModel object
| property | |
|---|---|
| name | type stringrequired Yes |
| description | type stringrequired No |
| disallowAutoContentCreation | type booleanrequired No |
| publicAggregates | type booleanrequired No |
ContentSetSaveModel object
| property | |
|---|---|
| name | type stringrequired No |
| description | type stringrequired No |
| disallowAutoContentCreation | type booleanrequired No |
| publicAggregates | type booleanrequired No |
| key | type stringrequired No |
ContentSetKey object
| property | |
|---|---|
| projectId | type stringrequired Yes |
| key | type stringrequired Yes |
TopAggregatedPeriod literal
weekmonthyearrolling7drolling28drolling12mContentSetTopQueryModel object
| property | |
|---|---|
| $size | type numberrequired No default 10 |
| projectId | type stringrequired No |
| period | type TopAggregatedPeriodrequired No |
ContentItemMetadata object
| property | |
|---|---|
| title | type stringrequired No |
| url | type stringrequired No |
ContentItem object
| property | |
|---|---|
| id | type stringrequired Yes |
| key | type stringrequired Yes |
| accountId | type stringrequired Yes |
| projectId | type stringrequired Yes |
| contentSetId | type stringrequired Yes |
| createdAt | type Daterequired Yes |
| updatedAt | type Daterequired Yes |
| state | type ContentItemStaterequired Yes |
| metadata | type ContentItemMetadatarequired No |
ContentQueryModel object
| property | |
|---|---|
| $size | type numberrequired No default 10 |
| $page | type numberrequired No |
| state | type allactivearchivedinactiverequired No |
| projectId | type stringrequired No |
| contentSetId | type stringrequired No |
ContentFilters object
| property | |
|---|---|
| state | type allactivearchivedinactiverequired No |
| projectId | type stringrequired No |
| contentSetId | type stringrequired No |
ContentItemLookupEntry object
| property | |
|---|---|
| projectId | type stringrequired Yes |
| key | type stringrequired Yes |
| metadata | type ContentItemMetadatarequired No |
| contentSetId | type stringrequired Yes |
| id | type stringrequired Yes |
ContentMetadataModel object
| property | |
|---|---|
| title | type stringrequired No |
| description | type stringrequired No |
| url | type stringrequired No |
ContentSaveModel object
| property | |
|---|---|
| title | type stringrequired No |
| description | type stringrequired No |
| url | type stringrequired No |
| key | type stringrequired No |
ContentKey object
| property | |
|---|---|
| contentSetId | type stringrequired Yes |
| key | type stringrequired Yes |
ContentTopQueryModel object
| property | |
|---|---|
| $size | type numberrequired No default 10 |
| projectId | type stringrequired No |
| contentSetId | type stringrequired No |
| period | type TopAggregatedPeriodrequired No |
FeelbackState literal
activerevokedFeelbackValue union
string | number | objectProfilingData object
| property | |
|---|---|
| userId | type stringrequired No |
| sessionId | type stringrequired No |
| os | type stringrequired No |
| osVersion | type stringrequired No |
| formFactor | type stringrequired No |
| device | type stringrequired No |
| deviceBrand | type stringrequired No |
| browser | type stringrequired No |
| browserVersion | type stringrequired No |
| country | type stringrequired No |
| city | type stringrequired No |
| language | type stringrequired No |
Feelback object
| property | |
|---|---|
| id | type stringrequired Yes |
| accountId | type stringrequired Yes |
| contentSetId | type stringrequired Yes |
| contentItemId | type stringrequired Yes |
| createdAt | type Daterequired Yes |
| state | type FeelbackStaterequired Yes |
| value | type FeelbackValuerequired Yes |
| context | type objectrequired No |
| profiling | type ProfilingDatarequired No |
ApiError object
| property | |
|---|---|
| error | Represents the error code. Examples are: "unauthorized", "bad-request", "not-found", ... type stringrequired Yes |
| message | type stringrequired Yes |
| data | type objectrequired No |