# Hive — Personal Cloud

> Hive is a personal cloud API. Agents get scoped access to files organized in spaces.

## Authentication
All requests require `Authorization: Bearer <api_key>` header.
Verify your key and see its grants: POST https://hive.yaneq.com/api/auth/verify
List the spaces your key can access: GET https://hive.yaneq.com/api/spaces

## API Base
https://hive.yaneq.com/api

## Endpoints

### Files (permission-scoped)
- GET  /api/data/{space}/files           — List files (?prefix= to filter by folder; entries include byte size)
- POST /api/data/{space}/files           — Create file { path, filename, content }
- GET  /api/data/{space}/files/{path}    — Read file (returns text/plain)
- PUT  /api/data/{space}/files/{path}    — Overwrite file (text/plain body)
- PATCH /api/data/{space}/files/{path}   — Append to file { content } (auto-newline, creates if missing)
- DELETE /api/data/{space}/files/{path}  — Delete file
- GET  /api/data/{space}/search?q=       — Full-text search

### Folders
- DELETE /api/data/{space}/folders/{path} — Delete folder and all contents

## Errors
JSON: { "error": "message", "status": 404 }
401 = bad key, 403 = no permission, 404 = not found

## Full Documentation
- OpenAPI spec: https://hive.yaneq.com/openapi.yaml
- Agent guide: https://hive.yaneq.com/agents.md
- Discovery: https://hive.yaneq.com/.well-known/hive