REST API

GolemDrive exposes a comprehensive REST API that powers the web dashboard, CLI, and MCP server. Anything you can do in the UI, you can do through the API.

Base URL

https://api.golemdrive.com/api/v1/

All endpoints are prefixed with /api/v1/.

Authentication

The API uses Bearer token authentication with JWTs issued by Zitadel (OpenID Connect).

Include your token in every request:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

To obtain a token, authenticate through the Zitadel OIDC flow (PKCE is required for public clients). The web dashboard and CLI handle this automatically. For server-to-server integrations, use a service account with client credentials.

Key endpoints

Files and folders

Method	Endpoint	Description
GET	/api/v1/nodes/	List files and folders
POST	/api/v1/nodes/	Create a file or folder
GET	/api/v1/nodes/{id}	Get file or folder details
PUT	/api/v1/nodes/{id}	Update file metadata
DELETE	/api/v1/nodes/{id}	Delete a file or folder

Sharing

Method	Endpoint	Description
GET	/api/v1/shares/	List your share links
POST	/api/v1/shares/	Create a share link
GET	/api/v1/shares/{id}	Get share link details
PUT	/api/v1/shares/{id}	Update share settings
DELETE	/api/v1/shares/{id}	Revoke a share link

Teams

Method	Endpoint	Description
GET	/api/v1/teams/	List your teams
POST	/api/v1/teams/	Create a team
GET	/api/v1/teams/{id}/members	List team members
POST	/api/v1/teams/{id}/invite	Invite a member

Search

Method	Endpoint	Description
GET	/api/v1/search/	Search files by name and metadata

AI chatbox

Method	Endpoint	Description
POST	/api/v1/ai/chat	Send a message to the AI assistant (SSE streaming response)

Usage and quotas

Method	Endpoint	Description
GET	/api/v1/userusage/quota-limit	Get current storage and bandwidth usage

Subscriptions and payments

Method	Endpoint	Description
GET	/api/v1/payment/subscriptions/	Get current subscription details
POST	/api/v1/payment/subscriptions/	Create or change subscription

Pagination

List endpoints return paginated responses. Control pagination with query parameters:

GET /api/v1/nodes/?page=1&page_size=20

Responses are wrapped in a standard envelope:

{
  "content": [...],
  "totalElements": 142,
  "totalPages": 8,
  "page": 1,
  "pageSize": 20
}

The default page size is 20. Maximum page size varies by endpoint.

Rate limiting

The API uses token bucket rate limiting per endpoint. Each endpoint has its own rate limit. If you exceed the limit, you’ll receive a 429 Too Many Requests response with a Retry-After header indicating when you can try again.

For most endpoints, the limits are generous enough that normal usage won’t hit them. Bulk operations or tight polling loops are the most common causes of rate limiting.

Error responses

Errors follow a consistent format:

{
  "code": 400,
  "message": "Invalid request: page_size must be between 1 and 100"
}

Common status codes:

Code	Meaning
400	Bad request — check your parameters
401	Unauthorized — token missing or expired
403	Forbidden — you don’t have access to this resource
404	Not found — resource doesn’t exist
429	Rate limited — slow down and retry after the specified delay
500	Server error — something went wrong on our end

OpenAPI specifications

Each API module publishes its own OpenAPI (Swagger) specification. These specs document every endpoint, request body, query parameter, and response schema in detail.

Access the public API specs at your GolemDrive instance’s Swagger UI endpoint.

Webhooks

The API supports webhooks for real-time event notifications. See Webhooks for setup instructions and event types.

Tips for API integrations

• Always include Content-Type: application/json for request bodies
• Use page_size (snake_case), not pageSize — the API uses snake_case for query parameters
• File uploads use chunked upload — see the upload endpoint documentation for the multi-step process
• The AI chat endpoint uses Server-Sent Events (SSE) for streaming responses — use an SSE client library, not standard JSON parsing