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. You can get your apiKey in the app through User → Settings → Api Key.

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

Use your apiKey in the Authorization header of each request.

(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/public/multiple Gets public info for multiple userIds specified in a comma seperated query string (?userIds=userId_abc,userId_xyz) 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/journal-spaces Get a list of the user's Journal Spaces (i.e. spaces with moonPhase) apiKey
GET /user/removed-spaces Get Spaces removed by the authenticating user apiKey
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
description String A description of this particular user
website String The user's website, url validity is not checked
lastReadNewStuffId String The id of the last read article from the 'new stuff' newsfeed
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
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)
shouldEmailWeeklyReview Boolean Whether the user has chosen to allow weekly review emails (default to true)
shouldShowMoreAlignOptions Boolean Whether the user has chosen to view more card position alignment and distribution options (default to true)
shouldInvertZoomDirection Boolean Whether the user has chosen to invert the direction of zooming with cmd/ctrl-scroll
shouldUseLastConnectionType Boolean Whether the user has chosen to use last connection type for new connections
shouldShowCardCollaborationInfo Boolean Whether the user has chosen to show collaboration info (update date, users) inside cards
dialogFavoritesFilters String User perference for favorite spaces filter, is either null, 'currentUser', 'otherUsers'
dialogSpaceFilters String User perference for spaces filter, is either null, 'journals', 'spaces'

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.

The closed privacy state refers to Public Read Only.

Method Path Description Auth
GET /space/:spaceId Get info on a space by id canViewSpace
GET /space/explore-spaces Get a list of recently updated spaces which are open or closed and have been renamed None
GET /space/live-spaces Get a list of currently being edited spaces which are open or closed 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
GET /space/explore-spaces/feed.json RSS feed for new spaces added to Explore None
GET /space/:spaceId/feed.json RSS feed for cards recently created or updated in a space. Use ?apiKey= for private spaces 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 its 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. Possible values are new-moon, waxing-crescent, waxing-quarter, waxing-gibbous, full-moon, waning-gibbous, waning-quarter, waning-crescent
showInExplore Boolean Whether the space is shown in explore
originSpaceId String If the space was created by duplicating another space, the origin space id is recorded
editedAt String The date when card contents in the space was last added or changed
editedByUserId String The user id of the last user who edited or created a card in the space
createdAt String The date when the space was created
updatedAt String The date when any changes in the space were made including a member visiting it
background String The image url used by the space background
backgroundTint String The background color used to tint the space background

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 canViewSpace
GET /card/multiple?cardIds=cardId1,cardId2 Get info on multiple cards, up to 60 cardIds at a time canViewSpace
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
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. spaceId cannot be patched. 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 its main text
x Integer x-axis position
y Integer y-axis position
z Integer z-axis position
width Integer card width
resizeWidth Integer width of a card resized by the user. Only affects cards with images or videos
height Integer card height
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 '…')
urlPreviewIsVisible Boolean Whether the card will display a url preview (aka link unfurl)
urlPreviewUrl String The url that the card url preview is based on
urlPreviewImage String The url for the url preview image
urlPreviewFavicon String The url for the url preview favicon image
urlPreviewTitle String The title displayed in the url preview
urlPreviewDescription String The description displayed in the line of the url preview. Because most sites stuff their description tags with SEO gibberish, descriptions are only displayed for whitelisted domains. Contact support to add a domain to the whitelist.
urlPreviewErrorUrl String The last url that the preview failed on (could be a private or broken url). If this matches urlPreviewUrl, the url preview won't be created

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. spaceId cannot be patched. 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 its 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. spaceId cannot be patched. 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