# Get Collection

`GET /schema/collections/{name}` · Core · Storage & Schema

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 | In | Required | Description |
|---|---|---|---|
| `name` | path | yes | The collection's name: a letter or `_`, then up to 62 letters, digits or `_`. Example: `"products"`. |
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | The collection's structure: columns, relationships, indexes and access scope, with its live row count. |
| `data.name` | string | yes | The collection (table) name. |
| `data.rowCount` | integer | yes | The live row count (soft-deleted rows excluded), counted without row-level security, so it can exceed what your own reads return. |
| `data.rowCountIsExact` | enum (true) | yes | Always true: `rowCount` is an exact count, not an estimate. |
| `data.lastMigrationSlug` | object | yes | The slug of the most recent migration that touched the collection; null when none did (for example a collection created outside migrations). |
| _one of_ | | |  |
| _or_ | | |  |
| `data.lastMigrationAppliedAt` | object | yes | When that migration was applied; null when no migration touched the collection. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.ownerColumn` | object | yes | The collection's per-subject owner column (its value is the end user's id); null for a shared collection. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.gateScope` | enum ("owner", "none") | yes | The gate scope the collection declares. Default `owner`. |
| `data.endUserScope` | enum ("owner", "deny", "open") | yes | 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`). |
| `data.columns` | array of object | yes | The columns, in table order. |
| `data.columns.[]name` | string | yes | The column name. |
| `data.columns.[]type` | string | yes | The column's Postgres type as `format_type` renders it, for example `text`, `integer`, `timestamp with time zone` or `vector(1536)`. |
| `data.columns.[]nullable` | boolean | yes | Whether the column accepts null. |
| `data.columns.[]isPrimary` | boolean | yes | Whether the column is part of the primary key. |
| `data.columns.[]isUnique` | boolean | yes | Whether the column has a single-column unique constraint. |
| `data.columns.[]default` | object | yes | The column's default as a SQL expression; null when it has none. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.columns.[]vectorDimension` | object | yes | For a `vector(N)` column, N; null for any other type. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.columns.[]reserved` | boolean | yes | True for a platform-reserved column (its name starts with `_`). Reserved columns are read-only to you. |
| `data.columns.[]isOwnerColumn` | boolean | yes | True when this is the collection's per-subject owner column (its value is the end user's id). |
| `data.columns.[]protection` | object | yes | The column's field-level encryption; null for an unprotected column. |
| _one of_ | | |  |
| `data.columns.[]protection.encrypted` | enum (true) | yes | Always true for a protected column. |
| `data.columns.[]protection.store` | enum ("inline", "vault") | yes | `inline`: the value is stored as ciphertext in the row. `vault`: the row holds a token and the value lives in the vault. |
| `data.columns.[]protection.blindIndexed` | boolean | yes | An `inline` column with a blind index, so equality filters work. Always false for `vault`. |
| `data.columns.[]protection.searchable` | boolean | yes | A `vault` column with a deterministic token, so equality filters work. Always false for `inline`. |
| `data.columns.[]protection.revealGated` | boolean | yes | True when reading the plaintext requires a stated purpose (a reveal gate). |
| _or_ | | |  |
| `data.relationships` | array of object | yes | Declared relationships, by join alias. |
| `data.relationships.[]column` | string | yes | The column holding the reference. |
| `data.relationships.[]joinAlias` | string | yes | The name to embed the related row under in a query. |
| `data.relationships.[]joinType` | string | yes | The join kind in query syntax: `!inner` or `!left`. |
| `data.relationships.[]targetCollection` | string | yes | The collection the column refers to. |
| `data.indexes` | array of object | yes | The collection's indexes, by name. |
| `data.indexes.[]name` | string | yes | The index name. |
| `data.indexes.[]columns` | array of string | yes | The indexed columns, in index order. Expression parts are left out. |
| `data.indexes.[]type` | string | yes | The index method, for example `btree`, `gin` or `hnsw`. |
| `data.indexes.[]unique` | boolean | yes | Whether the index enforces uniqueness. |
| `data.indexes.[]status` | enum ("active", "building", "invalid") | yes | `active`: in use. `building`: still being created. `invalid`: creation failed; drop and recreate it. |
| `meta` | object | yes | 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. |


## Errors

| HTTP | Code | When |
|---|---|---|
| 401 | `K9O_SESSION_EXPIRED` | Your session has expired; re-authenticate and retry. |
| 403 | `K9O_ACCESS_DENIED` | Your account does not have the required role (PROJECT_MEMBER or higher) to view this collection's schema. |
| 404 | `K9O_COLLECTION_NOT_FOUND` | No collection with that name exists in this project. |

## Code samples

### cURL

```bash
curl -X GET 'https://<org>.api-<region>.k9o.io/@storefront/schema/collections/<name>' \
  -H 'Authorization: Bearer $K9O_TOKEN'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/schema/collections/<name>', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`
  },
});
const { data, meta } = await res.json();
```

### @k9o/core

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

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.schema.collections.get("products")
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/get-collection
