Graniite Docs
REST API overviewItems

Add the item to one or more folders.

Idempotent — re-adding an existing (folder, item) pair is silently absorbed. Single-folder scope tokens get 403 forbidden_scope (no destination to add TO). Multi-folder scope tokens require every target folder to be in scope; out-of-scope targets surface as 403 with the offending ids. Per-token rate limit: 60/hr.

POST
/items/{id}/folders

Idempotent — re-adding an existing (folder, item) pair is silently absorbed. Single-folder scope tokens get 403 forbidden_scope (no destination to add TO). Multi-folder scope tokens require every target folder to be in scope; out-of-scope targets surface as 403 with the offending ids. 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

Path Parameters

id*string
Formatuuid

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/items/497f6eca-6276-4993-bfeb-53cbbbba6f08/folders" \  -H "Content-Type: application/json" \  -d '{    "folder_ids": [      "c9c54c2c-7793-4b70-8b93-7e3771bbc0c0"    ]  }'
{
  "ok": true,
  "added_folder_ids": [
    "15fefa61-4a2e-4b26-a05d-2af53e7cb618"
  ]
}
{
  "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
}

List folders the token can see. GET

Returns folders in the token's scope. Unscoped tokens get the user's full folder list; scoped tokens get only the folders they were minted against. Each row includes item_count. Per-token rate limit: 1000/hr.

Delete an item. DELETE

Write capability. Scoped tokens require ≥1 in-scope folder membership; out-of-scope returns 404. Cascade is automatic: outputs / chunks / folder_items via FK CASCADE; manual-upload storage objects queued by the delete_orphan_manual_content trigger for the 30-min cron drainer. Per-token rate limit: 30/hr.