<p align="center">
    <img src="../resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
</p>

<p align="center">
    <img src="../resources/logo-text.svg" alt="Provisioning" width="500"/>
</p>

# API Reference

Complete API documentation for the Provisioning platform, including REST endpoints, CLI
commands, and library interfaces.

## Available APIs

The Provisioning platform provides multiple API surfaces for different use cases and integration patterns.

### REST API

HTTP-based APIs for external integration and programmatic access.

- **[REST API Documentation](rest-api.md)** - Complete HTTP endpoint reference with 83+ endpoints
- **[Orchestrator API](orchestrator-api.md)** - Workflow execution and task management
- **[Control Center API](control-center-api.md)** - Platform management and monitoring

### Command-Line Interface

Native CLI for interactive and scripted operations.

- **[CLI Commands Reference](cli-commands.md)** - Complete reference for 111+ CLI commands
- **[Integration Examples](examples.md)** - Common integration patterns and workflows

### Nushell Libraries

Internal library APIs for extension development and customization.

- **[Nushell Libraries](nushell-libraries.md)** - Core library modules and functions

## API Categories

### Infrastructure Management

Manage cloud resources, servers, and infrastructure components.

**REST Endpoints**:

- Server Management - Create, delete, update, list servers
- Provider Integration - Cloud provider operations
- Network Configuration - Network, firewall, routing

**CLI Commands**:

- `provisioning server` - Server lifecycle operations
- `provisioning provider` - Provider configuration
- `provisioning infrastructure` - Infrastructure queries

### Service Orchestration

Deploy and manage infrastructure services and clusters.

**REST Endpoints**:

- Task Service Deployment - Install, remove, update services
- Cluster Management - Cluster lifecycle operations
- Dependency Resolution - Automatic dependency handling

**CLI Commands**:

- `provisioning taskserv` - Task service operations
- `provisioning cluster` - Cluster management
- `provisioning workflow` - Workflow execution

### Workflow Automation

Execute batch operations and complex workflows.

**REST Endpoints**:

- Workflow Submission - Submit and track workflows
- Task Status - Real-time task monitoring
- Checkpoint Recovery - Resume interrupted workflows

**CLI Commands**:

- `provisioning batch` - Batch workflow operations
- `provisioning workflow` - Workflow management
- `provisioning orchestrator` - Orchestrator control

### Configuration Management

Manage configuration across hierarchical layers.

**REST Endpoints**:

- Configuration Retrieval - Get active configuration
- Validation - Validate configuration files
- Schema Queries - Query configuration schemas

**CLI Commands**:

- `provisioning config` - Configuration operations
- `provisioning validate` - Validation commands
- `provisioning schema` - Schema management

### Security & Authentication

Manage authentication, authorization, secrets, and encryption.

**REST Endpoints**:

- Authentication - Login, token management, MFA
- Authorization - Policy evaluation, permissions
- Secrets Management - Secret storage and retrieval
- KMS Operations - Key management and encryption
- Audit Logging - Security event tracking

**CLI Commands**:

- `provisioning auth` - Authentication operations
- `provisioning vault` - Secret management
- `provisioning kms` - Key management
- `provisioning audit` - Audit log queries

### Platform Services

Control platform components and system health.

**REST Endpoints**:

- Service Health - Health checks and status
- Service Control - Start, stop, restart services
- Configuration - Service configuration management
- Monitoring - Metrics and performance data

**CLI Commands**:

- `provisioning platform` - Platform management
- `provisioning service` - Service control
- `provisioning health` - Health monitoring

## API Conventions

### REST API Standards

All REST endpoints follow consistent conventions:

**Authentication**:

```http
Authorization: Bearer <jwt-token>
```

**Request Format**:

```http
Content-Type: application/json
```

**Response Format**:

```json
{
  "status": "succes| s error",
  "data": { ... },
  "message": "Human-readable message",
  "timestamp": "2026-01-16T10:30:00Z"
}
```

**Error Responses**:

```json
{
  "status": "error",
  "error": {
    "code": "ERR_CODE",
    "message": "Error description",
    "details": { ... }
  },
  "timestamp": "2026-01-16T10:30:00Z"
}
```

### CLI Command Patterns

All CLI commands follow consistent patterns:

**Common Flags**:

- `--yes` - Skip confirmation prompts
- `--check` - Dry-run mode, show what would happen
- `--wait` - Wait for operation completion
- `--format jso| n yam| l table` - Output format
- `--verbose` - Detailed output
- `--quiet` - Minimal output

**Command Structure**:

```bash
provisioning <domain> <action> <resource> [flags]
```

**Examples**:

```bash
provisioning server create web-01 --plan medium --yes
provisioning taskserv install kubernetes --cluster prod
provisioning workflow submit deploy.ncl --wait
```

### Library Function Signatures

Nushell library functions follow consistent signatures:

**Parameter Order**:

1. Required positional parameters
2. Optional positional parameters
3. Named parameters (flags)

**Return Values**:

- Success: Returns data structure (record, table, list)
- Error: Throws error with structured message

**Example**:

```nushell
def create-server [
  name: string           # Required: server name
  --plan: string = "medium"  # Optional: server plan
  --wait                 # Optional: wait flag
] {
  # Implementation
}
```

## API Versioning

The Provisioning platform uses semantic versioning for APIs:

- **Major version** - Breaking changes to API contracts
- **Minor version** - Backwards-compatible additions
- **Patch version** - Backwards-compatible bug fixes

**Current API Version**: v1.0.0

**Version Compatibility**:

- REST API includes version in URL: `/api/v1/servers`
- CLI maintains backwards compatibility across minor versions
- Libraries use semantic import versioning

## Rate Limiting

REST API endpoints implement rate limiting to ensure platform stability:

- **Default Limit**: 100 requests per minute per API key
- **Burst Limit**: 20 requests per second
- **Headers**: Rate limit information in response headers

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642334400
```

## Authentication

All APIs require authentication except public health endpoints.

**Supported Methods**:

- **JWT Tokens** - Primary authentication method
- **API Keys** - For service-to-service integration
- **MFA** - Multi-factor authentication for sensitive operations

**Token Management**:

```bash
# Login and obtain token
provisioning auth login --user admin

# Use token in requests
curl -H "Authorization: Bearer $TOKEN"  [https://api/v1/servers](https://api/v1/servers)
```

See [Authentication Guide](../security/authentication.md) for complete details.

## API Discovery

Discover available APIs programmatically:

**REST API**:

```bash
# Get API specification (OpenAPI)
curl  [https://api/v1/openapi.json](https://api/v1/openapi.json)
```

**CLI**:

```bash
# List all commands
provisioning help --all

# Get command details
provisioning server help
```

**Libraries**:

```nushell
# List available modules
use lib_provisioning *
$nu.scope.commands | where is_custom
```

## Next Steps

- **[REST API Reference](rest-api.md)** - Explore HTTP endpoints
- **[CLI Commands](cli-commands.md)** - Master command-line tools
- **[Integration Examples](examples.md)** - See real-world usage patterns
- **[Nushell Libraries](nushell-libraries.md)** - Extend the platform

## Related Documentation

- **[Security Guide](../security/README.md)** - Authentication and authorization details
- **[Development Guide](../development/api-guide.md)** - Building with the API
- **[Orchestrator Architecture](../features/orchestrator.md)** - Workflow engine internals
