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 https://AIFS.Space 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

https://aifs.space

Endpoints

List Files

curl -H "Authorization: Bearer $AIFS_API_KEY" https://aifs.space/api/files

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

Read File

# Full file
curl -H "Authorization: Bearer $AIFS_API_KEY" "https://aifs.space/api/read?path=notes/todo.txt"

# Line range (1-indexed)
curl -H "Authorization: Bearer $AIFS_API_KEY" "https://aifs.space/api/read?path=notes/todo.txt&start_line=5&end_line=10"

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"}' \
  https://aifs.space/api/write

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"}' \
  https://aifs.space/api/patch

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"}' \
  https://aifs.space/api/delete

Summary (Preview)

Get first 500 chars of a file.

curl -H "Authorization: Bearer $AIFS_API_KEY" "https://aifs.space/api/summary?path=notes/long.txt"

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...\"}" \
  https://aifs.space/api/write

# Retrieve
curl -H "Authorization: Bearer $KEY" "https://aifs.space/api/read?path=sessions/2024-01-15.md"

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" "https://aifs.space/api/read?path=log.txt" | 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\"}" \
  https://aifs.space/api/write