The complete MCP & REST reference.

Before calling create_task, you MUST have clear answers to ALL of these:

WHAT:       Exactly what needs to be done (specific, not vague)
WHERE:      Full address or GPS coordinates + access instructions
DELIVER:    What the worker submits (photos, text, scans, GPS)
              - How many photos? What angles? What must be visible?
VERIFY:     What does "done correctly" look like? (acceptance criteria)
WHEN:       Deadline (date + time + timezone) — is it realistic?
DURATION:   How long on-site? (minutes)
MILESTONES: Single delivery or multi-step? Set milestone_count to match.

ASK FOLLOW-UPS if anything is unclear. Do not guess.
CRITICAL: 1 USD = 100 Amber. 1 Amber = $0.01. Always show BOTH.

ASK:     "What budget? ($5 = 500 Amber, $50 = 5000 Amber)"
CLARIFY: "50"   ->  "50 Amber ($0.50) or $50 (5000 Amber)?"
         "$20"  ->  "That's 2000 Amber ($20.00). Correct?"
CONFIRM: before fund_task -> "This charges X Amber ($Y). Proceed?"

MINIMUM REALISTIC BUDGETS (1 USD = 100 Amber):
  Quick photo         500+ Amber  ($5+)    ~10 min
  Detailed photos    1000+ Amber ($10+)    ~30 min
  Site verification   500+ Amber  ($5+)    ~15 min
  Inspection         1500+ Amber ($15+)    ~45 min
  Mystery shopping   2000+ Amber ($20+)    ~60 min
  Delivery / errand  1500+ Amber ($15+)    varies

+50% remote, +30% tight deadline (<2h), +25% specialized skill.
Workers get ~90% after fees. If < $8-10/hr, the task WILL expire.

PRICING: ask "Fixed-price or bidding?"
  Bidding -> ask TWO times: (1) how long bidding stays open,
             (2) the task deadline. They are DIFFERENT.

1. get_capabilities  ->  verify the target city has workers
2. get_wallet        ->  verify sufficient Amber balance
3. dry_run           ->  check quality score
     < 0.5    STOP. Instructions are too vague.
     0.5-0.7  Add more detail.
     0.7+     Good to proceed.
4. Fix ALL warnings from dry_run
5. Show final spec to user, get explicit "yes, create it"
6. create_task  ->  fund_task

When mcp_status = "input_required" (worker submitted):
  GOOD work    ->  approve_submission  (confirm with user first)
  NEEDS FIXES  ->  reject_submission with specific feedback
                   (the SAME worker revises the SAME task)
  FRAUD        ->  file_dispute

NEVER create a new task for revisions (wastes money, duplicates).
NEVER approve the whole task when only 1 milestone is done.
NEVER set milestone_count=3 when describing 2 milestones.
NEVER ignore submissions (auto-approves in 24 hours at 0.8).

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "aethra.create_task",
    "arguments": { "title": "Photograph storefront at 123 Main St", "budget_amber": 20 }
  }
}

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      { "type": "text", "text": "{\"task_id\": \"550e8400-...\", \"status\": \"draft\"}" }
    ]
  }
}

Developer Account (you)
├── Amber Balance: 15,000 Amber ($150.00)
├── Agent A (sk_live_xxxxx)   <- storefront verification feature
├── Agent B (sk_live_yyyyy)   <- delivery confirmation feature
└── Agent C (sk_live_zzzzz)   <- testing / sandbox

POST /api/v1/auth/register/developer
{
  "email": "you@company.com",
  "password": "YourSecurePassword123",   // min 12 chars
  "display_name": "Your Name",
  "org_name": "Your Company"
}
// -> { access_token (60 min), refresh_token (30 days) }

POST /api/v1/auth/developers/agents
Authorization: Bearer <developer-jwt>
{ "display_name": "My First Agent" }

// Response (api_key shown EXACTLY once — store it now):
{ "agent_id": "d4e5f6...", "api_key": "sk_live_AbCdEf..." }

POST /api/v1/amber/topup/create-intent
{ "usd_cents": 2000 }          // $20.00 = 2,000 Amber, minimum $1.00
// -> returns a Stripe client_secret; complete with Stripe.js

{
  "method": "tools/call",
  "params": {
    "name": "aethra.dry_run",         // free, no side effects
    "arguments": {
      "title": "Photograph the exterior of Starbucks at 123 Main St",
      "task_type": "photography",
      "location": { "latitude": 37.7749, "longitude": -122.4194 },
      "budget_amber": 15
    }
  }
}

// 1. create — task starts in "draft", invisible to workers
client.call("aethra.create_task", { ...spec })
// -> { task_id: "550e8400...", status: "draft", spec_quality_score: 0.87 }

// 2. fund — commits Amber to escrow and publishes to nearby workers
client.call("aethra.fund_task", { task_id })
// -> { status: "funded", escrow_id: "..." }

// worker submitted — review, then release payment
const sub = client.call("aethra.get_submission", { task_id })
// -> { photo_count: 4, text_content: "...", verification: { passed: true } }

client.call("aethra.approve_submission", {
  task_id,
  quality_rating: 0.9          // 0.0 to 1.0
})

Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv...

POST /api/v1/auth/login
{ "email": "you@company.com", "password": "..." }
// -> { access_token (60 min), refresh_token (30 days), role: "developer" }

POST /api/v1/auth/refresh
{ "refresh_token": "eyJ..." }

POST /api/v1/auth/revoke      // immediate, persisted
{ "refresh_token": "eyJ..." }

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your-agent-uuid>
&client_secret=<your-raw-api-key>
&scope=tasks.read tasks.create payments.fund

// -> { access_token, token_type: "bearer", expires_in: 3600, scope: "..." }

POST /api/v1/auth/api-keys
Authorization: Bearer <developer-jwt>
{
  "name": "Read-only monitoring key",
  "scopes": ["tasks.read", "payments.read", "profile.read"],
  "expires_in_days": 90
}

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "draft",
  "spec_quality_score": 0.87,
  "spec_quality_label": "good",
  "warnings": ["Consider adding acceptance_criteria for better guidance"],
  "estimated_match_minutes": 15,
  "budget_amber": "20.00",
  "priority": "medium",
  "deadline_at": "2026-03-06T14:30:00Z",
  "created_at": "2026-03-05T14:30:00Z"
}

1 USD = 100 AMBER = 100,000,000 micro-AMBER

// get_wallet  ->  balance_usd / pending_usd are USD-equivalent values
{ "balance_usd": "87.50", "pending_usd": "20.00", "currency": "USD" }
// 8,750 Amber spendable, 2,000 Amber in escrow

// set spending caps (developer JWT required)
PUT /api/v1/amber/spending-caps
{ "daily_agent_spend_cap_amber": 5000,   // 5,000 Amber = $50/day
  "per_task_spend_cap_amber": 500 }       // 500 Amber = $5 per task

// REST balance check
GET /api/v1/amber/balance
{ "amber": 8750, "micro_amber": 8750000000, "usd_equivalent": "87.50" }

import httpx, json

class RentablyClient:
    def __init__(self, api_key, base_url="https://api.rentably.ai"):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }
        self._id = 0

    def call(self, tool_name, arguments):
        self._id += 1
        payload = {
            "jsonrpc": "2.0", "id": self._id,
            "method": "tools/call",
            "params": {"name": tool_name, "arguments": arguments},
        }
        r = httpx.post(f"{self.base_url}/mcp", json=payload, headers=self.headers)
        r.raise_for_status()
        data = r.json()
        if "error" in data:
            raise Exception(f"MCP {data['error']['code']}: {data['error']['message']}")
        return json.loads(data["result"]["content"][0]["text"])

client = RentablyClient(api_key="sk_live_...")
wallet = client.call("aethra.get_wallet", {})
print(f"Balance: {wallet['balance_usd']} USD")

task = client.call("aethra.create_task", {
    "title": "Photograph the exterior of Chase Bank at 450 Main St, SF",
    "task_type": "photography",
    "location": {"latitude": 37.7749, "longitude": -122.4194,
                 "radius_meters": 50, "address": "450 Main St, SF"},
    "budget_amber": 20,
    "estimated_duration_minutes": 20,
    "deliverables": [
        {"type": "photo", "description": "Full storefront", "quantity": 1, "required": True},
        {"type": "photo", "description": "Branch sign close-up", "quantity": 1, "required": True},
    ],
    "acceptance_criteria": [
        {"criterion": "Photos include GPS", "verification_method": "auto_gps"},
        {"criterion": "At least 2 photos", "verification_method": "auto_photo_count"},
    ],
    "photo_requirements": {"min_count": 2, "must_include_gps_exif": True},
})
print(f"Task {task['task_id']} — quality {task['spec_quality_score']:.0%}")

import httpx, json

def stream_task_events(api_key):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "text/event-stream",
        # "Last-Event-ID": last_id,   # replay missed events on reconnect
    }
    with httpx.stream("GET", "https://api.rentably.ai/mcp", headers=headers) as r:
        for line in r.iter_lines():
            if line.startswith("data:"):
                event = json.loads(line[5:].strip())
                print(f"Task {event['task_id']}: {event['mcp_status']}")

# event types: task_state_change, submission_received, task_completed,
#              task_cancelled, task_disputed, error
# One concurrent SSE connection per API key (a second returns HTTP 503).

import httpx, secrets

webhook_secret = secrets.token_hex(32)   # store this — min 16 chars
httpx.post(
    "https://api.rentably.ai/api/v1/agent/webhooks",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "url": "https://yourapp.com/webhooks/aethra",   # https only, no localhost
        "event_types": ["task.completed", "review.submitted", "task.disputed"],
        "secret": webhook_secret,
    },
)

# 9 event types: task.created  task.updated  task.completed  task.cancelled
#   task.disputed  task.funded  review.submitted
#   payment.withdrawal_completed  payment.withdrawal_failed

import hmac, hashlib, time

def verify_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
    # reject stale events (>5 min) to prevent replay
    event_time = int(request.headers.get("X-Rentably-Timestamp", "0"))
    if abs(time.time() - event_time) > 300:
        return False
    sig = signature_header.removeprefix("sha256=")
    expected = hmac.new(secret.encode(), payload_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

# Headers on every delivery:
#   X-Rentably-Signature: sha256=<hexdigest>
#   X-Rentably-Event-Type: task.completed
#   X-Rentably-Timestamp: 1741200000

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1741200060

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: budget_amber must be at least 1",
    "data": { "field": "budget_amber", "reason": "below_minimum" }
  }
}