# AIFS API Documentation

AIFS simple HTTP REST API file storage service. All requests require authentication via API key.

## Authentication

All API requests require authentication using an API key. Create API keys from the dashboard at /dashboard after signing in.

### API Key Format
API keys follow this format: aifs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


Base Domain: https://aifs.space

### Authentication Headers

Include your API key using one of these methods:

Authorization Header (Recommended):
  Authorization: Bearer aifs_your_api_key_here

X-API-Key Header:
  X-API-Key: aifs_your_api_key_here

### API Key Types

| Type       | Read | Write | Delete | List |
|------------|------|-------|--------|------|
| admin      | Yes  | Yes   | Yes    | Yes  |
| read-write | Yes  | Yes   | Yes    | Yes  |
| read-only  | Yes  | No    | No     | Yes  |
| write-only | No   | Yes   | Yes    | No   |

## Rate Limiting

Default limit is 60 requests per minute per API key.

Response headers:
- X-RateLimit-Limit: Maximum requests per minute
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Unix timestamp when limit resets

## Endpoints

### GET /api/files
List all files recursively with metadata.

Response:
{
  "files": [
    { "path": "notes/todo.txt", "size": 1024, "modifiedAt": "2024-01-15T10:30:00Z" }
  ]
}

### GET /api/read
Read file content (full or by line range).

Query parameters:
- path (required): File path relative to storage
- start_line (optional): 1-indexed start line
- end_line (optional): 1-indexed end line

Response:
{
  "path": "notes/todo.txt",
  "content": "file content here",
  "total_lines": 42,
  "returned_lines": 10
}

### POST /api/write
Create or overwrite a file. Directories are created automatically (max depth: 20).

Request body:
{
  "path": "notes/new.txt",
  "content": "Hello world"
}

Response:
{
  "success": true,
  "path": "notes/new.txt",
  "size": 11,
  "lines": 1
}

### PATCH /api/patch
Update specific lines without rewriting the entire file.

Request body:
{
  "path": "notes/todo.txt",
  "start_line": 5,
  "end_line": 10,
  "content": "replacement content"
}

Response:
{
  "success": true,
  "path": "notes/todo.txt",
  "lines_before": 42,
  "lines_after": 38
}

### DELETE /api/delete
Remove a file.

Request body:
{
  "path": "notes/old.txt"
}

Response:
{
  "success": true,
  "deleted": "notes/old.txt"
}

### GET /api/summary
Get truncated preview of a file (first 500 characters).

Query parameters:
- path (required): File path relative to storage

Response:
{
  "path": "notes/long.txt",
  "summary": "First 500 characters of the file...",
  "full_size": 5000,
  "truncated": true
}



## API Key Management

### POST /api/keys
Create a new API key.

Request body:
{
  "name": "My App Key",
  "type": "read-write",
  "rate_limit_rpm": 60
}

Response:
{
  "success": true,
  "key": "aifs_xxxxxxxxxxxxx",
  "api_key": {
    "id": "key_id",
    "name": "My App Key",
    "type": "read-write",
    "key_prefix": "aifs_xxx"
  },
  "warning": "Save this key now. It will not be shown again."
}

### GET /api/keys
List all API keys for your account.

Response:
{
  "keys": [
    {
      "id": "key_id",
      "name": "My App Key",
      "key_prefix": "aifs_xxx",
      "type": "read-write",
      "rate_limit_rpm": 60
    }
  ]
}

### DELETE /api/keys/{id}
Revoke an API key.

Response:
{
  "success": true,
  "revoked": "key_id"
}

## Error Responses

All errors return JSON:
{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Error codes:
- AUTH_REQUIRED: No authentication provided
- AUTH_FAILED: Invalid API key
- FORBIDDEN: Operation not permitted for this key type
- RATE_LIMITED: Too many requests
- NOT_FOUND: File doesn't exist
- INVALID_PATH: Path traversal or invalid path
- DEPTH_EXCEEDED: Directory depth > 20
- INVALID_RANGE: Invalid line range
- MISSING_PARAM: Required parameter missing

## Example Usage

# List files
curl -H "Authorization: Bearer aifs_xxx" https://aifs.space/api/files

# Write a file
curl -X POST -H "Authorization: Bearer aifs_xxx" \
  -H "Content-Type: application/json" \
  -d '{"path":"hello.txt","content":"Hello World!"}' \
  https://aifs.space/api/write

# Read a file
curl -H "Authorization: Bearer aifs_xxx" \
  "https://aifs.space/api/read?path=hello.txt"



## Health Check

GET /api/health (no authentication required)

Response:
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z"
}