API documentation

Overview

The KDrive API is a REST API over HTTPS. It sends and receives JSON. You use it to manage folders and files, upload and download file content, create share links, read the event feed and receive webhooks.

Programmatic access is a Pro feature. See Pricing for the plans.

• • Base URL. https://api.kdrive.io. Every path starts with /v1/.
• • Formats. Requests and responses use JSON. Errors use application/problem+json.

Next steps: Quickstart, Authentication, Developers page.

Quickstart

1. 1
   Step 1.

   Create an API key in the web app. Open Settings, Developers, create a key, tick the scopes it needs and copy it. The key is shown once.

2. 2
   Step 2.

   Send your key to GET /v1/me. The response describes your account.

   curl -H "Authorization: Bearer $API_KEY" https://api.kdrive.io/v1/me

If the call answers 401, check the key. If it answers 403, your plan or your key's scopes do not allow it. Both are described under Errors.

Next steps: Authentication, Uploading and downloading files.

Authentication

Send your API key as a bearer token in the Authorization header. API keys are a Pro feature. You create and revoke them in the web app, under Settings, Developers.

Authorization: Bearer <your key>

Scopes

A key can do only what its scopes allow. A request that needs a scope the key lacks fails with 403.

Next steps: Errors, Manage your keys.

Requests and responses

These conventions apply to every operation. The reference lists the exact fields of each one.

• • Content type. Send JSON bodies with Content-Type: application/json.
• • Identifiers. Identifiers are opaque strings. Store and send them as they are.
• • Timestamps. Timestamps are RFC 3339 date-times.
• • Request ids. Every response carries a Kdrive-Request-Id header. Quote it when you ask for help.

Next steps: Errors, Pagination.

Errors

A failed request answers with a problem document ( application/problem+json) that holds status, code, detail and request_id. Branch on the code, not on the detail text.

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "code": "plan_feature_required",
  "detail": "...",
  "request_id": "req_..."
}

The reference lists every error code.

Next steps: Rate limits, Reference.

Pagination

Lists are paged with cursors. When more results exist, the response carries next_cursor. Send it back as the cursor parameter to continue, and stop when it is empty. The event feed continues with the after parameter instead. Treat cursors as opaque.

Rate limits

Limits apply to the API. When one is reached the API answers 429; wait for the number of seconds in the Retry-After header before you try again.

Uploading and downloading files

File content does not travel through the JSON calls. The API tells you where to send it.

1. 1
   Step 1.

   Start an upload with createUpload. The response says how the content is to be sent and gives the URLs to use.

2. 2
   Step 2.

   Send the content to the URLs the API returned, in the way the response describes. Follow the response; do not assume a mode.

3. 3
   Step 3.

   Finish with completeUpload. If it names parts that are missing, send those and complete again. Use getUpload to see where an upload stands and abortUpload to cancel it.

To download, ask for a download URL with createDownloadUrl and fetch the content from the URL it returns, or call downloadFileContent and follow its redirect.

Next steps: Errors, Reference.

Webhooks

A webhook endpoint receives an HTTPS POST with a JSON event for each change you subscribe to. You manage endpoints through the API with the webhook scopes.

Events

Verify a delivery

Every delivery carries three headers. Check the signature before you trust the body.

• • Kdrive-Webhook-Id: the id of the event.
• • Kdrive-Webhook-Timestamp: the time the delivery was signed.
• • Kdrive-Webhook-Signature: the signature, which starts with v1=.

The signature is the HMAC-SHA256 hex digest of the timestamp, a dot, the id, a dot and the raw request body, keyed with the endpoint's secret, prefixed with v1=. Compare it with the header in constant time, and reject a delivery whose timestamp is too old. Answer with a 2xx status once you have accepted the event.

Next steps: Authentication, Reference.

Reference

The reference lists every supported operation with its parameters, request bodies, responses, error codes and examples. It is generated from the API contract, so it always matches the API.

Next steps: Quickstart, Errors.

Support

Email [email protected] and include the request id of the failed response. Never send an API key or a webhook secret.

For legal questions see the Terms and Privacy pages.

Next steps: Developers page, Pricing, API keys.