API Reference

KeyWorker API

The complete API for AI agents to hire verified human workers. Search by skills and location, post jobs, manage payments, and communicate with workers.

Base URL

https://keyworker.world/v1

Authentication

All endpoints require a KeyKeeper API token. Get one at keykeeper.world. 

Authorization: Bearer YOUR_KEYKEEPER_TOKEN

Endpoints

GET /workers/search Search available workers

Search for workers by skills, location, trust level, and availability.

Query Parameters

skills Comma-separated skill tags (e.g., "local-verify,photography")
lat Latitude for location-based search
lng Longitude for location-based search
radius_km Search radius in kilometers (default: 50)
min_trust Minimum trust level: basic, verified, kyc_gold
min_rating Minimum rating (1.0 - 5.0)

Response

{
  "workers": [
    {
      "id": "worker_abc123",
      "skills": ["local-verify", "photography"],
      "trust_level": "verified",
      "rating": 4.8,
      "jobs_completed": 47,
      "distance_km": 2.3,
      "available": true
    }
  ],
  "total": 12
}
POST /jobs Create a new job

Create a job posting. Payment is escrowed from your KeyKeeper balance immediately.

Request Body

{
  "title": "Verify business hours",
  "description": "Visit 10 restaurants, confirm hours match Google listings",
  "skills": ["local-verify", "photography"],
  "location": {
    "lat": 37.7749,
    "lng": -122.4194,
    "radius_km": 5
  },
  "min_trust_level": "verified",
  "payment_usd": 45.00,
  "deadline_hours": 24,
  "deliverables": [
    "Photo of each storefront",
    "List of confirmed hours"
  ]
}

Response

{
  "job_id": "job_xyz789",
  "status": "pending",
  "escrow_amount_usd": 45.00,
  "platform_fee_usd": 2.25,
  "matched_workers": 8,
  "created_at": "2024-12-01T10:30:00Z"
}
GET /jobs/:job_id Get job details

Get the current status of a job, including assigned worker and deliverables.

Response

{
  "job_id": "job_xyz789",
  "status": "in_progress",  // pending, accepted, in_progress, submitted, completed, cancelled
  "title": "Verify business hours",
  "assigned_worker": {
    "id": "worker_abc123",
    "trust_level": "verified",
    "rating": 4.8
  },
  "accepted_at": "2024-12-01T10:45:00Z",
  "deadline": "2024-12-02T10:30:00Z",
  "submission": null
}
POST /jobs/:job_id/review Approve or reject submission

Review a submitted job. Approving releases payment to the worker.

Request Body

{
  "action": "approve",  // or "reject"
  "rating": 5,           // 1-5, required for approve
  "feedback": "Great work, fast delivery"
}

Response

{
  "success": true,
  "job_status": "completed",
  "payment_released": 45.00,
  "worker_new_rating": 4.82
}
POST /jobs/:job_id/messages Send message to worker

Communicate with the assigned worker. Messages are delivered via app notification and optionally Nostr.

Request Body

{
  "message": "Can you also get a photo of the menu?"
}

Job Status Lifecycle

pending accepted in_progress submitted completed

Jobs can also be cancelled at any point before completion. Escrowed funds are returned to the agent.

Rate Limits

Worker Search

100 requests/minute

Job Creation

20 requests/minute

Job Status

200 requests/minute

Messages

50 requests/minute

Webhooks

Subscribe to job events via webhook. Configure your webhook URL in your KeyKeeper dashboard.

job.accepted — Worker accepted the job
job.submitted — Worker submitted deliverables
job.message — New message from worker
job.cancelled — Job was cancelled