Bounties API

Bounties are open tasks that any qualified, verified worker can claim. Unlike standard tasks (which can be directed to specific workers), bounties are posted publicly and the first eligible worker to accept gets the assignment.

Base path: /v1/bounties

Bounties vs. Tasks

Feature	Task	Bounty
Assignment	Can target specific workers	First-come, first-served
Platform fee	16%	20%
Worker payout	84% of budget	80% of budget
Visibility	Can be private until assigned	Always visible to qualified workers
Use case	You know which worker you want	You want the fastest available worker

Bounties are ideal when location matters more than the specific worker -- for example, "someone in downtown Chicago needs to photograph this address."

---

Create Bounty

POST /v1/bounties

Create an open bounty. The request body is identical to Create Task, but the task is created as a bounty with the higher take rate (20%).

Request Body

Field	Type	Required	Description
title	string	Yes	Bounty title (1-200 characters)
description	string	Yes	Detailed description (1-2000 characters)
instructions	string	No	Private instructions for the worker (max 5000 characters)
category	string	Yes	Task category
required_skills	string[]	No	Required worker skills
location	object	Yes	Task location with city, state, latitude, longitude
budget_cents	integer	Yes	Total budget in cents (minimum 500)
priority	string	No	"normal" or "urgent" (default: "normal")
deadline	string	No	ISO 8601 deadline
proof_types	string[]	No	Required proof types (default: ["photo"])
metadata	object	No	Arbitrary key-value pairs

Example Request

curl -X POST https://api.workfunder.com/v1/bounties \
  -H "Authorization: Bearer wf_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mystery shop at Coffee Corner on 5th Ave",
    "description": "Visit Coffee Corner, order a medium latte, and evaluate the customer experience. Note wait time, staff friendliness, drink quality, and store cleanliness.",
    "instructions": "Do not reveal that you are conducting a mystery shop. Act as a normal customer. Take a photo of your receipt and a photo of the interior.",
    "category": "mystery_shopping",
    "required_skills": ["mystery_shopping"],
    "location": {
      "address": "456 5th Ave",
      "city": "New York",
      "state": "NY",
      "latitude": 40.7549,
      "longitude": -73.9840
    },
    "budget_cents": 7500,
    "priority": "normal",
    "proof_types": ["photo"],
    "metadata": {
      "chain": "Coffee Corner",
      "store_id": "CC-NYC-042"
    }
  }'

Example Response

{
  "id": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5",
  "developer_id": "d1e2f3a4b5c6d1e2f3a4b5c6d1e2f3a4",
  "title": "Mystery shop at Coffee Corner on 5th Ave",
  "description": "Visit Coffee Corner, order a medium latte, and evaluate the customer experience. Note wait time, staff friendliness, drink quality, and store cleanliness.",
  "category": "mystery_shopping",
  "required_skills": ["mystery_shopping"],
  "location_address": "456 5th Ave",
  "location_city": "New York",
  "location_state": "NY",
  "location_latitude": 40.7549,
  "location_longitude": -73.9840,
  "budget_cents": 7500,
  "platform_fee_cents": 1500,
  "worker_payout_cents": 6000,
  "priority": "normal",
  "status": "pending",
  "environment": "live",
  "worker_id": null,
  "max_proof_attempts": 3,
  "proof_types": ["photo"],
  "metadata": {
    "chain": "Coffee Corner",
    "store_id": "CC-NYC-042"
  },
  "created_at": "2026-02-24T12:00:00.000Z",
  "updated_at": "2026-02-24T12:00:00.000Z"
}

Note the pricing breakdown for a $75.00 bounty:

• Platform fee: $15.00 (20%)
• Worker payout: $60.00 (80%)

---

List Bounties

GET /v1/bounties

Retrieve a paginated list of your bounties.

Query Parameters

Parameter	Type	Default	Description
status	string	--	Filter by status
limit	integer	20	Results per page (max 100)
offset	integer	0	Number of results to skip

Example Request

curl "https://api.workfunder.com/v1/bounties?status=posted&limit=20" \
  -H "Authorization: Bearer wf_live_your_key"

Example Response

{
  "data": [
    {
      "id": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5",
      "title": "Mystery shop at Coffee Corner on 5th Ave",
      "status": "posted",
      "category": "mystery_shopping",
      "budget_cents": 7500,
      "location_city": "New York",
      "location_state": "NY",
      "worker_id": null,
      "created_at": "2026-02-24T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

---

Get Bounty

GET /v1/bounties/:id

Retrieve a single bounty by ID.

Path Parameters

Parameter	Type	Description
id	string	The bounty ID

Example Request

curl https://api.workfunder.com/v1/bounties/b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5 \
  -H "Authorization: Bearer wf_live_your_key"

Example Response

Returns the full bounty object (same format as the Create Bounty response, with current status).

Errors

Code	Status	Description
TASK_NOT_FOUND	404	Bounty not found or does not belong to your account

---

Cancel Bounty

DELETE /v1/bounties/:id

Cancel a bounty. Same cancellation rules as Cancel Task apply.

Example Request

curl -X DELETE https://api.workfunder.com/v1/bounties/b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5 \
  -H "Authorization: Bearer wf_live_your_key"

Example Response

{
  "id": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5",
  "status": "cancelled",
  "cancelled_at": "2026-02-24T15:00:00.000Z"
}

Errors

Code	Status	Description
TASK_NOT_FOUND	404	Bounty not found
INVALID_TASK_STATE	409	Bounty cannot be cancelled in its current state