ETH-001_CHALLENGE_BOARD_MODE_API_SPEC_v1

CHALLENGE BOARD MODE API SPECIFICATION v1.0

Machine-Readable Integration Reference

Document Version: 1.0 Date: December 5, 2025 API Version: v1.0 Base URL: https://api.ethraeon.com/v1 Patent: USPTO Provisional #7 (ETH-2025-001)

QUICK REFERENCE

Core Endpoints:

POST   /mode/activate          - Activate specific mode
GET    /mode/current           - Get current mode state
POST   /mode/evaluate          - Evaluate automatic transition
GET    /mode/history           - Mode transition history
POST   /artifacts              - Create artifact
GET    /artifacts/{id}         - Retrieve artifact
PUT    /artifacts/{id}         - Update artifact
DELETE /artifacts/{id}         - Delete artifact
POST   /artifacts/{id}/relationships - Create relationship
POST   /boards                 - Create board
GET    /boards                 - List boards
GET    /boards/{id}            - Get board details
PUT    /boards/{id}/layout     - Update spatial layout
POST   /tracks                 - Create track
GET    /tracks                 - List tracks
PUT    /tracks/{id}            - Update track
GET    /tracks/{id}/dependencies - Get dependency graph

ENDPOINT CATALOG

1. MODE MANAGEMENT

POST /mode/activate

Purpose: Explicitly activate a mode (amenable, challenge, board, orchestration)

Request Body:

{
  "target_mode": "challenge|amenable|board|orchestration",
  "reason": "string (optional)",
  "context": {
    "conversation_id": "string",
    "previous_exchanges": "integer"
  },
  "persist": true
}

Response (200 OK):

{
  "success": true,
  "mode_state": {
    "mode_id": "uuid",
    "user_id": "uuid",
    "current_mode": "challenge",
    "behavioral_contract": {
      "response_style": "multi_frame",
      "challenge_threshold": 1.0,
      "artifact_creation": true,
      "multi_frame_analysis": true
    },
    "activation_timestamp": "ISO 8601 datetime"
  }
}

Error Codes: - 400 - Invalid mode or transition - 401 - Unauthorized - 429 - Rate limit exceeded

GET /mode/current

Purpose: Retrieve user’s current mode state

Response (200 OK):

{
  "user_id": "uuid",
  "current_mode": "challenge",
  "behavioral_contract": {
    "mode": "challenge",
    "response_style": "multi_frame",
    "challenge_threshold": 1.0,
    "artifact_creation": true,
    "multi_frame_analysis": true
  },
  "activation_timestamp": "ISO 8601 datetime",
  "session_id": "uuid"
}

POST /mode/evaluate

Purpose: Evaluate if automatic mode transition should occur

Request Body:

{
  "user_input": "string",
  "context": {
    "conversation_history": [],
    "current_mode": "amenable"
  }
}

Response (200 OK):

{
  "should_transition": true,
  "target_mode": "challenge",
  "confidence": 0.85,
  "reason": "Strategic decision detected",
  "analysis": {
    "ambiguity_score": 0.7,
    "strategic_keywords_found": ["should", "option"],
    "recommendation": "ACTIVATE_CHALLENGE_MODE"
  }
}

GET /mode/history

Purpose: Retrieve mode transition history

Query Parameters: - limit (integer, default: 50, max: 500) - offset (integer, default: 0) - start_date (ISO date, optional) - end_date (ISO date, optional)

Response (200 OK):

{
  "total": 142,
  "limit": 50,
  "offset": 0,
  "transitions": [
    {
      "transition_id": "uuid",
      "from_mode": "amenable",
      "to_mode": "challenge",
      "timestamp": "ISO 8601 datetime",
      "reason": "Ambiguity detected",
      "confidence": 0.8
    }
  ]
}

2. ARTIFACT MANAGEMENT

POST /artifacts

Purpose: Create new artifact from substantial content

Request Body:

{
  "title": "string (1-255 chars)",
  "content": "string",
  "artifact_type": "concept|design|decision|note|constraint",
  "board_id": "uuid (optional)",
  "categories": ["string"],
  "metadata": {}
}

Response (201 Created):

{
  "artifact_id": "uuid",
  "title": "string",
  "artifact_type": "string",
  "board_id": "uuid",
  "categories": ["string"],
  "created_at": "ISO 8601 datetime",
  "url": "https://app.ethraeon.com/boards/{board_id}/artifacts/{artifact_id}"
}

GET /artifacts/{artifact_id}

Purpose: Retrieve specific artifact with relationships

Response (200 OK):

{
  "artifact_id": "uuid",
  "user_id": "uuid",
  "board_id": "uuid",
  "artifact_type": "design",
  "title": "string",
  "content": "string",
  "categories": ["string"],
  "metadata": {},
  "relationships": [
    {
      "target_artifact_id": "uuid",
      "relationship_type": "derives_from|contradicts|extends|requires",
      "strength": 0.8
    }
  ],
  "created_at": "ISO 8601 datetime",
  "updated_at": "ISO 8601 datetime"
}

PUT /artifacts/{artifact_id}

Purpose: Update existing artifact

Request Body:

{
  "title": "string (optional)",
  "content": "string (optional)",
  "categories": ["string"] (optional),
  "pinned": true (optional)
}

Response (200 OK):

{
  "success": true,
  "artifact_id": "uuid",
  "updated_at": "ISO 8601 datetime"
}

DELETE /artifacts/{artifact_id}

Purpose: Delete artifact (soft delete)

Response (200 OK):

{
  "success": true,
  "artifact_id": "uuid",
  "deleted_at": "ISO 8601 datetime"
}

POST /artifacts/{artifact_id}/relationships

Purpose: Create explicit relationship between artifacts

Request Body:

{
  "target_artifact_id": "uuid",
  "relationship_type": "derives_from|contradicts|extends|requires",
  "strength": 0.85
}

Relationship Types: - derives_from: Target artifact evolved from source - contradicts: Target presents opposing view to source - extends: Target builds upon source - requires: Target depends on source

Response (201 Created):

{
  "success": true,
  "relationship_id": "uuid",
  "source_artifact_id": "uuid",
  "target_artifact_id": "uuid",
  "relationship_type": "string",
  "strength": 0.85,
  "created_at": "ISO 8601 datetime"
}

3. BOARD MANAGEMENT

POST /boards

Purpose: Create new thematic board

Request Body:

{
  "name": "string (1-255 chars)",
  "board_type": "strategy|ux|technical|narrative|philosophy|constraints",
  "description": "string (optional)",
  "spatial_layout": {
    "layout_type": "grid|freeform|hierarchical"
  }
}

Response (201 Created):

{
  "board_id": "uuid",
  "name": "string",
  "board_type": "string",
  "url": "https://app.ethraeon.com/boards/{board_id}",
  "created_at": "ISO 8601 datetime"
}

GET /boards

Purpose: List all boards for user

Query Parameters: - board_type (string, optional) - limit (integer, default: 50) - offset (integer, default: 0)

Response (200 OK):

{
  "total": 23,
  "boards": [
    {
      "board_id": "uuid",
      "name": "string",
      "board_type": "string",
      "artifact_count": 47,
      "last_accessed": "ISO 8601 datetime",
      "url": "https://app.ethraeon.com/boards/{board_id}"
    }
  ]
}

GET /boards/{board_id}

Purpose: Retrieve full board with artifacts and spatial layout

Response (200 OK):

{
  "board_id": "uuid",
  "name": "string",
  "board_type": "string",
  "description": "string",
  "artifacts": [
    {
      "artifact_id": "uuid",
      "title": "string",
      "artifact_type": "concept",
      "position": {"x": 120, "y": 340}
    }
  ],
  "spatial_layout": {
    "layout_type": "freeform",
    "clusters": [
      {
        "cluster_id": "uuid",
        "artifact_ids": ["uuid1", "uuid2"],
        "centroid": {"x": 250, "y": 400}
      }
    ]
  },
  "created_at": "ISO 8601 datetime",
  "last_accessed": "ISO 8601 datetime"
}

PUT /boards/{board_id}/layout

Purpose: Update board spatial layout

Request Body:

{
  "artifacts": [
    {
      "artifact_id": "uuid",
      "position": {"x": 150, "y": 400}
    }
  ],
  "clusters": [
    {
      "cluster_id": "uuid",
      "artifact_ids": ["uuid1", "uuid2"],
      "centroid": {"x": 300, "y": 450}
    }
  ]
}

Response (200 OK):

{
  "success": true,
  "board_id": "uuid",
  "updated_at": "ISO 8601 datetime"
}

4. TRACK ORCHESTRATION

POST /tracks

Purpose: Create new orchestration track

Request Body:

{
  "track_name": "string (1-255 chars)",
  "track_type": "technical|ux|content|strategy|research",
  "description": "string (optional)",
  "dependencies": ["uuid"]
}

Response (201 Created):

{
  "track_id": "uuid",
  "track_name": "string",
  "track_type": "string",
  "status": "active",
  "progress": 0.0,
  "created_at": "ISO 8601 datetime"
}

GET /tracks

Purpose: List all tracks with status

Response (200 OK):

{
  "total_tracks": 5,
  "active_tracks": 3,
  "tracks": [
    {
      "track_id": "uuid",
      "track_name": "string",
      "track_type": "string",
      "status": "active|blocked|ready|completed|paused",
      "progress": 0.45,
      "next_action": "string",
      "dependencies": [
        {
          "track_id": "uuid",
          "track_name": "string",
          "status": "completed"
        }
      ]
    }
  ]
}

PUT /tracks/{track_id}

Purpose: Update track state

Request Body:

{
  "status": "ready|blocked|completed|paused",
  "progress": 0.65,
  "next_action": "string"
}

Response (200 OK):

{
  "success": true,
  "track_id": "uuid",
  "updated_at": "ISO 8601 datetime"
}

GET /tracks/{track_id}/dependencies

Purpose: Get track dependency graph

Response (200 OK):

{
  "track_id": "uuid",
  "dependencies": [
    {
      "track_id": "uuid",
      "track_name": "string",
      "dependency_type": "blocks|enables|informs",
      "status": "completed"
    }
  ],
  "blocked_by": [],
  "blocks": [
    {
      "track_id": "uuid",
      "track_name": "string"
    }
  ]
}

STATE MACHINE MAPPING

Endpoint → State Transition Mapping

API Endpoint State Machine Event State Change
POST /mode/activate USER_COMMAND current_mode → target_mode (IMMEDIATE)
POST /mode/evaluate AMBIGUITY_DETECTED amenable → challenge (if score > 0.6)
POST /mode/evaluate STRATEGIC_KEYWORDS amenable → challenge (if detected)
POST /mode/evaluate RESOLUTION_ACHIEVED challenge → amenable (if finalized)
POST /artifacts SUBSTANTIAL_CONTENT * → board (if criteria met)
POST /tracks PARALLEL_REQUEST * → orchestration (if multiple tracks)

State Validation Rules

Valid Transitions:

AMENABLE    → CHALLENGE, BOARD, ORCHESTRATION
CHALLENGE   → AMENABLE, BOARD
BOARD       → AMENABLE, ORCHESTRATION
ORCHESTRATION → AMENABLE

Invalid Transitions:

CHALLENGE   → ORCHESTRATION (direct)
  (Must first return to AMENABLE)

BOARD       → CHALLENGE (direct)
  (Must first return to AMENABLE)

ORCHESTRATION → CHALLENGE, BOARD (direct)
  (Must complete all tracks first)

AUTHENTICATION & AUTHORIZATION

JWT Token Authentication

Header:

Authorization: Bearer {jwt_token}

Token Structure:

{
  "user_id": "uuid",
  "email": "user@example.com",
  "tier": "individual|team|enterprise",
  "permissions": ["read", "write", "admin"],
  "exp": 1733356800,
  "iat": 1733270400
}

API Key Authentication (Alternative)

Header:

X-API-Key: eth_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

RATE LIMITING

Limits by Tier

Tier Requests/Hour Artifacts/Day Boards Total Tracks Concurrent
Individual 1,000 100 25 3
Team 5,000 500 100 6
Enterprise 20,000 Unlimited Unlimited 12

Rate Limit Headers

Response Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1733360400

ERROR HANDLING

Standard Error Response

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {},
    "timestamp": "ISO 8601 datetime",
    "request_id": "uuid"
  }
}

Error Code Reference

Code HTTP Status Description
INVALID_TRANSITION 400 Requested mode transition not valid
RESOURCE_NOT_FOUND 404 Artifact, board, or track not found
UNAUTHORIZED 401 Missing or invalid authentication
FORBIDDEN 403 Insufficient permissions
RATE_LIMIT_EXCEEDED 429 Too many requests
VALIDATION_ERROR 422 Request validation failed
INTERNAL_ERROR 500 Server error

CODE EXAMPLES

Python Client

import requests

class EthraeonClient:
    def __init__(self, api_key):
        self.base_url = "https://api.ethraeon.com/v1"
        self.headers = {
            "X-API-Key": api_key,
            "Content-Type": "application/json"
        }

    def activate_mode(self, mode, reason=None):
        response = requests.post(
            f"{self.base_url}/mode/activate",
            headers=self.headers,
            json={"target_mode": mode, "reason": reason}
        )
        return response.json()

    def evaluate_transition(self, user_input, context=None):
        response = requests.post(
            f"{self.base_url}/mode/evaluate",
            headers=self.headers,
            json={"user_input": user_input, "context": context or {}}
        )
        return response.json()

    def create_artifact(self, title, content, board_id=None):
        response = requests.post(
            f"{self.base_url}/artifacts",
            headers=self.headers,
            json={
                "title": title,
                "content": content,
                "artifact_type": "concept",
                "board_id": board_id
            }
        )
        return response.json()

# Usage
client = EthraeonClient("eth_live_your_api_key")

# Activate Challenge Mode
mode = client.activate_mode("challenge", "Strategic decision")
print(f"Mode: {mode['mode_state']['current_mode']}")

# Evaluate automatic transition
eval_result = client.evaluate_transition("Should we go with A or B?")
if eval_result['should_transition']:
    print(f"Recommend: {eval_result['target_mode']}")

# Create artifact
artifact = client.create_artifact(
    "Feature Prioritization",
    "Comprehensive framework for...",
    board_id="uuid"
)
print(f"Artifact: {artifact['url']}")

JavaScript/TypeScript Client

class EthraeonAPI {
  private apiKey: string;
  private baseUrl: string = "https://api.ethraeon.com/v1";

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async activateMode(mode: string, reason?: string) {
    const response = await fetch(`${this.baseUrl}/mode/activate`, {
      method: "POST",
      headers: {
        "X-API-Key": this.apiKey,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ target_mode: mode, reason })
    });
    return response.json();
  }

  async evaluateTransition(userInput: string, context?: object) {
    const response = await fetch(`${this.baseUrl}/mode/evaluate`, {
      method: "POST",
      headers: {
        "X-API-Key": this.apiKey,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ user_input: userInput, context: context || {} })
    });
    return response.json();
  }

  async createArtifact(title: string, content: string, boardId?: string) {
    const response = await fetch(`${this.baseUrl}/artifacts`, {
      method: "POST",
      headers: {
        "X-API-Key": this.apiKey,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        title,
        content,
        artifact_type: "concept",
        board_id: boardId
      })
    });
    return response.json();
  }
}

// Usage
const client = new EthraeonAPI("eth_live_your_api_key");

// Activate Challenge Mode
const mode = await client.activateMode("challenge", "Need alternatives");
console.log(`Mode: ${mode.mode_state.current_mode}`);

// Evaluate transition
const eval = await client.evaluateTransition("Should we go with A or B?");
if (eval.should_transition) {
  console.log(`Recommend: ${eval.target_mode}`);
}

// Create artifact
const artifact = await client.createArtifact(
  "Feature Prioritization",
  "Comprehensive framework...",
  "uuid"
);
console.log(`Artifact: ${artifact.url}`);

WEBHOOK INTEGRATION

Register Webhook

POST /webhooks

Request:

{
  "url": "https://your-app.com/webhooks/ethraeon",
  "events": [
    "mode.activated",
    "artifact.created",
    "track.completed"
  ],
  "secret": "your_webhook_secret"
}

Event Types

Event Fired When
mode.activated Mode transition occurs
mode.deactivated Mode exits
artifact.created New artifact created
artifact.updated Artifact modified
board.created New board created
track.created New track initiated
track.completed Track finishes

Webhook Payload

{
  "event": "mode.activated",
  "timestamp": "ISO 8601 datetime",
  "data": {
    "user_id": "uuid",
    "mode": "challenge",
    "reason": "Ambiguity detected"
  },
  "signature": "hmac_sha256_signature"
}

OPENAPI SCHEMA SUMMARY

OpenAPI Version: 3.0.0 Title: ETHRAEON Challenge Board Mode API Version: 1.0.0 Base URL: https://api.ethraeon.com/v1

Security Schemes: - bearerAuth (HTTP Bearer JWT) - apiKeyAuth (X-API-Key header)

Tags: - mode - Mode management endpoints - artifacts - Artifact CRUD operations - boards - Board management - tracks - Track orchestration - users - User management - webhooks - Event notifications

⟁ API SPEC v1.0 COMPLETE

Copyright © 2025 S. Jason Prohaska (ingombrante©) All Rights Reserved • Schedule A+ Enhanced IP Protection USPTO Provisional Patent #7 (ETH-2025-001)

END OF CHALLENGE BOARD MODE API SPECIFICATION v1.0