Objects and records API

Objects define the structure of your workspace data. Records hold values for an object, such as a client or project. Discover your workspace's schema before constructing write requests.

Endpoints

Paths below are relative to https://api.getkato.io/v1.

Discover objects and fields

List objects using GET /objects. Each entry includes id, slug, singularName, pluralName, and createdAt. Both object IDs and slugs work in field discovery and record creation.

Set KATO_OBJECT to an object ID or slug returned by your workspace:

curl --fail-with-body --silent --show-error \
  "https://api.getkato.io/v1/objects/$KATO_OBJECT/fields" \
  -H "Authorization: Bearer $KATO_API_KEY"

Each field includes id, slug, name, type, required, primary, readOnly, and options. Check the field type and options when forming a value. Read-only fields, including enriched fields and the system record ID, are ignored on writes.

Write requests accept field IDs or slugs in values. Unknown fields are rejected. If a slug is ambiguous, use its field ID; supply each field only once.

List and retrieve

curl --fail-with-body --silent --show-error --get \
  https://api.getkato.io/v1/records \
  -H "Authorization: Bearer $KATO_API_KEY" \
  --data-urlencode "object=$KATO_OBJECT" \
  --data-urlencode "limit=25"

The object filter is optional. Add include_archived=true to include archived records. Continue with next_cursor as described in pagination.

A record contains id, objectTypeId, title, avatarUrl, values, archived, createdBy, createdAt, and updatedAt. Response values are keyed by field ID, even when you wrote them using slugs. Keep the field definitions available to map IDs to names.

Create a record

The following example assumes your workspace has a clients object with a writable text field whose slug is name. Replace both with values from your schema.

curl --fail-with-body --silent --show-error \
  https://api.getkato.io/v1/records \
  -H "Authorization: Bearer $KATO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "object": "clients",
    "values": {
      "name": "Northlane"
    }
  }'

Supply exactly one of object (ID or slug) or the backwards-compatible object_type_id. Supply any values required by the object. The API returns the created record under data with status 201.

Update field values

Set KATO_RECORD_ID to the ID of an active record. This example uses the same name field assumption as creation.

curl --fail-with-body --silent --show-error \
  -X PATCH "https://api.getkato.io/v1/records/$KATO_RECORD_ID" \
  -H "Authorization: Bearer $KATO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"values":{"name":"Northlane Studio"}}'

Only supplied fields are merged into the record; omitted fields retain their values. Archived records must be restored before patching.

Upsert with a stable ID

For an external sync, generate and persist a UUID for each external record, then call PUT /records/:id with that same UUID on subsequent syncs.

curl --fail-with-body --silent --show-error \
  -X PUT "https://api.getkato.io/v1/records/$KATO_RECORD_UUID" \
  -H "Authorization: Bearer $KATO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"object":"clients","values":{"name":"Northlane"}}'

KATO_RECORD_UUID must be a valid UUID that you manage for this record. A new ID creates a record (201); an existing record in the same workspace and object merges supplied values (200). A conflicting ID belonging to another workspace or object returns 409. Upsert does not automatically restore an archived record.

This pattern avoids creating a new record ID on every sync. It does not provide a general exactly-once guarantee for downstream automation or webhook processing.

Archive and restore

DELETE archives the record rather than permanently erasing it:

curl --fail-with-body --silent --show-error \
  -X DELETE "https://api.getkato.io/v1/records/$KATO_RECORD_ID" \
  -H "Authorization: Bearer $KATO_API_KEY"

To restore:

curl --fail-with-body --silent --show-error \
  -X POST "https://api.getkato.io/v1/records/$KATO_RECORD_ID/restore" \
  -H "Authorization: Bearer $KATO_API_KEY"

Both operations return the record under data. Repeatedly archiving an already archived record is supported. Subscribe to record webhooks to respond to future changes.