# rdev API Documentation

rdev provides a REST API for remote development environments with SSE streaming support.

## Quick Start

### 1. Get an API Key

Contact your administrator to get an API key, or create one if you have admin access:

```bash
curl -X POST https://rdev.example.com/keys \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-key",
    "scopes": ["projects:read", "projects:execute"]
  }'
```

### 2. List Projects

```bash
curl https://rdev.example.com/projects \
  -H "X-API-Key: your-key"
```

### 3. Execute a Command

```bash
curl -X POST https://rdev.example.com/projects/my-project/shell \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}'
```

### 4. Stream Output

```bash
curl -N https://rdev.example.com/projects/my-project/events?stream_id=cmd-001 \
  -H "X-API-Key: your-key"
```

## Base URL

```
https://rdev.example.com
```

## Authentication

See [authentication.md](authentication.md) for details.

All requests (except `/health`, `/ready`, `/metrics`) require authentication.

**Header:**
```
X-API-Key: rdev_xxxx...
```

Or:
```
Authorization: Bearer rdev_xxxx...
```

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/projects` | List all projects |
| GET | `/projects/{id}` | Get project details |
| POST | `/projects/{id}/claude` | Run Claude command |
| POST | `/projects/{id}/shell` | Run shell command |
| POST | `/projects/{id}/git` | Run git command |
| GET | `/projects/{id}/events` | SSE event stream |
| GET | `/keys` | List API keys |
| POST | `/keys` | Create API key |
| DELETE | `/keys/{id}` | Revoke API key |
| GET | `/health` | Liveness check |
| GET | `/ready` | Readiness check |
| GET | `/metrics` | Prometheus metrics |

## Response Format

All responses follow this format:

### Success

```json
{
  "data": { ... },
  "meta": {
    "request_id": "req-abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

### Error

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found: my-project"
  },
  "meta": {
    "request_id": "req-abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `BAD_REQUEST` | 400 | Invalid request body or parameters |
| `UNAUTHORIZED` | 401 | Missing or invalid API key |
| `FORBIDDEN` | 403 | Insufficient permissions |
| `NOT_FOUND` | 404 | Resource not found |
| `TOO_MANY_REQUESTS` | 429 | Rate limit exceeded |
| `INTERNAL_ERROR` | 500 | Server error |

## Rate Limiting

Requests are rate limited per API key:

| Limit Type | Default |
|------------|---------|
| Requests/second | 10 |
| Concurrent commands | 5 |

Headers:
```
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1642089600
```

## Related Documentation

- [Authentication Guide](authentication.md)
- [SSE Streaming Examples](sse-examples.md)
- [Error Handling](errors.md)