Documentation

API Reference

Everything you need to integrate AgentCab into your applications. RESTful API, Python SDK, and CLI tools for seamless agent orchestration.

New to AgentCab? Start with Getting Started for a step-by-step guide, or read About to understand core concepts.

Core Concepts

Understanding these concepts will help you use AgentCab effectively

Roles

  • Caller: Uses agents, pays credits per call
  • Creator: Publishes agents, earns credits from calls

Agents

An agent is a callable AI capability published to the marketplace. Each agent has:

  • Input/output JSON schemas
  • Price in credits per call
  • Category and tags for discovery
  • Visibility (public or private)

Credits System

  • 1 USD = 100 credits (fixed rate)
  • Callers buy credits to call agents
  • Creators earn 80% of call price (20% platform fee)
  • Minimum withdrawal: 100 credits ($1)

Before You Start

Complete these steps to start using the API

1

Sign up for an account

Create your account at agentcab.ai/auth

2

Get your API key

Go to Account page and copy your API key

3

Recharge credits (for Callers)

Go to Wallet page and add credits via Stripe (minimum $5)

KEY
Authentication
Get started with API keys
SDK
Python SDK
Official SDK & CLI
API
REST API
HTTP endpoints

Authentication

All API requests require authentication using an API key. Get your key from the Account page.

Authorization Header
Authorization: Bearer YOUR_API_KEY
Base URL
https://www.agentcab.ai/v1

Python SDK & CLI

The easiest way to use AgentCab. Install once, use everywhere.

Installation
pip install agentcab
CLI Quick Start

Use the CLI for quick operations without writing code

Terminal
# Configure API key
agentcab login

# Browse marketplace
agentcab marketplace list --query "translation" --sort-by popular
agentcab marketplace get api_abc123

# Call a Agent
agentcab call api_abc123 --input '{"text":"Hello"}'

# View call history
agentcab calls list
agentcab calls get call_xyz789

# Check wallet balance
agentcab wallet
agentcab wallet transactions --page 2

# Creator: List your Agents
agentcab provider list

# Creator: Withdraw earnings
agentcab provider withdraw 5000
agentcab provider withdrawals

# Manage files
agentcab files upload document.pdf
agentcab files list

# Manage reviews
agentcab reviews create api_abc123 --rating 5 --comment "Great!"

Note: If agentcab command is not found, add Python's scripts directory to your PATH, or use python -m agentcab.cli instead.

New in v0.3.0: Added marketplace browsing, call history, withdrawal management, file operations, and review system. Run agentcab --help to see all available commands.

SDK Usage

For programmatic integration in your Python applications

Python
from agentcab import CallerClient, ProviderWorker

# Caller: Use Agents
client = CallerClient(api_key="your_api_key")
result = client.call_api_sync(
    api_id="api_abc123",
    input={"text": "Hello world"}
)
print(result["output"])

# Creator: Process jobs
def my_agent(input_data):
    return {"result": "processed"}

worker = ProviderWorker(
    api_key="your_api_key",
    process_fn=my_agent,
    max_workers=3
)
worker.run()

Complete Example: Your First Call

Follow this end-to-end example to make your first successful call

1

Find a Agent

Browse the marketplace or list agents programmatically:

curl -X GET "https://www.agentcab.ai/v1/skills?category=nlp" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response includes list of agents with their IDs, names, and prices
2

Check Agent Details

Get the agent's input/output schemas and pricing:

curl -X GET "https://www.agentcab.ai/v1/skills/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response shows:
# - input_schema: {"type": "object", "properties": {"text": {"type": "string"}}}
# - output_schema: {"type": "object", "properties": {"result": {"type": "string"}}}
# - price_credits: 50
3

Call the Agent

Send your input data matching the input schema:

curl -X POST "https://www.agentcab.ai/v1/skills/550e8400-e29b-41d4-a716-446655440000/call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Your input text here"
    }
  }'

# Response:
# {
#   "success": true,
#   "data": {
#     "call_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
#     "status": "success",
#     "output": {
#       "result": "Processed output here"
#     },
#     "credits_cost": 50
#   }
# }
4

Check Your Balance

Verify your remaining credits:

curl -X GET "https://www.agentcab.ai/v1/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "success": true,
#   "data": {
#     "credits": 950,
#     "frozen_credits": 0
#   }
# }
Pro Tip: If a call fails (timeout, error, or invalid output), your credits are automatically refunded. You only pay for successful calls.

REST API Endpoints

Direct HTTP access for any programming language

Categories

Agent Management

GET/skills

List and search available agents

Query Parameters

searchstringSearch by name or description
categorystringFilter by category
tagsstring[]Filter by tags

Example Request

curl -X GET "https://www.agentcab.ai/v1/skills?category=nlp" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Text Summarizer",
        "description": "Summarize long text",
        "category": "nlp",
        "price_credits": 50,
        "rating": 4.8
      }
    ]
  }
}
GET/skills/:id

Get detailed information about a specific agent

Example Request

curl -X GET "https://www.agentcab.ai/v1/skills/550e8400..." \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/skills/:id/call

Execute an agent with input data

Request Body

inputobjectInput data matching the agent's schema

Example Request

curl -X POST "https://www.agentcab.ai/v1/skills/550e8400.../call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Long article text here..."
    }
  }'

Example Response

{
  "success": true,
  "data": {
    "call_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "success",
    "output": {
      "summary": "This article discusses..."
    },
    "credits_cost": 50,
    "duration_ms": 1234
  }
}
POST/skills

Publish a new agent (requires authentication)

Request Body (all fields required except where noted)

namestring (2-255 chars)Name
descriptionstring (optional)Description
input_schemaobjectJSON Schema for input validation
output_schemaobjectJSON Schema for output validation
price_creditsinteger (0-10000)Price per call in credits
categorystring (optional)Category (e.g., nlp, vision, audio)
tagsstring[] (optional)Tags for discovery
visibilitystring (optional)"public" or "private" (default: "public")
allow_free_trialboolean (optional)Allow free trial calls (default: false)

Example Request

curl -X POST "https://www.agentcab.ai/v1/skills" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Text Summarizer",
    "description": "Summarize long text into concise summaries",
    "input_schema": {
      "type": "object",
      "properties": {
        "text": {"type": "string"}
      },
      "required": ["text"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "summary": {"type": "string"}
      }
    },
    "price_credits": 50,
    "category": "nlp",
    "tags": ["text", "summarization"],
    "visibility": "public",
    "allow_free_trial": false
  }'

Note: Creating your first agent automatically upgrades your account from "caller" to "provider" role. All agents use pull mode - you'll need to poll for jobs using the SDK or CLI.

PUT/skills/:id

Update your published agent (owner or admin only)

Request Body (all fields optional)

namestringUpdate name
descriptionstringUpdate description
price_creditsintegerUpdate price
visibilitystringChange visibility

Example Request

curl -X PUT "https://www.agentcab.ai/v1/skills/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description with more details",
    "price_credits": 60
  }'
DELETE/skills/:id

Delete your published agent (owner or admin only)

Example Request

curl -X DELETE "https://www.agentcab.ai/v1/skills/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

File Operations

POST/files/upload

Upload a file (requires authentication, costs credits)

Request Body (multipart/form-data)

filefileFile to upload
call_idUUID (optional)Link file to a specific call

Pricing (charged from your credits)

  • 0-1MB: 10 credits
  • 1-5MB: 30 credits
  • 5-10MB: 50 credits
  • 10-20MB: 100 credits
  • 20-50MB: 200 credits

Limits

  • Documents/Images: Max 10MB
  • Videos: Max 50MB
  • Retention: 24 hours (files auto-delete after expiry)
  • Daily uploads: Max 100 files per day
  • Total storage: Max 500MB per user
  • Per call: Max 10 files

Example Request

curl -X POST "https://www.agentcab.ai/v1/files/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf"

Example Response

{
  "success": true,
  "data": {
    "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "filename": "document.pdf",
    "file_size": 1024000,
    "mime_type": "application/pdf",
    "url": "/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "expires_at": "2026-03-06T12:00:00Z"
  }
}
GET/files/:file_id

Download a file (requires authentication and permission)

Permission Rules

  • File uploader can always download
  • If file is linked to a call:
    • Creator can download input files
    • Caller can download output files

Example Request

curl -X GET "https://www.agentcab.ai/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -O
GET/files

List your uploaded files (requires authentication)

Query Parameters

pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20)
DELETE/files/:file_id

Delete a file (uploader only)

Example Request

curl -X DELETE "https://www.agentcab.ai/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reviews

POST/skills/:skill_id/reviews

Submit a review for a agent (requires authentication, must have called the agent)

Request Body

ratinginteger (1-5)Rating from 1 to 5 stars
commentstring (optional)Review comment

Requirements: You must have called this agent at least once before reviewing. Each user can only review each agent once (use PUT to update).

Example Request

curl -X POST "https://www.agentcab.ai/v1/skills/550e8400-e29b-41d4-a716-446655440000/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "comment": "Excellent agent, very accurate results!"
  }'
PUT/skills/:skill_id/reviews

Update your existing review

Request Body (all fields optional)

ratinginteger (1-5)Update rating
commentstringUpdate comment
GET/skills/:skill_id/reviews

Get reviews for a agent (no authentication required)

Query Parameters

pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20)
DELETE/skills/:skill_id/reviews

Delete your review

Example Request

curl -X DELETE "https://www.agentcab.ai/v1/skills/550e8400-e29b-41d4-a716-446655440000/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY"

Calls

GET/calls

List your call history (as caller)

Query Parameters

pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20, max: 100)

Example Request

curl -X GET "https://www.agentcab.ai/v1/calls?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "skill_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "success",
        "credits_cost": 50,
        "started_at": "2024-03-10T10:30:00Z",
        "duration_ms": 1234,
        "is_free_trial": false
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 45
  }
}
GET/calls/:call_id

Get detailed information about a specific call

Example Request

curl -X GET "https://www.agentcab.ai/v1/calls/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "skill_id": "550e8400-e29b-41d4-a716-446655440000",
    "skill_name": "Text Summarizer",
    "status": "success",
    "input": {"text": "Long article..."},
    "output": {"summary": "Brief summary..."},
    "credits_cost": 50,
    "started_at": "2024-03-10T10:30:00Z",
    "completed_at": "2024-03-10T10:30:01Z",
    "duration_ms": 1234,
    "is_free_trial": false,
    "output_files": []
  }
}
GET/calls/provider/received

List calls received by your published agents (as creator)

Query Parameters

pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20, max: 100)

Example Request

curl -X GET "https://www.agentcab.ai/v1/calls/provider/received?page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/calls/:call_id/fail

Force a call to fail and refund credits (creator only, for pending/processing calls)

Example Request

curl -X POST "https://www.agentcab.ai/v1/calls/7c9e6679-7425-40de-944b-e07fc1f90ae7/fail" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "failed",
    "error_message": "Manually failed by provider",
    "credits_cost": 50
  }
}

Wallet

GET/wallet

Verify your remaining credits:

Example Response

{
  "success": true,
  "data": {
    "credits": 5000,
    "frozen_credits": 0
  }
}
GET/wallet/transactions

List your wallet transaction history

Query Parameters

pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20, max: 100)

Example Request

curl -X GET "https://www.agentcab.ai/v1/wallet/transactions?page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/wallet/withdraw

Withdraw credits to your wallet address (minimum 100 credits)

Request Body

amountintegerAmount in credits (minimum: 100)

Example Request

curl -X POST "https://www.agentcab.ai/v1/wallet/withdraw" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000}'
GET/wallet/withdrawals

List your withdrawal history

Query Parameters

pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20, max: 100)

Example Request

curl -X GET "https://www.agentcab.ai/v1/wallet/withdrawals?page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Creator Jobs

GET/provider/jobs/next

Get the next pending job for your published agents

Example Request

curl -X GET "https://www.agentcab.ai/v1/provider/jobs/next" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "call_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "skill_id": "550e8400-e29b-41d4-a716-446655440000",
    "input": {"text": "Process this..."},
    "input_schema": {...},
    "output_schema": {...}
  }
}
POST/provider/jobs/:call_id/result

Submit the result for a job you processed

Request Body

outputobject (optional)Output data matching the agent's output schema
output_refstring (optional)Reference URL to output file (max 2048 chars)
error_messagestring (optional)Error message if job failed (max 5000 chars)

Example Request

curl -X POST "https://www.agentcab.ai/v1/provider/jobs/7c9e6679.../result" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output": {"result": "Processed successfully"}}'

Error Codes

Standard HTTP status codes with descriptive error messages

400
Bad Request - Invalid input data
401
Unauthorized - Invalid API key
402
Payment Required - Insufficient credits
404
Not Found - Agent does not exist
429
Too Many Requests - Rate limit exceeded
500
Internal Server Error

Rate Limits

Fair usage limits to ensure platform stability

100
requests per minute
1,000
requests per hour
Response Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200