# toolbeacon.dev

> Telemetry collection service for AI agent tool calls. Track errors, successes, and feedback from your tools.

## Base URL

https://toolbeacon.dev

## Quick Start

1. Register your tool (no auth required):
   POST https://toolbeacon.dev/api/v1/tools
   Content-Type: application/json

   {"name": "your-tool-name"}

   Response: {"tool_id": "...", "admin_token": "adm_...", "submit_token": "sub_..."}

2. Save both tokens securely. They are shown ONCE and cannot be recovered.

3. Submit telemetry using your submit_token:
   POST /api/v1/submit
   Authorization: Bearer sub_your-token
   Content-Type: application/json

   {
     "type": "tool_call_error",
     "payload": {"error": "...", "tool_name": "...", "context": "..."},
     "version": "1.0.0"
   }

## When to Report

Report these event types in the "type" field:

- tool_call_start: Tool execution began
- tool_call_success: Tool completed successfully
- tool_call_error: Tool failed with an error
- tool_call_timeout: Tool execution timed out
- user_feedback: User provided feedback on tool output
- validation_error: Input validation failed before execution

## Request Body Examples

### tool_call_error
{
  "type": "tool_call_error",
  "payload": {
    "tool_name": "web_search",
    "error_type": "TimeoutError",
    "error_message": "Request timed out after 30s",
    "stack_trace": "...",
    "input_summary": "search query: 'latest news'",
    "duration_ms": 30000
  },
  "version": "1.0.0"
}

### tool_call_success
{
  "type": "tool_call_success",
  "payload": {
    "tool_name": "web_search",
    "duration_ms": 1250,
    "result_summary": "returned 10 results"
  },
  "version": "1.0.0"
}

### user_feedback
{
  "type": "user_feedback",
  "payload": {
    "tool_name": "code_edit",
    "feedback": "negative",
    "reason": "edit was incorrect",
    "user_comment": "Changed the wrong function"
  },
  "version": "1.0.0"
}

## API Reference

### POST /api/v1/tools
Register a new tool.

Headers (optional): Authorization: Bearer adm_... (to reuse existing admin token)
Request: {"name": "tool-name"}
- name: 1-100 chars, alphanumeric + dashes + underscores

Behavior:
- No auth header: Creates new tool with NEW admin_token
- Valid admin_token: Creates new tool under EXISTING admin (same token manages multiple tools)
- Invalid admin_token: Returns 401 error

Response (201):
{
  "status": "success",
  "data": {
    "tool_id": "uuid",
    "admin_token": "adm_uuid",
    "submit_token": "sub_uuid"
  }
}

### GET /api/v1/tools
List all tools accessible by this admin token. Requires admin_token.

Headers: Authorization: Bearer adm_...

Response (200):
{
  "status": "success",
  "data": {
    "items": [{"id": "uuid", "name": "tool-name", "created_at": "2024-01-01 00:00:00"}]
  }
}

### DELETE /api/v1/tools?tool_id={id}
Delete a tool and all associated data. Requires admin_token. This action is irreversible.

Headers: Authorization: Bearer adm_...
Query params:
- tool_id: (required) Tool ID to delete

Response (200):
{
  "status": "success",
  "data": {
    "tool_id": "uuid",
    "deleted": true,
    "reports_deleted": 42,
    "tokens_deleted": 3
  }
}

### POST /api/v1/submit
Submit a telemetry report. Requires submit_token.

Headers: Authorization: Bearer sub_...
Request: {"type": "string", "payload": {}, "version": "string"}

Response (201):
{
  "status": "success",
  "data": {"report_id": "uuid"}
}

### GET /api/v1/reports?tool_id={id}
List reports for a specific tool. Requires admin_token.

Headers: Authorization: Bearer adm_...
Query params:
- tool_id: (required) Tool ID to get reports for
- processed: true/false (optional filter)
- limit: 1-100 (default 25)
- cursor: pagination cursor

Response (200):
{
  "status": "success",
  "data": {
    "items": [{"id": "...", "type": "...", "payload": {}, "version": "...", "created_at": "...", "processed": false}],
    "pagination": {"count": 25, "has_more": true, "next_cursor": "..."}
  }
}

### PATCH /api/v1/reports/{id}/processed
Mark a report as processed. Requires admin_token.

Headers: Authorization: Bearer adm_...
Request: {"processed": true}

Response (200):
{
  "status": "success",
  "data": {"report_id": "uuid", "processed": true}
}

### POST /api/v1/tokens?tool_id={id}
Create additional submit token for a specific tool. Requires admin_token.

Headers: Authorization: Bearer adm_...
Query params:
- tool_id: (required) Tool ID to create token for

Response (201):
{
  "status": "success",
  "data": {"token_id": "uuid", "submit_token": "sub_uuid"}
}

### DELETE /api/v1/tokens/{id}
Revoke a submit token. Requires admin_token.

Headers: Authorization: Bearer adm_...

Response (200):
{
  "status": "success",
  "data": {"token_id": "uuid", "revoked": true}
}

## Integration Code Example (Python)

```python
import httpx

TOOLBEACON_URL = "https://toolbeacon.dev"
SUBMIT_TOKEN = "sub_your-token-here"

async def report_tool_call(tool_name: str, success: bool, error: str = None, duration_ms: int = None):
    async with httpx.AsyncClient() as client:
        await client.post(
            f"{TOOLBEACON_URL}/api/v1/submit",
            headers={"Authorization": f"Bearer {SUBMIT_TOKEN}"},
            json={
                "type": "tool_call_success" if success else "tool_call_error",
                "payload": {
                    "tool_name": tool_name,
                    "error_message": error,
                    "duration_ms": duration_ms,
                },
                "version": "1.0.0",
            },
        )
```

## Error Codes

- validation_error (400): Invalid request body
- auth_error (401): Missing/invalid/revoked token
- not_found (404): Resource doesn't exist
- rate_limit_exceeded (429): Too many requests
- internal_error (500): Server error