REST API overview

The REST API at https://graniite.co/api/v1 is the management surface. It provides full CRUD over folders, items, and memberships, plus ingest and uploads. Use it from scripts, automations (n8n, Zapier), and any client that prefers HTTP over JSON-RPC.

For agent-time read and add operations from inside a conversation, see the MCP server. For guidance on which to use, see MCP vs REST.

Auth

Every endpoint requires a bearer token:

Authorization: Bearer lev_…

Tokens are minted at /settings/integrations. See Authentication for the capability and scope model and how to pick a token shape for your use case.

OpenAPI spec

The full spec is hosted at:

https://graniite.co/api/v1/openapi.json

Drop it into any OpenAPI-aware tool to get interactive endpoint exploration:

• Postman: Import, then Link
• Insomnia: Import, then From URL
• LangChain: OpenAPIToolkit.from_url(...)
• LlamaIndex: OpenAPIToolSpec(spec_url=...)
• Mintlify or Scalar if you are building docs of your own

Endpoint reference

Each endpoint below has a dedicated page with parameter schemas, request and response examples, and code samples in curl, JavaScript, Python, and Go, auto-generated from the OpenAPI spec.

Knowledge

• POST /ingest: URL or text ingest

Folders

• GET /folders
• POST /folders
• DELETE /folders/{id}

Items

• GET /items
• GET /items/{id}
• DELETE /items/{id}
• POST /items/{id}/folders: add memberships
• DELETE /items/{id}/folders/{folderId}: remove one membership

Uploads (three-step binary flow)

The reference pages document each step in isolation. For the full end-to-end walkthrough (including the client-side PUT in step 2), see the binary upload quickstart.

• POST /uploads/signed-url: Step 1, request a signed Storage URL
• Client PUTs binary to the signed URL (Step 2, no API call)
• POST /uploads/finalize: Step 3 for audio and video
• POST /uploads/finalize-document: Step 3 for PDF and image

Error reference

See Errors.

Rate limits

Per-token, per-endpoint family. Read endpoints get 1000/hr. Ingest and membership writes get 60/hr. Folder and item delete gets 30/hr. Full table on the errors page.