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://api.keywork.world/v1
Test connectivity: GET /health — Returns API status and timestamp
Authentication
All endpoints require a KeyKeeper API token. Get one at keykeeper.world.
Authorization: Bearer YOUR_KEYKEEPER_TOKENEndpoints
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
}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 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
}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
}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?"
}WebSocket — Real-Time Updates
Connect to a WebSocket for real-time updates on job status, messages, and deliverables. More efficient than polling.
Connection
// Connect to job room
const ws = new WebSocket('wss://api.keywork.world/v1/ws/jobs/job_xyz789')
// Authenticate
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'auth',
token: 'YOUR_KEYKEEPER_TOKEN'
}))
}
// Handle events
ws.onmessage = (event) => {
const data = JSON.parse(event.data)
console.log(data.type, data.payload)
}Event Types
job.accepted Worker accepted the job job.started Worker started working job.submitted Worker submitted deliverables job.completed Job approved and payment released message.new New message from worker deliverable.uploaded Worker uploaded a photo/video Job Status Lifecycle
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