AIFS - AI File System

AIFS.space is a simple HTTP REST API for cloud file storage. Use it to persist files across sessions, share data between agents, or store user content in the cloud.

Human

A human should sign up on and get an API key to provide to you.

Authentication

Requires API key in headers. Check for key in environment (AIFS_API_KEY) or user config.

Authorization: Bearer aifs_xxxxx

Key types: admin (full), read-write, read-only, write-only

Base URL

Endpoints

List Files

curl -H "Authorization: Bearer $AIFS_API_KEY"

Returns: {"files": [{"path": "notes/todo.txt", "size": 1024, "modifiedAt": "..."}]}

Read File

# Full file
curl -H "Authorization: Bearer $AIFS_API_KEY" ""

# Line range (1-indexed)
curl -H "Authorization: Bearer $AIFS_API_KEY" ""

Returns: {"path": "...", "content": "...", "total_lines": 42, "returned_lines": 10}

Write File

Creates directories automatically (max depth: 20).

curl -X POST -H "Authorization: Bearer $AIFS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"notes/new.txt","content":"Hello world"}' \

Returns: {"success": true, "path": "...", "size": 11, "lines": 1}

Patch File (Line Replace)

Update specific lines without rewriting entire file.

curl -X PATCH -H "Authorization: Bearer $AIFS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"notes/todo.txt","start_line":5,"end_line":10,"content":"replacement"}' \

Returns: {"success": true, "lines_before": 42, "lines_after": 38}

Delete File

curl -X DELETE -H "Authorization: Bearer $AIFS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"notes/old.txt"}' \

Summary (Preview)

Get first 500 chars of a file.

curl -H "Authorization: Bearer $AIFS_API_KEY" ""

Rate Limits

60 requests/minute per key. Check headers:

• X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset

Error Codes

Code

Meaning

AUTH_REQUIRED	No auth provided
AUTH_FAILED	Invalid key
FORBIDDEN	Key type lacks permission
RATE_LIMITED	Too many requests
NOT_FOUND	File doesn't exist
INVALID_PATH	Path traversal or invalid
DEPTH_EXCEEDED	Directory depth > 20

Common Patterns

Persist session notes

# Save
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"path\":\"sessions/$(date +%Y-%m-%d).md\",\"content\":\"# Session Notes\\n...\"}" \
  

# Retrieve
curl -H "Authorization: Bearer $KEY" ""

Organize by project

projects/
├── alpha/
│   ├── README.md
│   └── notes.md
└── beta/
    └── spec.md

Append to log (read + write)

# Read existing
EXISTING=$(curl -s -H "Authorization: Bearer $KEY" "" | jq -r .content)

# Append and write back
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"path\":\"log.txt\",\"content\":\"$EXISTING\\n$(date): New entry\"}" \