# OpenAPI/Swagger Documentation - Claw Ecosystem API

**Version:** 1.0.0  
**Base URL:** https://claw-news.com/api  
**Documentation:** https://claw-news.com/agents/api-documentation.md

```yaml
openapi: 3.0.3
info:
  title: Claw Ecosystem API
  description: |
    Agent-first API for discovering, comparing, and selecting OpenClaw variants.
    
    ## Overview
    - 18+ Claw variants tracked
    - Schema.org compliant data
    - Semantic search capabilities
    - Real-time ecosystem statistics
    
    ## Authentication
    No authentication required for read endpoints.
    
    ## Rate Limits
    - 100 requests/minute per IP
    - Burst: 10 requests/second
    
    ## Response Format
    All responses are JSON with appropriate Content-Type headers.

  version: 1.0.0
  contact:
    name: claw-news
    url: https://claw-news.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://claw-news.com/api
    description: Production

tags:
  - name: Variants
    description: Claw variant discovery and listing
  - name: Search
    description: Semantic search capabilities
  - name: Comparison
    description: Side-by-side variant comparison
  - name: Statistics
    description: Ecosystem-wide metrics
  - name: Analytics
    description: API usage analytics

paths:
  /claws:
    get:
      tags:
        - Variants
      summary: Get all Claw variants
      description: Returns all Claw AI agent variants with full metadata including name, description, developer, memory usage, and more.
      operationId: getAllVariants
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClawVariant'
              example:
                - id: 1
                  slug: openclaw
                  name: OpenClaw
                  developer: "Peter Steinberger (Community)"
                  language: "TypeScript / Node.js"
                  positioning: "Original Framework"
                  description: "The open-source AI agent that became fastest-growing software ever..."
                  key_advantages: "328K+ stars, 64K+ forks, MIT license"
                  memory_footprint: "~1-2 GB"
                  binary_size: "~150 MB"
                  homepage: "https://openclaw.ai"
                  github: "https://github.com/psteinberger/openclaw"
                  category: "official"
                  added_at: "2026-03-17"
        '500':
          description: Server error

  /claws/structured:
    get:
      tags:
        - Variants
      summary: Get variants in Schema.org format
      description: Returns Claw variants formatted as Schema.org SoftwareApplication for AI agent consumption and SEO.
      operationId: getStructuredVariants
      responses:
        '200':
          description: Successful response with Schema.org data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaOrgItemList'
        '500':
          description: Server error

  /claws/search:
    get:
      tags:
        - Search
      summary: Semantic search variants
      description: Performs semantic search across variant names, descriptions, developers, and positioning fields.
      operationId: searchVariants
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query string
          example: "low memory lightweight"
      responses:
        '200':
          description: Search results with relevance scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '400':
          description: Missing query parameter
        '500':
          description: Server error

  /claws/compare:
    get:
      tags:
        - Comparison
      summary: Compare variants side-by-side
      description: Returns specified variants for direct comparison with key metrics highlighted.
      operationId: compareVariants
      parameters:
        - name: slugs
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated list of variant slugs
          example: "openclaw,nemoclaw,zeroclaw"
      responses:
        '200':
          description: Comparison data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComparisonResult'
        '404':
          description: One or more variants not found
        '500':
          description: Server error

  /ecosystem/stats:
    get:
      tags:
        - Statistics
      summary: Get ecosystem statistics
      description: Returns real-time metrics about the Claw ecosystem including total variants, categories, GitHub stars, and extreme values.
      operationId: getEcosystemStats
      responses:
        '200':
          description: Ecosystem statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EcosystemStats'
        '500':
          description: Server error

  /analytics:
    get:
      tags:
        - Analytics
      summary: Get API analytics
      description: Returns usage statistics including agent vs human traffic, uptime, and endpoint popularity.
      operationId: getAnalytics
      responses:
        '200':
          description: Analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsData'
        '500':
          description: Server error

  /agent-access/manifest.json:
    get:
      tags:
        - Variants
      summary: Get agent manifest
      description: Returns agent-first manifest with capabilities, endpoints, and usage examples.
      operationId: getAgentManifest
      responses:
        '200':
          description: Agent manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentManifest'
        '500':
          description: Server error

components:
  schemas:
    ClawVariant:
      type: object
      required:
        - id
        - slug
        - name
        - category
      properties:
        id:
          type: integer
          description: Unique identifier
          example: 1
        slug:
          type: string
          description: URL-safe identifier
          example: "openclaw"
        name:
          type: string
          description: Display name
          example: "OpenClaw"
        developer:
          type: string
          description: Creator/organization
          example: "Peter Steinberger (Community)"
        language:
          type: string
          description: Programming language(s)
          example: "TypeScript / Node.js"
        positioning:
          type: string
          description: Market positioning
          example: "Original Framework"
        description:
          type: string
          description: Full description
        key_advantages:
          type: string
          description: Key selling points
        memory_footprint:
          type: string
          description: RAM requirement
          example: "~1-2 GB"
        binary_size:
          type: string
          description: Disk space required
          example: "~150 MB"
        homepage:
          type: string
          format: uri
          description: Official website URL
        github:
          type: string
          format: uri
          description: GitHub repository URL
        category:
          type: string
          enum: [official, enterprise, chinese-enterprise, community, platform, update]
          description: Variant category
        added_at:
          type: string
          format: date
          description: Date added to database

    SchemaOrgItemList:
      type: object
      properties:
        "@context":
          type: string
          enum: ["https://schema.org"]
        "@type":
          type: string
          enum: ["ItemList"]
        itemListElement:
          type: array
          items:
            $ref: '#/components/schemas/SoftwareApplication'

    SoftwareApplication:
      type: object
      properties:
        "@type":
          type: string
          enum: ["SoftwareApplication"]
        name:
          type: string
        description:
          type: string
        applicationCategory:
          type: string
          enum: ["AI Agent"]
        operatingSystem:
          type: string
          enum: ["Cross-platform"]
        offers:
          $ref: '#/components/schemas/Offer'
        url:
          type: string
          format: uri

    Offer:
      type: object
      properties:
        "@type":
          type: string
          enum: ["Offer"]
        price:
          type: string
        priceCurrency:
          type: string
          enum: ["USD"]
        availability:
          type: string
          enum: ["https://schema.org/InStock"]

    SearchResults:
      type: object
      properties:
        query:
          type: string
        results:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              relevance_score:
                type: number
                format: float
              match_fields:
                type: array
                items:
                  type: string
              description:
                type: string
        total:
          type: integer
        search_time_ms:
          type: integer

    ComparisonResult:
      type: object
      properties:
        comparison:
          type: array
          items:
            $ref: '#/components/schemas/ClawVariant'
        metrics:
          type: object
          properties:
            lowest_memory:
              type: string
            smallest_binary:
              type: string
            most_stars:
              type: string

    EcosystemStats:
      type: object
      properties:
        total_variants:
          type: integer
        categories:
          type: object
          additionalProperties:
            type: integer
        total_github_stars:
          type: integer
        average_memory:
          type: string
        lightest_variant:
          type: object
          properties:
            name:
              type: string
            memory:
              type: string
            binary:
              type: string
        heaviest_variant:
          type: object
          properties:
            name:
              type: string
            memory:
              type: string
        last_updated:
          type: string
          format: date-time

    AnalyticsData:
      type: object
      properties:
        uptime_seconds:
          type: integer
        total_requests:
          type: integer
        agent_requests:
          type: integer
        human_requests:
          type: integer
        agent_percentage:
          type: number
          format: float
        top_endpoints:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              count:
                type: integer

    AgentManifest:
      type: object
      properties:
        name:
          type: string
        version:
          type: string
        description:
          type: string
        capabilities:
          type: array
          items:
            type: string
        endpoints:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              method:
                type: string
              description:
                type: string
        examples:
          type: array
          items:
            type: object

  securitySchemes: {}

security: []

```

## Usage Examples

### Python
```python
import requests

# Get all variants
response = requests.get('https://claw-news.com/api/claws')
variants = response.json()

# Search semantically
response = requests.get('https://claw-news.com/api/claws/search', params={'q': 'lightweight'})
results = response.json()

# Compare variants
response = requests.get('https://claw-news.com/api/claws/compare', params={'slugs': 'openclaw,nemoclaw'})
comparison = response.json()
```

### JavaScript
```javascript
// Get all variants
const response = await fetch('https://claw-news.com/api/claws');
const variants = await response.json();

// Search
const search = await fetch('https://claw-news.com/api/claws/search?q=minimal');
const results = await search.json();

// Compare
const compare = await fetch('https://claw-news.com/api/claws/compare?slugs=openclaw,zeroclaw');
const data = await compare.json();
```

### cURL
```bash
# Get all variants
curl https://claw-news.com/api/claws

# Search
curl "https://claw-news.com/api/claws/search?q=enterprise"

# Compare
curl "https://claw-news.com/api/claws/compare?slugs=openclaw,nemoclaw"

# Stats
curl https://claw-news.com/api/ecosystem/stats
```
