MagicStack Files API

System

Method	Path	Description
GET	/	API documentation
GET	/health	Application health check
GET	/db/health	Database connectivity check

/files File management

All /files endpoints require the X-Tenant-ID header and a Bearer token.

GET /files List files

Request

GET /files?limit=20&offset=0
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>

Query parameters

Param	Description
limit	Max records to return (default 50)
offset	Pagination offset (default 0)
any key	Filter by file property value

Response 200

{
  "data": [
    {
      "code": "ab12cd34",
      "type": "document",
      "size": 1024,
      "is_public": false,
      "public_access_type": null,
      "role": "owner",
      "properties": {
        "category": "reports"
      }
    }
  ],
  "meta": { "limit": 20, "offset": 0, "count": 1 }
}

POST /files Create a file

Request

POST /files
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "document",
  "content": "Hello, world!",
  "properties": {
    "category": "reports",
    "year": "2026"
  }
}

Use content_base64 instead of content to send binary or base64-encoded data. Only one may be provided.

Response 201

{
  "data": {
    "code": "ab12cd34",
    "type": "document",
    "size": 13,
    "content_hash": "a591a6d40b...",
    "properties": {
      "category": "reports",
      "year": "2026"
    }
  }
}

GET /files/:code Get a file with content

Request

GET /files/ab12cd34
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>

Response 200

{
  "data": {
    "code": "ab12cd34",
    "type": "document",
    "size": 13,
    "properties": { "category": "reports" },
    "role": "owner",
    "is_public": false,
    "public_access_type": null,
    "content": "Hello, world!"
  }
}

GET /files/:code/properties Get file properties (no content)

Request

GET /files/ab12cd34/properties
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>

Response 200

{
  "data": {
    "code": "ab12cd34",
    "type": "document",
    "size": 13,
    "properties": { "category": "reports" },
    "role": "owner",
    "is_public": false,
    "public_access_type": null
  }
}

PUT /files/:code Update file content and/or properties

Request

PUT /files/ab12cd34
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Updated content.",
  "properties": {
    "category": "archived"
  }
}

At least one of content or properties is required. Updating properties requires the admin role; updating content requires editor.

Response 200

{
  "data": {
    "code": "ab12cd34",
    "updated": true
  }
}

DELETE /files/:code Delete a file

Request

DELETE /files/ab12cd34
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>

Requires the owner role.

Response 200

{
  "data": { "deleted": true }
}

PUT /files/:code/object-path Update the caller's object path for a file

Request

PUT /files/ab12cd34/object-path
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>
Content-Type: application/json

{
  "object_path": "/uploads/2026/report.pdf"
}

Response 200

{
  "data": {
    "object_path": "/uploads/2026/report.pdf"
  }
}

PUT /files/:code/visibility Update file visibility

Request

PUT /files/ab12cd34/visibility
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>
Content-Type: application/json

{
  "is_public": true,
  "public_access_type": "view"
}

public_access_type values

Value	Description
`view`	Properties visible; content hidden
`content`	Properties and content both visible

Requires the owner role. Set is_public: false to make the file private; public_access_type will be set to null.

Response 200

{
  "data": {
    "is_public": true,
    "public_access_type": "view"
  }
}

/files/:code/users File user access

All file user endpoints require X-Tenant-ID and a Bearer token. Managing users requires the admin or owner role.

Roles (lowest to highest)

Role	Permissions
`viewer`	Read properties and content
`editor`	Viewer + update content
`admin`	Editor + update properties and manage users
`owner`	Admin + delete file and change visibility

GET /files/:code/users List users with access

Request

GET /files/ab12cd34/users
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>

Response 200

{
  "data": [
    {
      "user_id": 1,
      "role": "owner",
      "object_path": null
    },
    {
      "user_id": 42,
      "role": "editor",
      "object_path": "/uploads/report.pdf"
    }
  ]
}

POST /files/:code/users Add a user to a file

Request

POST /files/ab12cd34/users
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 42,
  "role": "editor"
}

Response 201

{
  "data": {
    "user_id": 42,
    "role": "editor"
  }
}

PUT /files/:code/users/:userId Update a user's role

Request

PUT /files/ab12cd34/users/42
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>
Content-Type: application/json

{
  "role": "admin"
}

Response 200

{
  "data": {
    "user_id": 42,
    "role": "admin"
  }
}

DELETE /files/:code/users/:userId Remove a user from a file

Request

DELETE /files/ab12cd34/users/42
X-Tenant-ID: your-tenant-id
Authorization: Bearer <token>

Response 200

{
  "data": { "removed": true }
}