Skip to content

api-reference.md

Latest commit

 

History

History
177 lines (137 loc) · 3.11 KB

api-reference.md

File metadata and controls

177 lines (137 loc) · 3.11 KB

AI Ranch API Reference

Overview

The AI Ranch provides a RESTful API for interacting with the self-evolving agent system.

Base URL

http://localhost:3000/api/ranch

Endpoints

Species

List All Species

GET /api/ranch/species

Response:

{
  "success": true,
  "data": [
    {
      "name": "cattle",
      "description": "Heavy reasoning agent for complex analysis",
      "capabilities": ["reasoning", "analysis", "email-processing"],
      "fitness": 0.75,
      "generation": 2
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

Get Single Species

GET /api/ranch/species?name=cattle

Update Species

POST /api/ranch/species
Content-Type: application/json

{
  "name": "cattle",
  "updates": {
    "fitness": 0.85
  }
}

Tasks

List Tasks

GET /api/ranch/tasks

Get Active Tasks

GET /api/ranch/tasks?active=true

Create Task

POST /api/ranch/tasks
Content-Type: application/json

{
  "content": "Analyze this email and extract key action items",
  "source": {
    "type": "api",
    "channelId": "default",
    "userId": "user-123"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "task_1705315800000_abc123",
    "intent": {
      "content": "Analyze this email...",
      "source": { "type": "api", "channelId": "default", "userId": "user-123" }
    },
    "routing": {
      "species": "cattle",
      "confidence": 0.85,
      "reasoning": "Matched keywords: analyze, email"
    },
    "status": "queued"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Evolution

Get Evolution History

GET /api/ranch/evolution

Get Current Evolution Cycle

GET /api/ranch/evolution?current=true

Trigger Evolution

POST /api/ranch/evolution

Species Types

Species Description Best For
cattle Heavy reasoning Analysis, email processing
duck Network specialist API calls, webhooks
goat Navigation Pathfinding, spatial reasoning
sheep Consensus Voting, mediation
horse ETL specialist Data pipelines, batch processing
falcon Fast search Quick lookups, reconnaissance
hog Diagnostics Logging, debugging
chicken Monitoring Alerts, health checks

Task Status

Status Description
queued Task waiting in queue
routing Collie determining species
processing Species handling task
completed Task finished successfully
failed Task encountered error

Evolution Phases

  1. Evaluate - Score species fitness
  2. Cull - Remove underperforming species
  3. Breed - Create offspring from top performers
  4. Distill - Cloud training for offspring
  5. Quarantine - Test offspring in sandbox
  6. Promote - Promote successful offspring

Error Responses

{
  "success": false,
  "error": "Species 'unknown' not found",
  "timestamp": "2024-01-15T10:30:00Z"
}

Rate Limits

  • Species endpoints: 100 req/min
  • Task endpoints: 60 req/min
  • Evolution endpoints: 10 req/min