Kinopio Help and Support

API Docs

The Kinopio API is used to find, save, and update the spaces of signed up users. You can use it to make cool things too.

Use of the API is subject to the Use Restrictions Policy.

Authentication

Kinopio uses token-based authentication using your user apiKey. The easiest way to get your apiKey is by entering JSON.parse(localStorage.user).apiKey in your browser console on kinopio.club.

Use your apiKey in the Authorization header of each request.

🙈 Your API key carries the same privileges as your user account, so be sure to keep it secret!

(For testing, you can also use a query string (?apiKey=) but this is less secure and not recommended)

Rate Limits

The API is limited to 5 requests per second. If you exceed this rate, you will receive a 429 response and will need to wait 30 seconds before subsequent requests will succeed.

Routes

All

https://api.kinopio.club is the base path for all routes

Method Name Description Auth
GET / Confirm that the API server is online None

Users

Users are representations of any account on Kinopio. Users are created by the server when they sign up.

User Routes

Routes with Auth as apiKey mean that the Authorization header apiKey must match the requested user.

Method Path Description Auth
GET /user/public/:userId Gets public info on a user None
GET /user Get all info on the authenticating user apiKey
GET /user/favorites Gets all info, including user and space favorites, on the authenticating user. Favorited spaces which have unread updates will have isEdited: true apiKey
GET /user/spaces Get a list of the user's Spaces apiKey
GET /user/removed-spaces Get Spaces removed by the authenticating user apiKey
GET /user/current-public-spaces Get a list of all users currently viewing or editing Spaces with privacy set to open None
GET /user/tags Get a list of the last edited Tags in your spaces apiKey
PATCH /user Update the authenticating user(s) based on an object body with user attributes. You can't patch apiKey, password, emailIsVerified, or email apiKey
PATCH /user/favorites Add or remove favorite users or spaces. Acts like a toggle, if the user is already liked it then removes the like. If not already liked it adds the like. request body should be in the format. apiKey

User Attributes

Name Type Description
id String The unique ID of the user. Is not user updateable
name String The unique name of the user. Is a url-safe string (no spaces or special characters) because it's also used for url slugs
email String The unique email address of the user required to create an account"
emailIsVerified Boolean Whether the user has verified their email address
apiKey UUID Used in Authentication headers to make API calls as the currentUser. Generated and returned only when user signs up or in. Is not user updateable
lastSpaceId String The spaceId of the last space edited. Used to return you to the same space the next time you visit kinopio.club
color String User color changes your paint stroke and default avatar color
defaultConnectionTypeId String The last connectionTypeId that the user marked as 'Default' to use for new Connections
lastReadNewStuffId String The id of the last read article from the 'new stuff' newsfeed
currentPublicSpaceId String The id of an space with privacy set to open that the user is currently viewing or editing
cardsCreatedCount Integer The number of cards the user has created if they're not a paid user, used to enforce the free user limit. Is not user updatable.
isUpgraded Boolean Whether the user currently has a paid subscription. Is not user updatable.
filterShowUsers Boolean Whether the user has has toggled the card user filter
filterShowDateUpdated Boolean Whether the user has has toggled the card date filter
filterShowAbsoluteDates Boolean Whether card dates are displayed as absolute (false is default relative)
journalPrompts Array id, name, and packId for each user journal prompt. Private user info.
newSpacesAreBlank Boolean Whether new spaces that the user creates are blank, or have the default onboarding/tutorial cards
shouldHideCardTips Boolean Whether the user has chosen to hide the card editing tips button ('?')
shouldEmailNotifications Boolean Whether the user has chosen to allow notification emails (default to true)
shouldEmailBulletin Boolean Whether the user has chosen to allow bulletin emails (default to true)

Spaces

Spaces are where your Cards and Connections live.

Space Routes

Routes with Auth canViewSpace or canEditSpace requires that your Authorization apiKey belongs to a user with the permission to view or edit the space.

Method Path Description Auth
GET /space/:spaceId Get info on a space by id canViewSpace
GET /space/new-spaces Get a list of recently updated spaces which are open or closed and have been renamed None
GET /space/best-of A subset of new-spaces that have explicitly been curated by Kinopio None
GET /space/:spaceId/
removedCards
Get Cards removed in a space canEditSpace
GET /space/by-url/:spaceUrl Get info on a space by space url format (:space-name-:id) canViewSpace
GET /space/multiple?spaceIds=spaceId1,spaceId2 Get info on multiple spaces, up to 60 spaceIds at a time canViewSpace
POST /space Create a new space(s) from object(s) in request body. The owner will be the apiKey user apiKey
PATCH /space Update space(s) from object(s) in request body canEditSpace
PATCH /space/restore Restore removed space(s) from object(s) in request body canEditSpace
DELETE /space Remove space(s) specified in request body canEditSpace
DELETE /space/permanent Permanently remove space(s) specified in request body canEditSpace
DELETE /space/collaborator Removes collaborator user from space. Request Body Keys: spaceId, userId canEditSpace

Space Attributes

Name Type Description
id String The unique ID of the space. Is not user updateable
name String The name of the space
url String The url of a space is determined by it's name and id. For example, kinopio.club/:space-name-:id
ownerUserId String The userId of the user who created the space. Used to create url slugs
privacy String Can be open, closed, private
isRemoved Boolean Sets whether the space has been soft-removed. (can then be restored or permanently removed)
removedByUserId String The user who soft-removed the space. All space users can restore it via the API, but only the user who removed it will see it listed
collaboratorKey String Used like an apikey to allow editing, but just for that space. allows anonymous users who aren't signed in to edit a space. You can rotate this key, but you should still treat it as a secret
users Array The user who created/owns the space (a space will always have only one user)
collaborators Array A list of users that can also edit the space
cards Array A list of Cards in the space
connections Array A list of Connections
connectionTypes Array A list of Connection Types
tags Array A list of Tags
moonPhase String Name of the moonPhase icon used by Journal spaces
showInExplore Boolean Whether the space is shown in explore
bestOfExplore Boolean Whether the space has been curated by Kinopio
originSpaceId String If the space was created by duplicating another space, the origin space id is recorded

Cards

Cards are the building blocks of Spaces. They have x, y, and z positions and a name.

Cards Routes

Routes with Auth canEditSpace requires that your Authorization apiKey belongs to a user with the permission to edit the space that the card belongs to.

Method Path Description Auth
GET /card/:cardId Get info on a card None
GET /card/by-tag-name/:tagName get all cards with tag matching tagName in your Spaces apiKey
GET /card/by-link-to-space/:spaceId get the cards and Spaces where linkToSpaceId is spaceId. Will only return spaces that the user can view apiKey and canViewSpace
GET /card/by-tag-name-and-user/:tagName/:userId get cards tagged with tagName in spaces that the userId can edit. Only returns results from spaces which you have permission to view apiKey and canViewSpace
POST /card Create card(s) from object(s) in request body. Body object must contain spaceId and name. If not included, x, y, z will be near the last updated card in the space canEditSpace
PATCH /card Update card(s) from object(s) in request body. Body object must contain id canEditSpace
PATCH /card/restore Restore removed card specified in body canEditSpace
DELETE /card Remove card specified in body canEditSpace
DELETE /card/permanent Permanently remove card specified in body canEditSpace

Card Attributes

Name Type Description
id String The unique ID of the card. Is not user updateable
name String The name of the card is it's main text
x Integer x-axis position
y Integer y-axis position
z Integer z-axis position
frameId String The id of type of frame applied to the card, if any
isRemoved Boolean Sets whether the card has been soft-removed. (can be restored or permanently removed by space users)
spaceId String The space that the card belongs to
nameUpdatedByUserId String The user id that last updated the name of the card
nameUpdatedAt String The updated at date for the card name
linkToSpaceId String The spaceId linked to in the card name
commentIsVisible Boolean If the card is a ((comment)), determines whether the full comment displays (instead of '…')

Connections

Connections are the lines that connect cards together. Connections have a connection-type which assigns them a color and allows the user to thematically group cards together by connected type.

Connection Routes

Routes with Auth canEditSpace requires that your Authorization apiKey belongs to a user with the permission to edit the space that the connection belongs to.

Method Path Description Auth
GET /connection/
:connectionId
Get info on a connection None
POST /connection Create connection(s) from object in request body. Object must contain spaceId, connectionTypeId canEditSpace
PATCH /connection Update connection(s) from object in request body canEditSpace
DELETE /connection Permenently remove connection(s) speced in req body canEditSpace

Connection Attributes

Name Type Description
id String The unique ID of the connection. Is not user updateable
startCardId String The card that the connection line starts from
endCardId String The card that the connection line ends at
path String SVG path that defines the connection line and it's curve, e.g. 'm524,138 q90,40 49,123' is a quadratic bezier curve made up of origin XY, control point XY, and end XY points.
connectionTypeId String The connection-type that the connection belongs to
spaceId String The space that the connection belongs to

Connection Types

Connection Types group Connections together to allow the attributes of multiple connection lines to be represented and edited together.

Connection Type Routes

Routes with Auth canEditSpace requires that your Authorization apiKey belongs to a user with the permission to edit the space that the connection type belongs to.

Method Path Description Auth
GET /connection-type/:connectionTypeId Get info on a connectionType None
POST /connection-type Create connectionType(s) from object (or array) in request body. Object must contain spaceId canEditSpace
PATCH /connection-type Update connectionType(s) from object in request body canEditSpace
DELETE /connection-type Permenently remove connectionType canEditSpace

Connection Type Attributes

Name Type Description
id String The unique ID of the connection. Is not user updateable
name String The name of the connection-type
color String User color changes your paint stroke and default avatar color
spaceId String The space that the connection-type belongs to

Tags

Each tag you add to a card is considered a seperate entity. So if you have two cards which both have the tag [[balloon]], this is two tag entities both named 'balloon', with different cardIds.

Tags Routes

Routes with Auth canEditSpace requires that your Authorization apiKey belongs to a user with the permission to edit the space that the connection type belongs to.

Method Path Description Auth
GET /tags/:tagName Get all tags with tagName in your Spaces apiKey
GET /tags/by-card/:cardId Get all tags in a Cards apiKey
PATCH /tags/color Change the color of all tags with the name specified in request body. Object must contain name, color apiKey

Tags Attributes

Name Type Description
id String The unique ID of the tag. Is not user updateable
name String The name of the tag
color String Tag color, displayed on a card
cardId String The card that the tag belongs to
spaceId String The space that the tag belongs to

Notifications

Notifications are created when another user adds a card in a space that you're a member and not currently viewing. The notifying user can be either a space collaborator, or anyone viewing an open space.

Notifications Routes

Routes with Auth as apiKey mean that the Authorization header apiKey must match the requested user.

Method Path Description Auth
GET /notifications Get the last 50 notifications for the current user apiKey

Notifications Attributes

Name Type Description
id String The unique ID of the notification. Is not user updateable
type String The action that created the notification (e.g. addCard)
recipientUserId String The user that'll receive the notification
cardId String The card that the notification involves
card Object Basic information about the Card id, name
spaceId String The space that the notification involves
space Object Basic information about the Space id, name, privacy, background
userId String The user that created the notification
user Object Basic information about the User id, name, color
isRead Boolean Has the notification been read by the recipient in Kinopio
isEmailed Boolean Has the notification been emailed to the recipient. Emails are only sent if user.shouldEmailNotifications = true