API documentation

Authentication

Send your API key on every request (except folder sync when using a sync token):

• X-Api-Key: YOUR_KEY
• or Authorization: Bearer YOUR_KEY

Base URL: https://folder.ovh/api/v1

Content-Type for bodies: application/json.

Response format

Success:

{"ok":true,"data":{...}}

Error:

{"ok":false,"error":"Message"}

Common status codes: 200/201 success, 401 missing/invalid key, 403 forbidden, 404 not found, 422 validation, 429 rate limit.

Quick example

curl -H "X-Api-Key: YOUR_KEY" \
  https://folder.ovh/api/v1/me

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d "{\"body\":\"Hello #folder\"}" \
  https://folder.ovh/api/v1/posts

Account

GET /api/v1/me

Returns the authenticated user: id, username, email, bio, avatar_url, profile_url, role, timezone, daily_link_quota, links_created_today.

Folders

GET /api/v1/folders

List your folders (id, title, table_hash, item_count, public_url, …).

POST /api/v1/folders

{
  "title": "My list",
  "description": "Optional",
  "items": [
    {"name": "file.iso", "size": 1048576}
  ],
  "settings": {
    "tag": "games",
    "active": true,
    "password": "",
    "min_select_size": 0,
    "max_select_size": 0,
    "require_comment": false,
    "allow_user_edit": false,
    "need_reg": false,
    "whitelist_pattern": "",
    "blacklist_pattern": "",
    "private_note": "",
    "parent_id": 0
  }
}

title and at least one valid items[{name,size}] are required. Returns id, table_hash, public_url, item_count.

GET /api/v1/folders/{id}/items

Items for a folder you own (id, name, size, size_human).

POST /api/v1/folders/{hash}/links

{
  "ids": [12, 34, 56],
  "comment": "Optional note",
  "password": "",
  "expires_hours": 0,
  "max_views": 0
}

Creates a selective share link (/r/…). ids are folder item IDs. Respects folder quotas, size limits, filters, and approval settings.

POST /api/v1/folders/{hash}/sync

Replace all items (desktop helpers). Auth: API key (owner/co-admin) or header X-Sync-Token / body sync_token.

{
  "items": [
    {"name": "a.bin", "size": 100, "note": "", "cover_url": ""}
  ]
}

Social

Requires social features enabled on the site.

POST /api/v1/posts

{
  "body": "Hello #folder @friend",
  "folder_id": 0,
  "share_code": "",
  "media_url": "https://example.com/image.jpg",
  "media_type": "image"
}

body required (max 5000). Optional media must be http(s). May be held by moderation filters.

POST /api/v1/posts/{id}/like · DELETE /api/v1/posts/{id}/like

Like / unlike. Returns liked flag and like_count.

POST /api/v1/posts/{id}/comments

{"body":"Nice post"}

Body max 2000 characters.

GET /api/v1/users/{username}

Public profile (respects private profiles / follows).

GET /api/v1/users/{username}/posts

Recent posts for that user (visibility rules apply).

GET /api/v1/search?q=…&type=all|user|post|hashtag

q required. Returns users, posts, and/or hashtags.

Limits & notes

• Rate limits apply per user (posts, likes, comments, folder creates). Expect 429 when exceeded.
• Daily link quota and daily post limits follow your account / site settings.
• If the account requires a password reset, API calls return 403 until fixed in the panel.
• Banned accounts cannot use the API.
• Browser pick-page helpers (POST /api/gen-link, POST /api/draft) are separate session endpoints — not part of this key-based API.