HTTP API
Build on Yogfile with direct-to-storage transfers, realtime events, and a public JSON API.
The public API gives applications and agents the same drive used by the web and native clients. Yogfile manages identity, namespace, and policy. Signed grants send file bytes directly between the client and the storage node.
API status
Check the production control plane.
Reference client
Read the production Rust implementation.
MCP connector
Use the hosted integration instead of building one.
Conventions
- Base URL:
https://api.yogfile.com. - Send
Authorization: Bearer <token>where the reference says Bearer. - Success is wrapped as
{ "data": ... }. - Failure is
{ "error": { "code", "message", "hint", "retryable", "details" } }. - Sizes are integer bytes.
- Fields ending in
_atare Unix seconds. Fields ending in_at_msare Unix milliseconds. - An omitted or zero lifecycle means no automatic expiry.
- Bearer + idem means
Idempotency-Keyis required. - Reuse an idempotency key only for an exact retry of the same mutation.
Common response shapes
Drive listings return an array directly under data. Trash separates complete drives from item
roots so a client can restore or purge either kind explicitly.
{
"data": [{
"name": "x7k2p9",
"private": false,
"default_ttl_secs": null,
"created_at": 1787050800,
"files": 3
}]
}{
"data": {
"drives": [{
"drive_id": "x7k2p9",
"trashed_at_ms": 1787050800000,
"purge_at_ms": 1789642800000
}],
"items": [{
"id": "<uuid>",
"drive_id": "a1b2c3",
"parent_id": null,
"kind": "file",
"name": "report.pdf",
"trashed_at_ms": 1787050800000,
"purge_at_ms": 1789642800000
}],
"retention_days": 30
}
}Direct upload
The flow has three steps: request a content-bound grant, PUT the exact bytes directly to Nauka, and confirm the returned hash with Yogfile.
Compute the full 64-character BLAKE3 hash and exact byte size before asking for a grant.
FILE=report.pdf
SIZE=$(wc -c < "$FILE" | tr -d ' ')
HASH=$(b3sum "$FILE" | awk '{print $1}')
DRIVE=$(curl -sS "$API/v2/drives" \
-H "authorization: Bearer $TOKEN" | jq -r '.data[0].name')
GRANT=$(jq -nc \
--arg name "$(basename "$FILE")" \
--argjson size "$SIZE" \
--arg hash "$HASH" \
'{name:$name,size:$size,mime:"application/pdf",folder:"reports/2026",blake3:$hash,ttl_secs:0}' \
| curl -sS -X POST "$API/v2/drives/$DRIVE/uploads" \
-H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' --data-binary @-)
FILE_ID=$(printf '%s' "$GRANT" | jq -r '.data.file_id')
UPLOAD_URL=$(printf '%s' "$GRANT" | jq -r '.data.upload.url')
UPLOAD_HEADERS=()
while IFS=$'\t' read -r key value; do
UPLOAD_HEADERS+=(-H "$key: $value")
done < <(printf '%s' "$GRANT" | jq -r '.data.upload.headers | to_entries[] | [.key,.value] | @tsv')
PUT_RESULT=$(curl -sS -X PUT "$UPLOAD_URL" "${UPLOAD_HEADERS[@]}" \
--data-binary "@$FILE")
NODE_HASH=$(printf '%s' "$PUT_RESULT" | jq -r '.hash')
curl -sS -X POST "$API/v2/files/$FILE_ID/confirm" \
-H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d "{\"hash\":\"$NODE_HASH\"}"Keep credentials on the right host
Send the Yogfile Bearer token only to api.yogfile.com. Send the exact signed upload headers to
the storage URL. Never forward the Bearer token to a storage node.
Accounts and MFA
MFA is optional. Setup requires the complete account number again so a stolen Bearer token cannot install an attacker's factor. The TOTP secret and ten recovery codes are returned once.
curl -sS -X POST "$API/v2/me/mfa/totp/setup" \
-H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d "{\"account_number\":\"$ACCOUNT\"}"
curl -sS -X POST "$API/v2/me/mfa/totp/enable" \
-H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d '{
"totp_code": "123456",
"recovery_code": "<one saved recovery code>",
"device_name": "Build server"
}'| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| POST | /v2/accounts | Public | Create an anonymous account. The 16 digit credential is returned once. |
| POST | /v2/sessions | Public | Exchange an account number for a 24-hour Bearer token, or receive an MFA challenge. |
| POST | /v2/sessions/mfa | Public | Complete an MFA challenge with TOTP or a recovery code. |
| POST | /v2/sessions/refresh | Device | Rotate a revocable device token and mint a fresh session. |
| GET | /v2/me | Bearer | Read the current plan, limits, usage, and security warning. |
| GET | /v2/me/security | Bearer | Read MFA state, recovery-code count, and trusted devices. |
| POST | /v2/me/mfa/totp/setup | Bearer | Create a pending TOTP secret and ten recovery codes. |
| POST | /v2/me/mfa/totp/enable | Bearer | Verify setup and enable MFA. |
| POST | /v2/me/mfa/recovery-codes | Bearer | Replace recovery codes after a fresh factor. |
| DELETE | /v2/me/mfa | Bearer | Disable MFA after a fresh factor. |
| DELETE | /v2/me/devices/{id} | Bearer | Revoke one trusted device. |
Drives and folders
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| GET | /v2/drives | Bearer | List active drives owned by the account. |
| POST | /v2/drives | Bearer | Create a drive, optionally private or with a lifecycle policy. |
| GET | /v2/drives/{drive} | Optional | List one folder of a public drive. Private drives need owner auth or X-Drive-Passphrase. |
| PATCH | /v2/drives/{drive} | Bearer | Change privacy, passphrase, or default_ttl_secs. |
| DELETE | /v2/drives/{drive} | Bearer | Move a drive and its items to Trash for 30 days. |
| POST | /v2/drives/{drive}/restore | Bearer + idem | Restore a trashed drive. |
| DELETE | /v2/drives/{drive}/purge | Bearer + idem | Permanently purge a trashed drive. |
| POST | /v2/drives/{drive}/folders | Bearer | Create a folder path, including missing parents. |
| PATCH | /v2/folders/{id} | Bearer | Rename or move a folder. |
| DELETE | /v2/folders/{id} | Bearer | Move a folder subtree to Trash for 30 days. |
Files, links, and previews
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| POST | /v2/drives/{drive}/uploads | Bearer | Create a content-bound direct-upload grant. |
| POST | /v2/files/{id}/confirm | Bearer | Verify the node upload and make the file active. |
| GET | /v2/files/{id} | Public | Read public file metadata and preview state. |
| PATCH | /v2/files/{id} | Bearer | Rename a file or move it within its drive. |
| DELETE | /v2/files/{id} | Bearer | Move a file to Trash for 30 days. |
| POST | /v2/files/{id}/links | Bearer | Mint a signed download URL lasting 60 seconds to 24 hours. |
| GET | /v2/files/{id}/download | Public | Mint a short link and redirect to the bytes. |
| POST | /v2/files/{id}/preview | Public | Read or lazily request a safe preview rendition. |
| PUT | /v2/files/{id}/report | Public | Send a duplicate-resistant abuse signal. |
| GET | /v2/files/{id}/versions | Bearer | List retained versions of a file. |
| POST | /v2/files/{id}/versions/{version}/restore | Bearer + idem | Restore a retained content version. |
Filesystem sync surface
This lower-level surface powers native clients with client-selected UUIDs, optimistic version tokens, opaque cursors, persistent upload sessions, conflict forks, versions, and recoverable Trash.
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| GET | /v2/drives/{drive}/items | Bearer | List immediate children with an opaque stable cursor. |
| GET | /v2/drives/{drive}/changes | Bearer | Read the ordered change journal after an opaque anchor. |
| POST | /v2/drives/{drive}/items/folders | Bearer + idem | Create a folder with a client-selected UUID. |
| POST | /v2/drives/{drive}/items/uploads | Bearer + idem | Start a create or replace upload session. |
| GET | /v2/items/{id} | Bearer | Read one item and its version tokens. |
| PATCH | /v2/items/{id} | Bearer + idem | Rename, move, or change executable state with optimistic concurrency. |
| DELETE | /v2/items/{id} | Bearer + idem | Move an item subtree to Trash. |
| GET | /v2/items/{id}/content | Bearer | Mint content for a specific or current content version. |
| POST | /v2/items/{id}/copy | Bearer + idem | Copy an active file without re-uploading its bytes. |
| POST | /v2/items/{id}/restore | Bearer + idem | Restore a Trash root, resolving name conflicts safely. |
| DELETE | /v2/items/{id}/purge | Bearer + idem | Permanently purge a Trash root. |
| POST | /v2/uploads/{session}/confirm | Bearer + idem | Commit a filesystem upload session. |
| POST | /v2/uploads/{session}/fork | Bearer + idem | Keep a conflicting upload as a separate file. |
| GET | /v2/trash | Bearer | List recoverable drive and item roots with purge dates. |
Realtime wakeups
These long-held requests return after a matching mutation. Keep the returned cursor in memory and
send it on the next request. A sync: true response means the client must reload its current view.
curl -sS "$API/v2/events?cursor=$CURSOR&wait_ms=25000" \
-H "authorization: Bearer $TOKEN"{
"data": {
"cursor": 42,
"sync": false,
"events": [{
"sequence": 42,
"kind": "filesystem.changed",
"drive": "abc123",
"item_ids": ["<uuid>"],
"parent_ids": ["<folder uuid>"],
"root_changed": false
}]
}
}Bearer tokens and passphrases stay in headers, never in URLs.
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
| GET | /v2/events | Bearer | Wait for any drive, filesystem, or Trash mutation owned by the account. |
| GET | /v2/drives/{drive}/events | Optional | Wait for mutations in a public, owned, or passphrase-opened drive. |
| GET | /v2/files/{id}/events | Public | Wake an already open public file page when that file changes or disappears. |
Compatibility and support
Historical /v2/boxes aliases remain available for installed clients but should not be used in new
integrations. For implementation questions, contact support@yogfile.com
or inspect the public MCP reference client. Never send the
complete account number.