KnowYourAgent API Specification

Base URL: https://api.knowyouragent.xyz/v1

Authentication

All requests require an API key in the header:

Authorization: Bearer <api_key>

Endpoints

1. Discover Agents

GET /agents/discover

Query Parameters:

capabilities: Array of required capabilities
confidence_threshold: Minimum confidence score (0-100)
limit: Number of results (default: 10)

Example:

GET /agents/discover?capabilities=text-translation,code-generation&confidence_threshold=95&limit=5

Example Response:

{
  "status": "success",
  "agents": [
    {
      "agent_id": "GLB-NLP-OPENAI-T5X",
      "capabilities": ["text-translation", "code-generation", "text-summarization"],
      "confidence_score": 98,
      "endpoint": "https://api.agent-provider.com/agent/t5x",
      "attestations": {
        "performance": "verified",
        "security": "verified",
        "reliability": "verified"
      },
      "interaction_schema": {
        "input_format": "json",
        "output_format": "json",
        "authentication": "bearer",
        "rate_limit": 100
      },
      "pricing": {
        "model": "per-request",
        "currency": "USD",
        "rate": 0.001
      }
    }
  ],
  "total": 1
}

2. Get Agent Details

GET /agents/{agent_id}

Example:

GET /agents/GLB-NLP-OPENAI-T5X

Example Response:

{
  "status": "success",
  "agent": {
    "agent_id": "GLB-NLP-OPENAI-T5X",
    "description": "Advanced language model specializing in translation and code generation",
    "capabilities": ["text-translation", "code-generation", "text-summarization"],
    "confidence_score": 98,
    "endpoint": "https://api.agent-provider.com/agent/t5x",
    "attestations": {
      "performance": "verified",
      "security": "verified",
      "reliability": "verified"
    },
    "interaction_schema": {
      "input_format": "json",
      "output_format": "json",
      "authentication": {
        "type": "bearer",
        "token_endpoint": "https://api.agent-provider.com/auth/token"
      },
      "methods": {
        "translate": {
          "endpoint": "/translate",
          "method": "POST",
          "parameters": {
            "source_text": "string",
            "source_lang": "string",
            "target_lang": "string"
          }
        },
        "generate_code": {
          "endpoint": "/generate",
          "method": "POST",
          "parameters": {
            "prompt": "string",
            "language": "string",
            "max_length": "integer"
          }
        }
      },
      "rate_limit": 100
    },
    "pricing": {
      "model": "per-request",
      "currency": "USD",
      "rate": 0.001
    },
    "performance_metrics": {
      "avg_response_time": 0.2,
      "uptime": 99.9,
      "success_rate": 99.5
    }
  }
}

3. Verify Agent Status

GET /agents/{agent_id}/verify

Example:

GET /agents/GLB-NLP-OPENAI-T5X/verify

Example Response:

{
  "status": "success",
  "verification": {
    "agent_id": "GLB-NLP-OPENAI-T5X",
    "is_active": true,
    "last_verified": "2025-01-21T10:00:00Z",
    "attestations": {
      "performance": {
        "status": "verified",
        "last_updated": "2025-01-21T10:00:00Z",
        "proof": "0x1234..."
      },
      "security": {
        "status": "verified",
        "last_updated": "2025-01-21T10:00:00Z",
        "proof": "0x5678..."
      }
    },
    "current_load": 45,
    "availability": "ready"
  }
}

Example: Programmatic Agent Invocation Flow

Discover suitable agent:

import requests

response = requests.get(
    "https://api.knowyouragent.xyz/v1/agents/discover",
    params={
        "capabilities": ["text-translation"],
        "confidence_threshold": 95
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

agent = response.json()["agents"][0]

Get detailed interaction schema:

details = requests.get(
    f"https://api.knowyouragent.xyz/v1/agents/{agent['agent_id']}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

schema = details.json()["agent"]["interaction_schema"]

Verify agent status:

status = requests.get(
    f"https://api.knowyouragent.xyz/v1/agents/{agent['agent_id']}/verify",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if status.json()["verification"]["is_active"]:
    # Proceed with invocation using the schema
    invoke_url = f"{agent['endpoint']}{schema['methods']['translate']['endpoint']}"
    response = requests.post(
        invoke_url,
        json={
            "source_text": "Hello world",
            "source_lang": "en",
            "target_lang": "es"
        },
        headers={"Authorization": f"Bearer {agent_token}"}
    )

Error Responses

{
  "status": "error",
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "The specified agent was not found",
    "details": {
      "agent_id": "GLB-NLP-OPENAI-T5X"
    }
  }
}

Common error codes:

AGENT_NOT_FOUND: Agent does not exist
INVALID_CAPABILITIES: Requested capabilities are invalid
VERIFICATION_FAILED: Agent verification failed
RATE_LIMITED: Too many requests
UNAUTHORIZED: Invalid API key

Note

This API is currently in development. Follow us on Twitter for updates on the public beta release.