Graniite Docs
REST API overviewItems

List items the token can see.

Paginated list. Scoped tokens see only items in folders within their scope. Lightweight shape — no transcript or outputs (use GET /items/{id} for the full item). Per-token rate limit: 1000/hr.

GET
/items

Paginated list. Scoped tokens see only items in folders within their scope. Lightweight shape — no transcript or outputs (use GET /items/{id} for the full item). Per-token rate limit: 1000/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

Query Parameters

folder_id?string

Filter to items in this folder. Must be in token scope; out-of-scope folder_id returns 404 (no existence leak).

Formatuuid
archived?string

Default excludes archived items. 'true' returns only archived. 'any' returns both.

Value in"true" | "any"
in_kb?string

Filter by in_kb flag. kbOnly tokens force in_kb=true regardless.

Value in"true" | "false" | "any"
page?integer
Default1
Range1 <= value
per_page?integer
Default20
Range1 <= value <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/items"
{
  "items": [
    {
      "user_item_id": "bdbfc5c1-4635-4d6b-a226-2cb5d7e08712",
      "content_id": "713e4c61-5a69-43fb-a600-2e2699462e14",
      "title": "string",
      "url": "string",
      "platform": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "in_kb": true,
      "archived": true,
      "read": true,
      "auto_transform": true,
      "transcription_status": "string",
      "duration_seconds": 0,
      "media_kind": "audio",
      "thumbnail_url": "string",
      "published_at": "2019-08-24T14:15:22Z"
    }
  ],
  "total": 0,
  "page": 1,
  "per_page": 1
}
{
  "error": "string",
  "message": "string"
}
{
  "error": "string",
  "message": "string"
}
{
  "error": "string",
  "message": "string"
}
{
  "error": "rate_limited",
  "retry_after_sec": 0
}

Get full item. GET

Returns metadata, transcript + segments, outputs (transforms), and folder memberships (filtered to in-scope folders only). Scoped tokens 404 on items outside scope; kbOnly tokens 404 on in_kb=false items. Per-token rate limit: 1000/hr.

Remove an item from a folder. DELETE

Removing the item's only folder is allowed — the item becomes unfiled but stays in the library. Returns 404 if the membership didn't exist (idempotent). Per-token rate limit: 60/hr.