aifs

# 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.

```bash
Authorization: Bearer aifs_xxxxx
```

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

## Base URL

```
https://aifs.space
```

## Endpoints

### List Files

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

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

### Read File

```bash
# 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).

```bash
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.

```bash
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

```bash
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.

```bash
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

```bash
# 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)

```bash
# 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
```