runnersOpenAPI 3.1
Back home
API v1 · Pilot

Give your agent
a way outside.

Create location-specific jobs, follow every dispatch event, and receive verified real-world output. The v1 pilot serves Indiranagar and Nagarbhavi, Bengaluru.

Quickstart

Create a job

Send one authenticated request. Use an idempotency key so retries never create duplicate jobs.

curl -X POST https://YOUR_DOMAIN/api/v1/jobs \
  -H "x-api-key: runners_test_indiranagar" \
  -H "idempotency-key: instinct-demo-001" \
  -H "content-type: application/json" \
  -d '{
    "title": "Pick up a signed document",
    "task": "Collect the envelope from reception and deliver it to the address. Do not open it.",
    "owner": { "name": "Instinct", "contact": "agent:instinct" },
    "pricing": { "mode": "runner_quote", "min_amount": 50, "max_amount": 500, "auto_approve_up_to": 100, "currency": "INR" },
    "location": { "address": "Nagarbhavi, Bengaluru", "latitude": 12.9591, "longitude": 77.5128, "service_radius_meters": 5000 },
    "route": {
      "from": { "address": "Pickup location, Nagarbhavi" },
      "to": { "address": "Sallapuradamma Temple, Nagarbhavi", "latitude": 12.9591, "longitude": 77.5128 }
    },
    "payment": { "mode": "simulated" },
    "runner": {
      "mode": "pilot_test",
      "qualification": "none"
    },
    "outreach": { "channels": ["call"] },
    "follow_up_after_seconds": 300,
    "proof_requirements": [],
    "webhook": { "url": "https://agent.example.com/runners/events", "secret": "whsec_your_secret" }
  }'
For local and pilot testing, use runners_test_indiranagar. Replace it with a managed key before production.
End to end

Test it yourself

  1. Set runner.mode to pilot_test. Runners ranks up to three nearby active profiles.
  2. POST the job. Runners calls candidates one at a time, explains the task, records each ₹50–₹500 quote, and ends each quote call.
  3. After quote collection, Runners calls the lowest-priced candidate back and negotiates from the opening offer to the configured ceiling. Assignment happens only after explicit acceptance.
  4. After acceptance, simulated funds are held, the runner gets the summary link, and a five-minute follow-up is scheduled.
  5. The runner can upload proof and report completion. Requester approval settles the simulated 98% payout and 2% fee.

For the smallest Instinct prompt, send it to the agent instructions page.

Endpoints

Small, predictable surface

POST/api/v1/jobsCreate, match, and dispatch a job
GET/api/v1/jobsList recent jobs; filter with ?status=
GET/api/v1/jobs/{job_id}Get current job state
GET/api/v1/jobs/{job_id}/eventsRead the ordered event timeline
POST/api/v1/jobs/{job_id}/quoteApprove or reject a runner quote
POST/api/v1/jobs/{job_id}/confirmationConfirm completion and settle test payout
POST/api/v1/runnersPublic runner-interest form

Agent endpoints accept x-api-key or Authorization: Bearer …. Every response is JSON. Errors use { "error": { "code", "message" } }.

Lifecycle

Job states

finding_candidateRanking nearby eligible runners
contacting_candidatesCalling shortlisted runners one at a time for quotes
negotiating_priceCalling the lowest-priced runner back to negotiate
assignedA runner accepted the negotiated job
runner_en_routeRunner is travelling to the task
runner_at_workPhysical work is in progress
proof_reviewEvidence is being checked
quote_receivedRunner proposed a price
awaiting_quote_approvalRequester approval is needed
awaiting_requester_confirmationRunner says done; requester must confirm
completedVerified result is ready
paidSimulated payout and platform fee are settled
needs_attentionHuman operator or agent input is required
cancelledJob was cancelled
Realtime

Webhooks

Runners posts an event immediately whenever the job changes. Payloads include an event id, event type, timestamp, job id, status and a human-readable message. When a webhook secret is supplied, verify x-runners-signature as an HMAC-SHA256 of the raw body.

{
  "id": "evt_01…",
  "type": "runner.assigned",
  "created_at": "2026-09-10T12:30:04.000Z",
  "data": { "job_id": "job_01…", "status": "assigned", "message": "Arjun accepted and is 1.4 km away." }
}

Production heartbeat schedule: immediate events, then unchanged-state heartbeats at 10s, 30s, 60s, and every 60s until a terminal state. Agents should still use the GET endpoint for recovery after downtime.

Service area

Bengaluru pilot

The test currently covers Indiranagar and Nagarbhavi. INR is the only currency; runner-decided pilot quotes range from ₹50 to ₹500. Coordinates are strongly preferred, and address-only requests must name one of the active pilot areas.