rdev/docs/guides/sdlc/api-reference.md

# SDLC API Reference

The rdev API provides REST endpoints for SDLC orchestration within project pods.

## Authentication

All endpoints require API key authentication:

```
X-API-Key: rdev_sk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Base Path

All SDLC endpoints are prefixed with `/projects/{id}/sdlc/`.

## State Endpoints

### GET /projects/{id}/sdlc/state

Get the global SDLC state for a project.

**Response:**
```json
{
  "data": {
    "version": 1,
    "project": {"name": "My Project"},
    "active_work": {"features": [...]},
    "blocked": [],
    "last_updated": "2026-01-15T10:00:00Z"
  }
}
```

### GET /projects/{id}/sdlc/next

Get the classifier's recommended next action.

**Query Parameters:**
- `feature` - Feature slug (optional, defaults to active feature)

**Response:**
```json
{
  "data": {
    "action": "CREATE_SPEC",
    "feature": "auth-flow",
    "message": "Create specification document",
    "next_command": "/spec-feature auth-flow"
  }
}
```

## Feature Endpoints

### GET /projects/{id}/sdlc/features

List all features.

**Response:**
```json
{
  "data": [
    {
      "slug": "auth-flow",
      "title": "User Authentication Flow",
      "phase": "draft",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}
```

### POST /projects/{id}/sdlc/features

Create a new feature.

**Request Body:**
```json
{
  "slug": "auth-flow",
  "title": "User Authentication Flow"
}
```

### GET /projects/{id}/sdlc/features/{slug}

Get feature details.

### DELETE /projects/{id}/sdlc/features/{slug}

Delete a feature.

### POST /projects/{id}/sdlc/features/{slug}/transition

Transition feature to a new phase.

**Request Body:**
```json
{
  "phase": "specified"
}
```

### POST /projects/{id}/sdlc/features/{slug}/block

Block a feature.

**Request Body:**
```json
{
  "reason": "Waiting for API design"
}
```

### POST /projects/{id}/sdlc/features/{slug}/unblock

Unblock a feature.

## Artifact Endpoints

### GET /projects/{id}/sdlc/features/{slug}/artifacts

Get artifact statuses for a feature.

### POST /projects/{id}/sdlc/features/{slug}/artifacts/{type}/approve

Approve an artifact.

### POST /projects/{id}/sdlc/features/{slug}/artifacts/{type}/reject

Reject an artifact.

## Task Endpoints

### GET /projects/{id}/sdlc/features/{slug}/tasks

List tasks for a feature.

### POST /projects/{id}/sdlc/features/{slug}/tasks

Add a new task.

**Request Body:**
```json
{
  "title": "Implement login handler"
}
```

### POST /projects/{id}/sdlc/features/{slug}/tasks/{taskId}/start

Start a task.

### POST /projects/{id}/sdlc/features/{slug}/tasks/{taskId}/complete

Complete a task.

### POST /projects/{id}/sdlc/features/{slug}/tasks/{taskId}/block

Block a task.

## Branch Endpoints

### POST /projects/{id}/sdlc/features/{slug}/branch

Create a feature branch.

### GET /projects/{id}/sdlc/features/{slug}/branch

Get branch status and merge checklist.

**Response:**
```json
{
  "data": {
    "branch": {
      "name": "feature/auth-flow",
      "base_branch": "main",
      "created_at": "2026-01-15T10:00:00Z"
    },
    "checklist": [],
    "ready": true
  }
}
```

### POST /projects/{id}/sdlc/features/{slug}/branch/sync

Sync feature branch with base.

## Merge and Archive Endpoints

### POST /projects/{id}/sdlc/features/{slug}/merge

Merge a feature branch.

**Request Body:**
```json
{
  "strategy": "squash"
}
```

### POST /projects/{id}/sdlc/features/{slug}/archive

Archive a released feature.

## Query Endpoints

### GET /projects/{id}/sdlc/query/blocked

List blocked features.

### GET /projects/{id}/sdlc/query/ready

List features ready for work.

### GET /projects/{id}/sdlc/query/needs-approval

List features awaiting approval.

## Orchestrator Endpoints

### POST /projects/{id}/sdlc/execute

Execute the next classifier action.

**Request Body:**
```json
{
  "feature": "auth-flow",
  "provider": "claude"
}
```

### POST /projects/{id}/sdlc/resolve

Resolve a blocker.

**Request Body:**
```json
{
  "feature": "auth-flow"
}
```

### POST /projects/{id}/sdlc/commit

Commit changes in the project.

**Request Body:**
```json
{
  "feature": "auth-flow",
  "message": "feat: implement login handler",
  "push": true
}
```

## Error Responses

All errors return:

```json
{
  "error": "error_code",
  "message": "Human readable message"
}
```

Common error codes:
- `not_initialized` - SDLC not initialized in project
- `feature_not_found` - Feature does not exist
- `feature_exists` - Feature already exists
- `invalid_transition` - Invalid phase transition
- `invalid_phase` - Unknown phase
- `merge_not_ready` - Feature not ready to merge