Files

The Files API manages user file storage with folders, sharing, trash, and quota tracking.

Asset Types

Type	Description
folder	Container for other files
file	Generic uploaded file
profile_pic	User profile picture
emote	Custom emote
chat_attachment	File attached to chat message

Processing States

State	Description
pending	Awaiting processing
processing	Currently being processed
ready	Processing complete
failed	Processing failed

List Files

List files with filtering and pagination.

GET /v1/files?parent_id={folderID}&asset_type={type}&limit=100&cursor={cursor}
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
parent_id	-	Filter by parent folder (omit for root)
asset_type	-	Filter by asset type
limit	100	Max results (1-500)
cursor	-	Pagination cursor
sort	name	Sort field (name, created_at, size_bytes)

Response:

{
  "files": [
    {
      "id": "123456789",
      "owner_id": "12345",
      "parent_id": null,
      "name": "My Documents",
      "asset_type": "folder",
      "size_bytes": 0,
      "mime_type": null,
      "processing_state": null,
      "shortcode": null,
      "is_public": false,
      "created_at": 1703520000,
      "updated_at": 1703520000
    },
    {
      "id": "234567890",
      "owner_id": "12345",
      "parent_id": null,
      "name": "photo.jpg",
      "asset_type": "file",
      "size_bytes": 2048576,
      "mime_type": "image/jpeg",
      "processing_state": "ready",
      "is_public": false,
      "created_at": 1703525000,
      "updated_at": 1703525000
    }
  ],
  "next_cursor": "eyJvIjoxMDB9"
}

Get File

Get file info with folder ancestors (breadcrumb path).

GET /v1/files/{id}
Authorization: Bearer {token}

Response:

{
  "file": {
    "id": "234567890",
    "owner_id": "12345",
    "parent_id": "123456789",
    "name": "photo.jpg",
    "asset_type": "file",
    "size_bytes": 2048576,
    "mime_type": "image/jpeg",
    "processing_state": "ready",
    "is_public": false,
    "created_at": 1703525000,
    "updated_at": 1703525000
  },
  "ancestors": [
    {
      "id": "123456789",
      "name": "My Documents",
      "asset_type": "folder"
    }
  ]
}

Create Folder

Create a new folder.

POST /v1/files
Authorization: Bearer {token}

{
  "name": "New Folder",
  "asset_type": "folder",
  "parent_id": "123456789"
}

Response (201 Created):

{
  "id": "345678901",
  "owner_id": "12345",
  "parent_id": "123456789",
  "name": "New Folder",
  "asset_type": "folder",
  "size_bytes": 0,
  "is_public": false,
  "created_at": 1703530000,
  "updated_at": 1703530000
}

Error Codes:

Code	Description
FILE_PARENT_NOT_FOUND	Parent folder doesn't exist
FILE_PARENT_NOT_FOLDER	Parent is not a folder
FILE_INVALID_NAME	Invalid filename

Update File

Rename, move, or change visibility.

PATCH /v1/files/{id}
Authorization: Bearer {token}

Rename:

{
  "name": "renamed-file.jpg"
}

Move to folder:

{
  "parent_id": "123456789"
}

Move to root:

{
  "parent_id": null
}

Make public:

{
  "is_public": true
}

Response:

{
  "id": "234567890",
  "owner_id": "12345",
  "parent_id": "123456789",
  "name": "renamed-file.jpg",
  "asset_type": "file",
  "size_bytes": 2048576,
  "is_public": false,
  "created_at": 1703525000,
  "updated_at": 1703535000
}

Error Codes:

Code	Description
FILE_CYCLIC_MOVE	Cannot move folder into itself

Delete File

Move file to trash (soft delete).

DELETE /v1/files/{id}
Authorization: Bearer {token}

Response: 204 No Content

Notes:

• Deleting a folder also deletes all contents
• Files can be restored from trash

Get Download URL

Get a presigned URL to download a file.

GET /v1/files/{id}/url
Authorization: Bearer {token}

Response:

{
  "url": "https://cdn.ocvr.net/...",
  "expires_at": 1703533600
}

Trash Operations

List Trash

View deleted files.

GET /v1/trash?limit=100&cursor={cursor}
Authorization: Bearer {token}

Response:

{
  "files": [...],
  "next_cursor": null
}

Restore from Trash

Restore a deleted file.

POST /v1/trash/{id}/restore
Authorization: Bearer {token}

Response:

{
  "id": "234567890",
  "name": "restored-file.jpg",
  ...
}

File Sharing

List Shares

List all shares for a file.

GET /v1/files/{id}/shares
Authorization: Bearer {token}

Response:

[
  {
    "id": "999888777",
    "file_id": "234567890",
    "grantee_id": "67890",
    "permission": "view",
    "expires_at": 1704124800,
    "created_at": 1703520000
  }
]

Create Share

Share a file with another user.

POST /v1/files/{id}/shares
Authorization: Bearer {token}

{
  "grantee_id": "67890",
  "permission": "view",
  "expires_at": 1704124800
}

Permissions:

Permission	Description
view	Can view/download
edit	Can modify (future)

Response (201 Created):

{
  "id": "999888777",
  "file_id": "234567890",
  "grantee_id": "67890",
  "permission": "view",
  "expires_at": 1704124800,
  "created_at": 1703530000
}

Delete Share

Revoke a share.

DELETE /v1/shares/{shareID}
Authorization: Bearer {token}

Response: 204 No Content

Get Share Download URL

Download a file via a share (for grantee).

GET /v1/shares/{shareID}/url
Authorization: Bearer {token}

Response:

{
  "url": "https://cdn.ocvr.net/...",
  "expires_at": 1703533600
}

Error Codes:

Code	Description
SHARE_NOT_FOUND	Share doesn't exist
SHARE_ACCESS_DENIED	Share has expired

Quota

Get Quota

Check storage usage and limits.

GET /v1/quota
Authorization: Bearer {token}

Response:

{
  "used_bytes": 104857600,
  "limit_bytes": 5368709120,
  "available_bytes": 5263851520,
  "usage_percent": 1.95
}