Skip to main content
GET/schema/collections/{name}

Get Collection

Returns full schema detail for a single named collection, including:

  • all columns (with type, nullability, primary-key flag, default, and vectorDimension for vector(N) columns)
  • declared relationships (from the migration policy section)
  • indexes with their current build status (active, building, or invalid)

Reserved columns are flagged with reserved: true.

Returns K9O_COLLECTION_NOT_FOUND (404) if the name does not exist in the project schema.

Requires PROJECT_MEMBER role minimum.

Parameters
name *path

The collection's name: a letter or _, then up to 62 letters, digits or _.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
401K9O_SESSION_EXPIREDYour session has expired; re-authenticate and retry.
403K9O_ACCESS_DENIEDYour account does not have the required role (PROJECT_MEMBER or higher) to view this collection's schema.
404K9O_COLLECTION_NOT_FOUNDNo collection with that name exists in this project.
Response body (200)
data *object

The collection's structure: columns, relationships, indexes and access scope, with its live row count.

name *string

The collection (table) name.

rowCount *integer

The live row count (soft-deleted rows excluded), counted without row-level security, so it can exceed what your own reads return.

rowCountIsExact *true

Always true: rowCount is an exact count, not an estimate.

lastMigrationSlug *any

The slug of the most recent migration that touched the collection; null when none did (for example a collection created outside migrations).

One of: string
or: null
lastMigrationAppliedAt *any

When that migration was applied; null when no migration touched the collection.

One of: string <date-time>
or: null
ownerColumn *any

The collection's per-subject owner column (its value is the end user's id); null for a shared collection.

One of: string
or: null
gateScope *"owner" | "none"

The gate scope the collection declares.

Default owner.

endUserScope *"owner" | "deny" | "open"

What an end user can reach. owner: only their own rows (gate scope owner with an owner column). deny: nothing (gate scope owner, no owner column). open: every row the policy allows (gate scope none).

columns *object[]

The columns, in table order.

name *string

The column name.

type *string

The column's Postgres type as format_type renders it, for example text, integer, timestamp with time zone or vector(1536).

nullable *boolean

Whether the column accepts null.

isPrimary *boolean

Whether the column is part of the primary key.

isUnique *boolean

Whether the column has a single-column unique constraint.

default *any

The column's default as a SQL expression; null when it has none.

One of: string
or: null
vectorDimension *any

For a vector(N) column, N; null for any other type.

One of: integer
or: null
reserved *boolean

True for a platform-reserved column (its name starts with _).

Reserved columns are read-only to you.

isOwnerColumn *boolean

True when this is the collection's per-subject owner column (its value is the end user's id).

protection *any

The column's field-level encryption; null for an unprotected column.

One of: object
encrypted *true

Always true for a protected column.

store *"inline" | "vault"

inline: the value is stored as ciphertext in the row. vault: the row holds a token and the value lives in the vault.

blindIndexed *boolean

An inline column with a blind index, so equality filters work.

Always false for vault.

searchable *boolean

A vault column with a deterministic token, so equality filters work.

Always false for inline.

revealGated *boolean

True when reading the plaintext requires a stated purpose (a reveal gate).

or: null
relationships *object[]

Declared relationships, by join alias.

column *string

The column holding the reference.

joinAlias *string

The name to embed the related row under in a query.

joinType *string

The join kind in query syntax: !inner or !left.

targetCollection *string

The collection the column refers to.

indexes *object[]

The collection's indexes, by name.

name *string

The index name.

columns *string[]

The indexed columns, in index order.

Expression parts are left out.

type *string

The index method, for example btree, gin or hnsw.

unique *boolean

Whether the index enforces uniqueness.

status *"active" | "building" | "invalid"

active: in use. building: still being created. invalid: creation failed; drop and recreate it.

meta *any

Request metadata: cost, timing and correlation ids.

The list adds cursor (next, totalCount null, countMethod none); both routes add a K9O_ORG_CLAIM_UNBOUND entry to warnings when the token has no org claim.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.schema.collections.get('products')

Showing example in TypeScript

Response example (200)
{
  "data": {
    "name": "string",
    "rowCount": 0,
    "rowCountIsExact": true,
    "lastMigrationSlug": "string",
    "lastMigrationAppliedAt": "string",
    "ownerColumn": "string",
    "gateScope": "owner",
    "endUserScope": "owner",
    "columns": [
      {
        "name": "string",
        "type": "string",
        "nullable": false,
        "isPrimary": false,
        "isUnique": false,
        "default": "string",
        "vectorDimension": 0,
        "reserved": false,
        "isOwnerColumn": false,
        "protection": {
          "encrypted": true,
          "store": "inline",
          "blindIndexed": false,
          "searchable": false,
          "revealGated": false
        }
      }
    ],
    "relationships": [
      {
        "column": "string",
        "joinAlias": "string",
        "joinType": "string",
        "targetCollection": "string"
      }
    ],
    "indexes": [
      {
        "name": "string",
        "columns": [
          "string"
        ],
        "type": "string",
        "unique": false,
        "status": "active"
      }
    ]
  }
}

More in Storage & Schema