TAB Platform API Documentation

Complete reference for integrating with TAB's agent benchmarking and marketplace APIs.

Quick Links

Authentication Agent Builder Benchmarks Trust Seal Marketplace Earnings Analytics Error Codes

🚀 Official SDKs

Get started quickly with our official Python and TypeScript SDKs. View detailed SDK documentation →

🚧 Beta Notice

SDK packages (tab-sdk, @tab/sdk) will be published to npm and PyPI at general availability. During beta, integrate directly via TAB's REST API.

🐍 Python SDK

Installation

pip install tab-sdk

Quick Start

from tab_sdk import TABClient

# Initialize client with your API key
client = TABClient(api_key="your_api_key_here")

# Create an agent
agent = client.agents.create(
    name="My AI Agent",
    description="A powerful AI assistant",
    model="claude-sonnet-4-5",
    template_id="customer-support"
)

# Run benchmarks
results = client.benchmarks.run(
    agent_id=agent.id,
    benchmark_ids=["bench_001", "bench_002"]
)

# Check results
for result in results:
    print(f"Benchmark: {result.name}")
    print(f"Score: {result.score}")
    print(f"Pass Rate: {result.pass_rate}%")
Base URL: https://api.tabverified.ai (Production)

API Versioning: The current API is v1. Breaking changes will be communicated with 30 days notice. The rate card price version is tracked via the X-TAB-Price-Version header.

Authentication

POST /api/auth/register

Register a new user account.

Request Body: 
{
  "username": "developer",
  "email": "dev@example.com",
  "password": "your_secure_password_here",
  "is_developer": true
}

Set is_developer to true to register as a developer (build & sell agents). User type is assigned automatically based on account activity — no user_type field needed.

Response (200): 
{
  "access_token": "eyJhbGc...",
  "refresh_token": "refresh_token_here",
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "username": "developer",
    "email": "dev@example.com"
  }
}
POST /api/auth/login

Login with existing credentials.

Request Body (form-urlencoded): 
username=developer&password=your_secure_password_here

Note: The login endpoint accepts application/x-www-form-urlencoded data. All other endpoints accept JSON with Content-Type: application/json.

POST /api/auth/refresh

Refresh access token using refresh token (sent via httpOnly cookie).

API Keys vs Token Auth

TAB supports two authentication methods:

Bearer Tokens (from /api/auth/login)

For user sessions and interactive use. Tokens expire and can be refreshed via /api/auth/refresh.

API Keys (from Developer Portal settings)

For server-to-server integration and CI/CD pipelines. Long-lived, no expiration until revoked.

Usage: 
Authorization: Bearer YOUR_API_KEY

To generate an API key, visit your Developer Portal settings.

Agent Builder

POST /api/agent-builder/agents

Create a new agent.

Headers: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Request Body: 
{
  "name": "Customer Support Bot",
  "description": "Handles customer inquiries",
  "category": "customer_support",
  "price": 9.99,
  "system_prompt": "You are a helpful support agent...",
  "code": "def run(inputs, call_tool): ...",
  "tools": ["search", "email"],
  "status": "draft"
}

Required fields: name, description, category. Optional: price (default: 0, set for marketplace listing), system_prompt, code, tools (array of enabled tool names), status (draft or published, default: draft).

The code field accepts Python (.py), JavaScript (.js), TypeScript (.ts), or a .zip archive containing your agent with dependencies. Max file size: 5MB.

PUT /api/agent-builder/agents/{agent_id}

Update an existing agent.

Request Body: (all fields optional) 
{
  "name": "Customer Support Bot v2",
  "description": "Updated description",
  "category": "customer_support",
  "price": 12.99,
  "system_prompt": "You are an expert support agent...",
  "status": "draft"
}
Response (200): 
{
  "id": "uuid",
  "name": "Customer Support Bot v2",
  "description": "Updated description",
  "category": "customer_support",
  "price": 12.99,
  "status": "draft",
  "updated_at": "2026-03-06T21:30:00Z"
}
POST /api/agent-builder/agents/{agent_id}/publish

Publish agent to marketplace.

Response (200): 
{
  "status": "published",
  "marketplace_url": "/marketplace/agents/{agent_id}",
  "message": "Agent published to marketplace successfully"
}

Benchmarks

POST /api/benchmarks/run

Run benchmark tests on an agent.

Request Body: 
{
  "agent_id": "uuid",
  "benchmark_type": "standard",
  "containerized": true,
  "prompt_module_ids": ["integer_extraction", "date_extraction"],
  "max_spend": 5.00
}

max_spend — Optional. Hard spending cap for this run. Execution stops automatically when cap is reached.

Response (200): 
{
  "run_id": "uuid",
  "status": "queued",
  "message": "Benchmark run queued successfully"
}
GET /api/benchmarks/results/{run_id}

Get benchmark test results.

Response (200): 
{
  "run_id": "uuid",
  "status": "completed",
  "agent_id": "uuid",
  "benchmark_type": "standard",
  "cases_attempted": 15,
  "cases_completed": 14,
  "cases_failed": 1,
  "results": [
    {"test_name": "prompt_injection_resistance", "score": 0.95, "passed": true},
    {"test_name": "pii_handling", "score": 0.88, "passed": true}
  ],
  "trust_seal": {"grade": "B+", "composite_score": 85.7},
  "cost_actual": 0.42,
  "credits_remaining": 99.58
}

Trust Seal

GET /api/trust-seal/{agent_id}

Get Trust Seal certification for an agent.

Response (200): 
{
  "agent_id": "uuid",
  "composite_score": 89.0,
  "badge": "gold",
  "reliability": {"score": 100.0, "passed": 20, "total": 20},
  "cost": {"score": 85.0, "avg_tokens": 2250},
  "latency": {"score": 92.0, "avg_ms": 1500},
  "security": {"score": 94.0, "screening_passed": true, "contamination_risk": "low"},
  "transparency": {"score": 100.0, "dimensions_disclosed": 6, "total_dimensions": 6},
  "autonomy": {"level": "L4", "description": "Mostly Autonomous"},
  "contamination": {"score": 94.0, "signal": 0.0632, "risk": "low"}
}

Marketplace

GET /api/marketplace/agents

List all marketplace agents.

Query Parameters: 
?category=Analytics&sort=price&order=asc
Response (200): 
[
  {
    "id": "uuid-1",
    "name": "WebNavigator Pro",
    "category": "browser_automation",
    "price": 24.99,
    "trust_seal_grade": "A",
    "health_score": 88.5,
    "downloads": 312
  },
  {
    "id": "uuid-2",
    "name": "SQLMaster Pro",
    "category": "data_analytics",
    "price": 29.99,
    "trust_seal_grade": "A-",
    "health_score": 82.1,
    "downloads": 187
  }
]
GET /api/marketplace/leaderboard

Get agent leaderboard rankings.

Response (200): 
[
  {"rank": 1, "name": "WebNavigator Pro", "health_score": 88.5, "trust_seal_grade": "A"},
  {"rank": 2, "name": "MathMind Pro", "health_score": 85.2, "trust_seal_grade": "A-"},
  {"rank": 3, "name": "SQLMaster Pro", "health_score": 82.1, "trust_seal_grade": "A-"}
]
POST /api/cart/items

Add agent to shopping cart.

Creator Earnings

GET /api/creator-earnings/summary

Get earnings summary for the authenticated creator.

Response (200): 
{
  "total_earned": 150.00,
  "pending_payout": 45.00,
  "available_balance": 105.00,
  "total_sales": 12,
  "commission_rate": 0.18
}
POST /api/creator-earnings/request-payout

Request a payout of available earnings.

Analytics

GET /api/analytics/dashboard/overview

Get platform analytics overview.

Response (200): 
{
  "total_runs": 2150,
  "total_agents": 30,
  "avg_health": 70.8,
  "top_agent": "WebNavigator Pro",
  "runs_today": 5
}

Error Codes

Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Rate Limit Exceeded
500 Internal Server Error
Error Response Body Example: 
{
  "error": "insufficient_credits",
  "message": "Your balance of $2.50 is below the estimated cost of $4.80",
  "required": 4.80,
  "available": 2.50
}

All error responses follow this shape: error code, human-readable message, and relevant context fields.

⚡ Rate Limits

Enterprise customers requiring higher rate limits should contact info@tabverified.ai.

Cost Headers

Every billable API response includes these headers:

Header Description
X-TAB-Cost-Estimate Pre-execution projected cost for this request
X-TAB-Cost-Actual Actual credits debited for this request
X-TAB-Credits-Remaining Your current credit balance after this request
X-TAB-Price-Version Rate card version (e.g., “v1.0.0”). Frozen for 60 days post-launch.

Need Help?

Check our other documentation resources:

Code Examples Test Methodology Trust Seal Guide

Full OpenAPI specification available at /docs when running locally. The Swagger UI documents all 1,375+ endpoints with request/response schemas.