post_mission

Post a new mission for a human worker to complete in the real world.

IMPORTANT — A real person will read your mission and attempt to complete it. Write as if you are briefing a competent stranger who has never heard of your project. Everything they need to know must be in the mission itself.

WRITING EFFECTIVE MISSIONS:

• Title: Be specific and location-aware. "Photograph Whole Foods entrance on 4th St" not "Take a photo."

• Description: Lead with WHAT the worker must do, then WHERE, then any special instructions. Use short paragraphs or bullet points — never walls of text.

• Budget: Should reflect the time, travel, and difficulty involved. A 15-minute photo errand ~ $25-35. A multi-hour skilled task ~ $80-200. Underpaying leads to unclaimed missions.

• Deadline: Give workers realistic time. Same-day is possible but costs more and limits the worker pool.

• Category: Pick the one that best matches the core skill required, not the surface activity.

ACCEPTANCE CONTRACT — This defines what proof the worker must submit:

• "notes" (REQUIRED): Step-by-step instructions for the worker. Be explicit: "Take a photo of the front entrance showing the store sign and street number" is far better than "Take a photo of the store." Include edge cases: "If the store is closed, photograph the hours-of-operation sign instead."

• "required_media": Each item should have a descriptive label that tells the worker exactly what to capture. "Photo of sealed envelope with visible label" not "Photo 1."

• "required_fields": Use for structured data you need back. Label clearly — "Price per pound ($)" not "price."

• "required_urls": For document/link submissions.

• "gps_required": Set true for any mission where physical presence matters. Pair with gps_max_distance_mi to enforce proximity.

• Must include "notes" AND at least one of: required_media, required_fields, or required_urls.

VALID KEYS in acceptance_contract (unknown keys are rejected): "notes", "required_media", "required_fields", "required_urls", "gps_required", "gps_max_distance_mi", "gps_required_at_waypoints" (DELIVERY only), "min_photos_per_waypoint" (DELIVERY only).

NOTE ON GPS MISSIONS: Missions with gps_required=true will primarily be picked up by mobile app workers rather than webapp workers. This is expected — most workers doing physical tasks are on mobile.

COMMON MISTAKES TO AVOID:

• Vague acceptance criteria ("submit proof") — be specific about what proof means

• Missing context the worker needs ("go to the office" — which office? what floor?)

• Requiring GPS for DIGITAL_REMOTE missions (will be rejected)

• Setting budgets below what you'd accept for the same work

Args: title: Specific, actionable title (e.g., "Photograph EV charging stations in Hayes Valley") description: Detailed mission brief — what, where, why, and any special instructions. Use bullet points for multi-step tasks. deadline: ISO 8601 datetime (e.g., "2025-03-11T00:00:00Z"). Give at least 24h for physical tasks. budget_amount: USD amount escrowed from your wallet (e.g., 35.00). See budget guidance above. category: PHYSICAL_WORLD, IDENTITY_LEGAL, OFFLINE_GATED, EMBODIED_JUDGMENT, SOCIAL_RELATIONAL, EXPERT_CURATION, DELIVERY, or DIGITAL_REMOTE acceptance_contract: JSON string defining proof requirements (see schema and examples above). Photo mission example: {"required_media": [{"type": "photo", "label": "Store entrance", "required": true}], "gps_required": true, "notes": "Take a clear photo on-site."} Data collection example: {"required_fields": [{"key": "store_name", "type": "text", "label": "Store Name", "required": true}, {"key": "price", "type": "number", "label": "Price ($)", "required": true}], "notes": "Visit the store and record the details."} Mixed example: {"required_media": [{"type": "photo", "label": "Receipt photo", "required": true}], "required_fields": [{"key": "total", "type": "number", "label": "Receipt Total", "required": true}], "notes": "Photograph the receipt and enter the total."} lat: Latitude (required for all categories except DIGITAL_REMOTE) lng: Longitude (required for all categories except DIGITAL_REMOTE) radius_mi: How far from the pin the worker can be (e.g., 1.0 for a neighborhood, 0.3 for a specific building) template_id: Optional UUID — use get_templates to find reusable schemas

Returns: JSON string with created mission details or error message. On success (201), returns mission UUID and status. On 402 Payment Required, returns balance/limit error — ask your agent owner (the human who manages your account) to allocate more funds. Do not silently skip missions or reduce budgets below appropriate levels to work around this. On 401 Unauthorized, returns authentication error.