Client API Project Data

The Client API exposes organization-scoped project data for scripts and integrations. It is useful for reading Builder projects, inspecting scenes and features, exporting structured feature metadata, and testing controlled feature and property updates.

Use Client API Keys for key delivery, scope, expiration, and audit details.

Recommended Workflow

1. Create or choose a small sandbox project in Kartorium.
2. Import GeoJSON through Builder when starting from GIS files. Map scenes support GeoJSON import from the UI.
3. Use the Client API to inspect the resulting hierarchy: project, scenes, features, and feature properties.
4. Test script writes against a small scene and confirm the result in Builder or Viewer before running the script broadly.
5. Keep the API key scoped to the resources needed for the test.

Questions to Settle Before the First Key

For a first Client API test, define these answers before writing a script:

Question	Why it matters
Is the script reading an existing project, creating new features, or both?	Read and write scopes are separate. A script that writes and then reads back its result needs both scopes.
Is the target scene a Map scene?	GeoJSON-style markers, lines, and polygons belong in Map scenes. A newly created scene defaults to Standard unless type is set to Map.
Should source GeoJSON properties remain searchable metadata?	Builder’s GeoJSON import stores source properties as feature custom fields. The Client API project-data routes expose feature properties, not feature custom fields.
Are attachments part of the first script?	The Client API file routes manage file reference metadata. Binary upload and feature-attachment association use the authenticated app upload flow.
Does the script need to clear fields or only update values?	Empty strings are treated as omitted values in PATCH-style routes, so they do not clear existing string fields.

For read-only export scripts, start with:

• projects:read
• scenes:read
• features:read

For controlled upload tests, add only the write scopes needed for the script, such as features:write for feature/property creation or updates.

Client API access starts with a Kartorium-provisioned API key. A normal browser account by itself does not create a self-service API key.

Base URL and Authentication

Production API examples use:

https://kartorium.app/api/v1

Pass the key as a bearer token:

Authorization: Bearer <your-api-key>

Do not put API keys in URLs, logs, notebooks, screenshots, or shared source files.

Reading Project Data

A project is the top-level container. Each project contains scenes, and each scene contains features. Feature properties carry display settings, line/polygon coordinate strings, and other structured metadata.

Typical read sequence:

1. GET /client/projects
2. GET /client/projects/:projectID/scenes
3. GET /client/projects/:projectID/features or GET /client/scenes/:sceneID/features
4. GET /client/features/:featureID/properties

Python example:

import os
import requests
 
BASE_URL = "https://kartorium.app/api/v1"
API_KEY = os.environ["KARTORIUM_API_KEY"]
 
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {API_KEY}"})
 
projects = session.get(f"{BASE_URL}/client/projects", timeout=30)
projects.raise_for_status()
 
for project in projects.json():
    project_id = project["id"]
    scenes = session.get(f"{BASE_URL}/client/projects/{project_id}/scenes", timeout=30)
    scenes.raise_for_status()
 
    features = session.get(f"{BASE_URL}/client/projects/{project_id}/features", timeout=30)
    features.raise_for_status()
 
    print(project["title"], len(scenes.json()), len(features.json()))

Exporting Map Features

Kartorium map features can be converted back into GeoJSON-like data by reading features and their properties:

Kartorium feature type	Geometry source
marker	feature.position, using GeoJSON coordinate order: longitude, latitude, optional altitude
line	Feature property with key = 'coordinateString'
polygon	Feature property with key = 'coordinateString'

The API does not return a single generated GeoJSON file. Export scripts compose one by fetching project features and feature properties, then mapping the Kartorium feature representation into the target format.

Creating or Updating Features

The feature creation route creates the base feature row. It does not run Builder’s GeoJSON import helper, so scripts that create map features also create the display and geometry properties those features need.

Create a feature in a scene:

POST /client/scenes/:sceneID/features
Content-Type: application/json
Authorization: Bearer <your-api-key>

{
  "type": "marker",
  "name": "Service Point A",
  "description": "Notes about the service point.",
  "position": [-105.2705, 40.015, 0],
  "visible": true
}

Create a map label by creating a marker feature and then adding marker display properties:

[
  { "type": "string", "key": "displayType", "value": "label" },
  { "type": "string", "key": "text", "value": "Service Point A" },
  { "type": "string", "key": "color", "value": "#ffffff" },
  { "type": "integer", "key": "size", "value": "0.07" }
]

Create a line or polygon by creating a line or polygon feature and then adding a coordinateString property. The value is a JSON string containing coordinate arrays:

{
  "type": "string",
  "key": "coordinateString",
  "value": "[[-105.2705,40.015,0],[-105.271,40.016,0]]"
}

Create a feature property:

POST /client/features/:featureID/properties
Content-Type: application/json
Authorization: Bearer <your-api-key>

{
  "type": "text",
  "key": "inspection_notes",
  "value": "Needs field verification before final design."
}

Update the formatted feature notes by patching the feature description:

PATCH /client/features/:featureID
Content-Type: application/json
Authorization: Bearer <your-api-key>

{
  "description": "Updated notes for this feature."
}

GeoJSON Imports

Builder’s GeoJSON import accepts GeoJSON FeatureCollection, single Feature, or raw geometry input in Map scenes. The import converts:

GeoJSON geometry	Kartorium result
Point	marker feature with default marker display properties
LineString / MultiLineString	line feature with a coordinateString property
Polygon / MultiPolygon	polygon feature with a coordinateString property

Long line and polygon coordinate arrays may be simplified during import to keep feature payloads manageable. GeoJSON properties become feature custom fields, and long string values are truncated to fit field limits.

The Client API does not accept a raw GeoJSON file upload as a single request. Scripts that upload map data translate GeoJSON into feature creation calls and supporting feature properties, or use Builder’s GeoJSON import first and then use the Client API to inspect or update the result.

GeoJSON source properties imported through Builder are feature custom fields. The Client API project-data routes expose feature rows and feature properties. If a script needs to export source GeoJSON properties, store script-readable metadata as feature properties or coordinate a custom-field export path with Kartorium.

Attachments and Files

The Client API can list and register organization file references:

• GET /client/files
• POST /client/files
• DELETE /client/files/:fileID

The file routes manage file reference metadata for files that Kartorium already knows about. They do not upload file bytes. Feature attachment links are managed through Kartorium’s authenticated application upload flow. For scripted attachment work, coordinate with Kartorium before writing file references.

Request Shapes and Common Failures

Area	Behavior
Authentication	Missing or invalid API keys return 401. Use Authorization: Bearer ... for scripts.
Scopes	Missing scopes return 403 with missing_scope. Write scopes do not imply matching read scopes.
IDs	Project, scene, feature, property, model, file, and asset IDs are positive integers. Invalid IDs return 400; IDs outside the key’s organization return 404.
Scene types	Scene type must be one of Standard, Map, 360 Image, or Virtual Tour. New scenes default to Standard.
Feature types	Map scripting normally uses marker, line, and polygon. Other feature type values exist, but the map import/export workflow should stay with those three unless Kartorium confirms the target behavior.
Feature property types	Feature property type must be one of integer, decimal, string, image, text, vector3, boolean, file, or customField. The stored value is a string.
Position, rotation, scale	These fields are three-number arrays. Validate array length and numeric values before sending requests.
Empty strings	Empty string values are normalized as omitted for most string fields on create/update routes. They do not clear an existing field in PATCH requests.
Large geometry	Property values can store large strings, but scripts should keep coordinateString compact. Builder simplifies long GeoJSON line and polygon coordinates during UI import.
Custom fields	Feature custom fields are separate from feature properties and are not exposed by the Client API project-data routes.
Interactions	Client API feature creation does not create Builder’s default click interactions. Configure interactions in Builder when Viewer click behavior matters.

Route Summary

Area	Routes
Projects	GET /client/projects, POST /client/projects, GET/PATCH/DELETE /client/projects/:projectID
Scenes	GET /client/projects/:projectID/scenes, POST /client/projects/:projectID/scenes, GET/PATCH/DELETE /client/scenes/:sceneID
Scene properties	GET/POST /client/scenes/:sceneID/properties, PATCH/DELETE /client/scenes/:sceneID/properties/:propertyID
Features	GET /client/projects/:projectID/features, GET /client/scenes/:sceneID/features, POST /client/scenes/:sceneID/features, GET/PATCH/DELETE /client/features/:featureID
Feature properties	GET/POST /client/features/:featureID/properties, PATCH/DELETE /client/features/:featureID/properties/:propertyID
Models	GET/POST /client/models, GET /client/projects/:projectID/models, GET/PATCH/DELETE /client/models/:modelID
Files	GET/POST /client/files, DELETE /client/files/:fileID
Organization	GET /client/organization