Kanesh
GitHub ★ Star

API

API overview

Base URL, IDs, every main endpoint, the response format and errors.

Every example in the API docs comes in cURL, Node.js, Go and Python. Pick a language once and every page remembers it. Kanesh has no SDK to install: the examples use plain HTTP.

Before you start

  • Run Kanesh with Getting started and create a collection in Studio.
  • Node.js examples need Node 18 or newer. Save them as .mjs so await works at the top level.
  • Python examples use requests: pip install requests.
  • Go examples use only the standard library.

Base URL and IDs

A local install serves the API at http://127.0.0.1:8080. API paths start with /api/v1. Use HTTPS when Kanesh runs outside your machine.

Paths use IDs, not names. :workspace is a workspace ID and :collection is a collection ID. Get both from Workspaces and collections, or copy them from Studio.

Endpoints

MethodPathWhat it does
POST/api/v1/auth/loginSign in and get a token
GET/api/v1/auth/meThe signed-in user
POST/api/v1/auth/logoutRevoke the token you send
GET/api/v1/workspacesWorkspaces you can access
GET/api/v1/workspaces/:workspace/collectionsCollections and their fields
GET/api/v1/workspaces/:workspace/collections/:collection/recordsList and query records
GET/api/v1/workspaces/:workspace/collections/:collection/records/:recordGet one record
POST/api/v1/workspaces/:workspace/collections/:collection/recordsCreate a record
PATCH/api/v1/workspaces/:workspace/collections/:collection/records/:recordUpdate fields of a record
DELETE/api/v1/workspaces/:workspace/collections/:collection/records/:recordDelete a record
POST/api/v1/workspaces/:workspace/graphqlGraphQL for the workspace
GET/health/liveLiveness check, no sign-in

Import, export, files, members and roles have more endpoints. Studio’s API reference lists all of them for your workspace.

Response format

A successful response puts the result in data. List responses add pagination to meta:

{
	"data": [{ "title": "Cloud migration" }],
	"meta": {
		"request_id": "ZILI2GCARTZPNVR6JBAWQV2VMZ",
		"response_time": 1.78,
		"pagination": { "limit": 50, "offset": 0, "count": 7, "has_more": false }
	}
}

An error puts a code and a message in error:

{
	"error": { "code": "not_found", "message": "The requested resource is unavailable." },
	"meta": { "request_id": "L7DIIN4JO5XT4WPN2JQC7YCYBI", "response_time": 0.36 }
}
  • response_time is in milliseconds.
  • request_id matches the server log and the X-Request-ID header. Include it when you report a problem.
  • A delete returns 204 with no body.

Errors

The most common are 400 invalid_input, 401 authentication_required, 403 access_denied and 404 not_found. See Errors for every code, its message and what to do.

OpenAPI

Studio’s API reference exports an OpenAPI 3.1 document for your workspace. It only includes what your account may access, so you can generate a typed client with any OpenAPI tool.

Next steps

Buy me a coffee