Kinopio API

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)
`filterComments`	`Boolean`	Whether comment cards are hidden to the user
`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
`shouldShowMoreFooterControls`	`Boolean`	Whether the user has chosen to show the second row of footer controls (links, tags, etc.)
`shouldShowCardStyleActions`	`Boolean`	Whether the user has chosen to show card styling options in the card-details dialog
`shouldShowMultiCardStyleActions`	`Boolean`	Whether the user has chosen to show card styling options in the multiple-actions dialog that appears when you paint select cards
`showInExploreUpdatedAt`	`String`	When the user last opened the Explore dialog. Used to determine new/unread Explore spaces
`shouldShowCurrentSpaceTags`	`Boolean`	Whether the user has chosen should only tags in the current space in the Tags dialog
`shouldOpenLinksInNewTab`	`Boolean`	Whether the user has chosen to open card urls in a new tab by default
`dialogFavoritesFilters`	`String`	User preference for favorite spaces filter, is either `null`, `'currentUser'`, `'otherUsers'`
`dialogSpaceFilters`	`String`	User preference for spaces filter, is either `null`, `'journals'`, `'spaces'`
`defaultSpaceBackground`	`String`	User preference for a default background url to use for new spaces
`defaultSpaceBackgroundTint`	`String`	User preference for a default background color used to tint new spaces
`defaultAddSpaceId`	`String`	User preference for the default space used in kinopio.club/add, such as through browser extensions

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. Use `?textOnly=true` for card names only	`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
`isTemplate`	`Boolean`	Whether the space is a personal template
`isHidden`	`Boolean`	Whether the space is hidden from the users personal list of spaces

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)
`shouldHideUrlPreviewInfo`	`Boolean`	Whether the card will display it's url preview title and description
`shouldHideUrlPreviewImage`	`Boolean`	Whether the card will display it's url preview image
`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
`backgroundColor`	`String`	Background color for the card to display in
`isLocked`	`Boolean`	If the card is locked and cannot be selected or edited in the client unless unlocked
`isComment`	`Boolean`	If the card is a comment, an alternative to the `((comment))` name syntax

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

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`

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