AI Dev Gateway - API Contract

Version: 1.0.0
Date: 2026-01-30
Purpose: Contract between Slack Integration and Backend Core

Overview

This contract defines the interface between two parallel development streams:

Slack Integration (frontend connector)
Backend Core (orchestration and execution)

Both teams can develop independently against this contract.

Core Endpoints

1. Start Work Session

Endpoint: POST /api/sessions/start

Request:

{
  "trigger": "slack",
  "user_id": "U123456",
  "channel_id": "C789012",
  "thread_ts": "1234567890.123456",
  "category": "ai-dev",
  "project": "proj-api-service",
  "repositories": ["domain-apis", "k8s-lab"],
  "task_title": "Implement JWT authentication",
  "task_description": "Add JWT auth to all API endpoints",
  "priority": "high",
  "suggested_complexity": "needs-architecture"
}

Response:

{
  "session_id": "sess_abc123",
  "workspace_path": ".builders/ai-dev-proj-api-service",
  "bmad_routing": {
    "suggested": "architect",
    "confidence": 0.85,
    "reason": "Security-sensitive feature requiring architectural decisions"
  },
  "status": "awaiting_routing_confirmation"
}

2. Confirm BMAD Routing

Endpoint: POST /api/sessions/{session_id}/route

Request:

{
  "routing_decision": "architect",  // architect | pm | builder | party-mode
  "user_confirmed": true
}

Response:

{
  "session_id": "sess_abc123",
  "routing": "architect",
  "status": "routing_to_architect",
  "next_action": "party_mode_consultation"
}

3. Send Message to Session

Endpoint: POST /api/sessions/{session_id}/message

Request:

{
  "message": "Use RS256 for JWT signing",
  "message_type": "user_response",  // user_response | command | feedback
  "context": {
    "question_id": "q_xyz789",
    "selected_option": "rs256"
  }
}

Response:

{
  "session_id": "sess_abc123",
  "message_received": true,
  "agent_response": "Acknowledged. Continuing with RS256..."
}

4. Request Deployment

Endpoint: POST /api/sessions/{session_id}/deploy

Request:

{
  "deployment_type": "lab",
  "namespace": "ai-dev-proj-api-service-lab",
  "branch": "feature/jwt-auth-with-ratelimit"
}

Response:

{
  "deployment_id": "dep_def456",
  "namespace": "ai-dev-proj-api-service-lab",
  "status": "awaiting_confirmation",
  "deployment_plan": {
    "namespace": "ai-dev-proj-api-service-lab",
    "domain": "api-service.builder.lab.ctoaas.co",
    "strategy": "configmap_pvc",
    "estimated_time": "30s",
    "tests": ["unit", "integration", "acceptance"]
  }
}

5. Confirm Deployment

Endpoint: POST /api/deployments/{deployment_id}/confirm

Request:

{
  "confirmed": true,
  "options": {
    "run_tests": true,
    "notify_on_complete": true
  }
}

Response:

{
  "deployment_id": "dep_def456",
  "status": "deploying",
  "progress_url": "/api/deployments/dep_def456/progress"
}

6. Get Deployment Progress (SSE)

Endpoint: GET /api/deployments/{deployment_id}/progress

Stream Format: Server-Sent Events (SSE)

Event Types:

// Progress event
{
  "event": "progress",
  "data": {
    "step": "creating_namespace",
    "status": "in_progress",
    "message": "Creating namespace: ai-dev-proj-api-service-lab"
  }
}
 
// Step complete
{
  "event": "step_complete",
  "data": {
    "step": "creating_namespace",
    "status": "complete",
    "duration_ms": 1234
  }
}
 
// Test results
{
  "event": "test_results",
  "data": {
    "test_type": "unit",
    "passed": 23,
    "failed": 0,
    "total": 23,
    "details": [...]
  }
}
 
// Deployment complete
{
  "event": "complete",
  "data": {
    "status": "success",
    "lab_url": "https://api-service.builder.lab.ctoaas.co",
    "code_server_url": "https://code.example.com/workspace/...",
    "total_duration_ms": 28000,
    "test_summary": {
      "unit": "23/23 ✓",
      "integration": "12/12 ✓",
      "acceptance": "3/3 ✓"
    }
  }
}

7. Get Session Status

Endpoint: GET /api/sessions/{session_id}

Response:

{
  "session_id": "sess_abc123",
  "status": "active",
  "current_phase": "implementation",
  "opencode_session_id": "ses_opencode123",
  "workspace_path": ".builders/ai-dev-proj-api-service",
  "git_branch": "feature/jwt-auth-with-ratelimit",
  "last_activity": "2026-01-30T20:15:00Z",
  "deployment": {
    "namespace": "ai-dev-proj-api-service-lab",
    "status": "active",
    "lab_url": "https://api-service.builder.lab.ctoaas.co"
  }
}

8. List Active Sessions

Endpoint: GET /api/sessions

Query Parameters:

user_id (optional)
status (optional): active | paused | complete
category (optional)

Response:

{
  "sessions": [
    {
      "session_id": "sess_abc123",
      "category": "ai-dev",
      "project": "proj-api-service",
      "task_title": "Implement JWT authentication",
      "status": "active",
      "created_at": "2026-01-30T18:00:00Z",
      "last_activity": "2026-01-30T20:15:00Z"
    }
  ]
}

Webhook Events (Backend → Slack)

The backend sends events to Slack via registered webhook URLs.

1. Progress Update

Payload:

{
  "event_type": "progress_update",
  "session_id": "sess_abc123",
  "channel_id": "C789012",
  "thread_ts": "1234567890.123456",
  "message": {
    "type": "progress",
    "content": "✅ Created JWT token service",
    "milestone": true
  }
}

2. Question Prompt

Payload:

{
  "event_type": "question",
  "session_id": "sess_abc123",
  "question_id": "q_xyz789",
  "channel_id": "C789012",
  "thread_ts": "1234567890.123456",
  "question": {
    "text": "Should I add rate limiting to token endpoint?",
    "options": [
      {
        "id": "yes",
        "label": "Yes (Recommended)",
        "recommended": true
      },
      {
        "id": "no",
        "label": "No"
      },
      {
        "id": "discuss",
        "label": "Discuss in New Thread"
      }
    ],
    "timeout": "2h",
    "default": "yes"
  }
}

3. Deployment Ready

Payload:

{
  "event_type": "deployment_ready",
  "session_id": "sess_abc123",
  "deployment_id": "dep_def456",
  "channel_id": "C789012",
  "thread_ts": "1234567890.123456",
  "deployment_plan": {
    "namespace": "ai-dev-proj-api-service-lab",
    "domain": "api-service.builder.lab.ctoaas.co",
    "strategy": "configmap_pvc",
    "estimated_time": "30s",
    "summary": {
      "files_changed": 12,
      "tests_written": 23,
      "branch": "feature/jwt-auth-with-ratelimit"
    }
  }
}

4. Test Results

Payload:

{
  "event_type": "test_results",
  "session_id": "sess_abc123",
  "deployment_id": "dep_def456",
  "channel_id": "C789012",
  "thread_ts": "1234567890.123456",
  "results": {
    "unit": { "passed": 23, "failed": 0, "total": 23 },
    "integration": { "passed": 12, "failed": 0, "total": 12 },
    "acceptance": { "passed": 3, "failed": 0, "total": 3 },
    "all_passing": true,
    "lab_url": "https://api-service.builder.lab.ctoaas.co",
    "code_server_url": "https://code.example.com/workspace/..."
  }
}

Error Responses

All endpoints use standard HTTP status codes and return errors in this format:

{
  "error": {
    "code": "session_not_found",
    "message": "Session sess_abc123 does not exist",
    "details": {
      "session_id": "sess_abc123",
      "suggestion": "Check session ID or create a new session"
    }
  }
}

Common Error Codes:

session_not_found (404)
invalid_request (400)
unauthorized (401)
deployment_failed (500)
opencode_error (500)

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer <slack_app_token>

Backend validates tokens against Slack API.

Rate Limiting

Standard endpoints: 60 requests/minute per user
SSE streams: 10 concurrent streams per user
Webhooks: No limit (backend → Slack)

Development Guidelines

For Slack Integration Team:

Mock the backend endpoints for local development
Use provided JSON schemas for request/response validation
Implement SSE client for deployment progress
Handle all error cases gracefully

For Backend Core Team:

Implement OpenAPI spec from this contract
Provide mock Slack webhook endpoint for testing
Emit events via webhook for all async operations
Follow error format strictly

Testing Contract Compliance

Both teams should implement contract tests:

# Slack Integration - Contract Tests
def test_start_session_contract():
    response = backend_api.post('/api/sessions/start', json={...})
    assert response.status_code == 200
    assert 'session_id' in response.json()
    assert 'bmad_routing' in response.json()
 
# Backend Core - Contract Tests  
def test_webhook_progress_contract():
    payload = {
        "event_type": "progress_update",
        "session_id": "sess_test",
        ...
    }
    response = slack_webhook.post(payload)
    assert response.status_code == 200

Version History

1.0.0 (2026-01-30): Initial contract definition

Notes

This contract is the source of truth for both teams
Changes require both teams’ approval
Breaking changes require version bump
Both teams commit to backward compatibility within major versions

Techcle Wiki

Explorer

Api Contract

AI Dev Gateway - API Contract

Overview

Core Endpoints

1. Start Work Session

2. Confirm BMAD Routing

3. Send Message to Session

4. Request Deployment

5. Confirm Deployment

6. Get Deployment Progress (SSE)

7. Get Session Status

8. List Active Sessions

Webhook Events (Backend → Slack)

1. Progress Update

2. Question Prompt

3. Deployment Ready

4. Test Results

Error Responses

Authentication

Rate Limiting

Development Guidelines

For Slack Integration Team:

For Backend Core Team:

Testing Contract Compliance

Version History

Notes

Graph View

Table of Contents