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 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
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

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/: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
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
collaborators Array List of users added to space as collaborators
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

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
POST /card Create card(s) from object(s) in request body. Body object must contain id and spaceId 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

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 id, 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
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 id, 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