c59d348040
This commit captures the current state before implementing the composable monorepo template system. Key changes included: Infrastructure: - Add CockroachDB provisioner adapter for database provisioning - Add Redis provisioner adapter for cache provisioning - Add build events system with PostgreSQL storage - Add WebSocket endpoint for real-time build progress Code agent improvements: - Fix Claude Code adapter to use default allowed tools instead of dangerously-skip-permissions - Add context-aware stream closing for cancellation support - Improve parser tests for edge cases Build system: - Add build event constants and metrics - Remove deprecated git_operations.go (replaced by pod_git_operations.go) - Add rollback logic for multi-step provisioning operations Documentation: - Add composable-monorepo feature documentation - Add DNS/Cloudflare service documentation - Update deployment and troubleshooting guides Cookbooks: - Add fullstack-app cookbook - Refactor landing-test with shared library Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
146 lines
2.9 KiB
Markdown
146 lines
2.9 KiB
Markdown
# 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.masq-ops.orchard9.ai
|
|
```
|
|
|
|
## 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)
|