Graniite Docs
REST API overviewFolders

Create a folder.

Whole-library tokens only — scoped tokens get 403 forbidden_scope because scope is fixed at mint time. Names are case-insensitive unique per user (409 name_taken on collision). Per-token rate limit: 60/hr.

POST
/folders

Whole-library tokens only — scoped tokens get 403 forbidden_scope because scope is fixed at mint time. Names are case-insensitive unique per user (409 name_taken on collision). Per-token rate limit: 60/hr.

Authorization

bearerAuth
AuthorizationBearer <token>

Per-user bearer token minted at /settings/integrations. Format: 'lev_' followed by 32 base64url chars. Each token carries a capability set (read | write) and a folder scope (whole library or a list of specific folders). Per-endpoint requirements are noted on each operation.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/folders" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{
  "folder": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "last_added_at": "2019-08-24T14:15:22Z",
    "item_count": 0
  }
}
{
  "error": "string",
  "message": "string"
}
{
  "error": "string",
  "message": "string"
}
{
  "error": "forbidden_scope",
  "message": "string",
  "out_of_scope": [
    "e247dd1e-9ba6-4526-b17b-ddce20d3d1a2"
  ]
}
{
  "error": "string",
  "message": "string"
}
{
  "error": "rate_limited",
  "retry_after_sec": 0
}

REST API overview

REST endpoints for CRUD, organization, and ingest. Companion to the MCP server.

Delete a folder. DELETE

Whole-library tokens only. By default the items in the folder survive (their other folder memberships are preserved; items whose ONLY folder was this one become unfiled). Pass ?cascade_items=true to also delete items whose only folder is this one. Folder_items + kb_access_token_folders rows cascade automatically via FK CASCADE; tokens whose last scoped folder gets deleted are auto-revoked. Per-token rate limit: 30/hr.