> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read the Semantic Layer

> Discover the catalog, folder, and document ids a grant can name.

Assigning a Semantic Layer permission needs the UUID of a catalog, folder, or document. Three read endpoints provide them, and an API key may call all three.

| Endpoint                                | Returns                                                                                                           |                                                                      |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `GET /api/v1/semantic-layer/catalog/`   | The root of the tree — the coarsest resource a grant can name.                                                    | this page                                                            |
| `GET /api/v1/semantic-layer/folders/`   | Folders you can see, paginated.                                                                                   | [reference](/platform-api/permissions/semantic-layer/list-folders)   |
| `GET /api/v1/semantic-layer/documents/` | Documents you can see, paginated. Filter with `?folder=<id>`, or `?folder=root` for documents outside any folder. | [reference](/platform-api/permissions/semantic-layer/list-documents) |

Each list is already filtered to what your key's creator can reach, so anything it returns is a resource you may name in an assignment. The playground on this page exercises the catalog root; the other two have their own pages.

<Warning>
  These endpoints are **read-only for API keys**. Creating or editing Semantic Layer documents and folders through a machine credential returns `403`; use the app or an MCP token for that.
</Warning>

## Walk the tree, then grant

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.nekt.ai"
GROUP = "b8c5e1e3-6d02-4f45-ad20-8f4b6e2d0e13"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

folders = requests.get(f"{BASE_URL}/api/v1/semantic-layer/folders/", headers=headers).json()
finance = next(f for f in folders["results"] if f["name"] == "Finance")

requests.post(
    f"{BASE_URL}/api/v1/semantic-layer/permissions/",
    headers=headers,
    json={
        "assignments": [
            {"permission_level": "viewer", "groups": [GROUP], "folders": [finance["id"]]}
        ]
    },
)
```

<Note>
  `/api/v1/context-documents/` is a legacy alias of the documents endpoint, kept while internal clients migrate. It is not part of the published API — build against `/api/v1/semantic-layer/documents/`.
</Note>

## Related

* [List Semantic Layer Folders](/platform-api/permissions/semantic-layer/list-folders) and [List Semantic Layer Documents](/platform-api/permissions/semantic-layer/list-documents) — the other two reads, with their own playgrounds.
* [Assign Semantic Layer Permissions](/platform-api/permissions/semantic-layer/assign) — what to do with the ids.
* [Semantic Layer](/semantic-layer/overview) — what the module is and how it is used in the app.


## OpenAPI

````yaml GET /api/v1/semantic-layer/catalog/
openapi: 3.0.3
info:
  title: Nekt API
  version: v1
  description: Nekt API Documentation
  contact:
    email: support@nekt.ai
servers:
  - url: https://api.nekt.ai
security: []
paths:
  /api/v1/semantic-layer/catalog/:
    get:
      tags:
        - v1
      summary: Retrieve the Semantic Layer root
      description: '`GET /semantic-layer/catalog/` -- the root of the tree.'
      operationId: v1_semantic_layer_catalog_retrieve
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticLayerCatalog'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SemanticLayerCatalog:
      type: object
      description: >-
        The root. Has no name and no parent -- it exists to hold the root-level
        items.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
      required:
        - id
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key authentication. Format: ''x-api-key: api_key'''

````