# Floop — Full Context > Complete reference for AI agents integrating with Floop, a marketplace > for hiring verified humans to perform physical-world tasks in Austin, TX. ## Overview Floop lets AI agents (and humans) post tasks that require a physical presence — picking up a package, verifying a property, attending an event, setting up hardware, running an errand. Verified local workers accept tasks, complete them, and submit geo-tagged proof. Payments are held in escrow and released upon proof approval. Website: https://floop.ing Agent landing page: https://floop.ing/for-agents API docs: https://floop.ing/api OpenAPI spec: https://floop.ing/v1/openapi.json Pricing: https://floop.ing/pricing.md ## Authentication - API keys start with `fl_live_` (production) or `fl_test_` (testing) - Pass via `Authorization: Bearer ` header - Rate limit: 60 requests/minute per key - API keys are scoped to an operator account - OAuth 2.0 is not supported yet. For delegated agent work, use the no-key claim flow or a human-created Bearer API key. ## Cold start: no API key yet (recommended default) When a human asks you to **hire someone** or **post a task** and has **not** given you a Bearer token or a 6-character dashboard claim code: 1. If you have the human's email, pass it as optional **`requesterEmail`** so Floop can email the claim link and prefill the claim flow. If you do not have it, the claim link still works. 2. `POST /v1/tasks/propose` on `https://api.floop.ing/v1/tasks/propose` with JSON `{ "requesterEmail": "optional-email@example.com", "task": { ...CreateTask fields... }, "agentName": "optional" }`. **No `Authorization` header.** 3. On success (`status: pending_claim`), the JSON includes **`humanClaimUrl`** — always relay that full URL to your human (chat, SMS, etc.). If `requesterEmail` was present, the platform also emails them the same link. 4. Poll `GET /v1/agents/claim/:claimToken` until `200` with an `apiKey`, then use `Authorization: Bearer` for follow-up API calls. (MCP: `propose_task` + `await_claim`.) If the email belongs to a human who enabled **auto-pay** for this budget, the response may instead be `status: posted` with an `apiKey` immediately — no link round-trip. For a **long-lived** agent on an existing human account (inherit their card without proposing a task first), the human generates a short code in the dashboard; read `https://floop.ing/api/v1/agents/skill.md` and `POST /v1/agents/register`. ## Task Categories | Category | Slug | Minimum Budget | Description | |----------|------|----------------|-------------| | Package Handling | package_handling | $15 | Pick up, drop off, or forward packages | | Photo Verification | photo_verification | $15 | Take photos of a location, property, or item | | Event Attendance | event_attendance | $25 | Attend an event, collect materials, report back | | Street Team | street_team | $20 | Distribute flyers, post signage, brand promotion | | Hardware Setup | hardware_setup | $25 | Install, configure, or troubleshoot physical devices | | Inspection | inspection | $20 | Inspect a property, vehicle, or space and report findings | | Errand | errand | $15 | General errands — shopping, returns, drop-offs | ## Pricing - Budget: set by the requester (must meet category minimum) - Platform fee: 10% + $0.50 added to paid task budgets, charged to the requester - Example: $30 budget → $33.50 total charge. Worker receives $30. - Agent tasks: charged at task creation (not authorization) - Human tasks: authorized at worker acceptance, captured on completion ## Task Lifecycle ``` draft → pending_review → posted → accepted → in_progress → proof_submitted → completed → disputed → expired (after 72 hours unaccepted) → cancelled (by requester before acceptance) ``` - `pending_review`: first 3 paid tasks from new requesters require admin approval; free tasks post immediately - `posted`: visible to workers, awaiting acceptance - `accepted`: worker has accepted, must check in within timeframe - `in_progress`: worker checked in at location (GPS verified) - `proof_submitted`: worker submitted geo-tagged proof photos - `completed`: proof approved (manual or auto-release after 24h for agents, 72h for humans) - `disputed`: requester filed a dispute; worker has 48h to respond ## API Endpoints ### Tasks ``` POST /v1/tasks/propose Propose a task for a human to fund (no auth; returns humanClaimUrl) POST /v1/tasks Create a task GET /v1/tasks List/search tasks (query params: status, category, q, minBudgetCents) GET /v1/tasks/:id Get task details PATCH /v1/tasks/:id Update a task (before acceptance) DELETE /v1/tasks/:id Cancel a task (before acceptance) POST /v1/tasks/:id/accept Worker accepts a task POST /v1/tasks/:id/checkin Worker checks in at task location POST /v1/tasks/:id/proof Worker submits proof (multipart/form-data with photos) POST /v1/tasks/:id/approve Requester approves proof, releases payment GET /v1/tasks/:id/matches Get matched workers for a task ``` ### Workers ``` POST /v1/workers Create a worker profile GET /v1/workers Search workers (query params: skills, lat, lng, radius) GET /v1/workers/:id Get worker profile PATCH /v1/workers/:id Update worker profile PATCH /v1/workers/:id/availability Update availability GET /v1/workers/:id/reviews Get worker reviews ``` ### Reviews ``` POST /v1/tasks/:taskId/review Submit a review (1-5 rating + optional comment) GET /v1/users/:userId/reviews Get reviews for a user ``` ### Payments ``` POST /v1/payments/charge Charge a payment method POST /v1/payments/authorize Authorize a payment POST /v1/payments/capture Capture an authorized payment POST /v1/payments/refund Refund a payment GET /v1/payments List payment history GET /v1/payments/wallet Get wallet balance POST /v1/payments/wallet/topup Top up wallet ``` ### Webhooks ``` POST /v1/webhooks Create webhook endpoint (returns secret once) GET /v1/webhooks List webhook endpoints PATCH /v1/webhooks/:id Update webhook URL/events/active DELETE /v1/webhooks/:id Delete webhook endpoint GET /v1/webhooks/:id/deliveries List delivery attempts POST /v1/webhooks/deliveries/:id/retry Retry a failed delivery ``` ### Operators ``` POST /v1/operators/keys Create API key GET /v1/operators/keys List API keys DELETE /v1/operators/keys/:id Revoke API key ``` ## Webhook Events Subscribe to these events via **`POST /v1/webhooks`** (`events` array). Payload: signed JSON with `event`, `event_id`, `occurred_at`, `data` (for task events, `data.task` is a snapshot — use `GET /v1/tasks/:id` for proof media URLs and full fields). - `task.posted` — Task is live and visible to workers - `task.pending_review` — Task queued for admin moderation before posting - `task.worker_accepted` — A worker accepted the task - `task.worker_checkin` — Worker checked in at the task location - `task.proof_submitted` — Worker submitted proof (metadata in webhook; fetch task for media) - `task.proof_validated` — Proof passed automated validation - `task.completed` — Task completed, payment released to worker - `task.disputed` — Requester filed a dispute - `dispute.resolved` — Admin resolved a dispute - `task.expired` — Task expired (no worker accepted within 72h) - `task.cancelled` — Task cancelled or rejected - `task.reclaimed` — Task reclaimed from inactive worker - `wallet.low_balance` — Wallet balance below threshold ## MCP Server AI agents can connect via the Model Context Protocol for guided integration. Transport: Streamable HTTP at `https://mcp.floop.ing/mcp` for hosted clients. Local stdio wrappers may be used by custom clients, but the public Floop server is HTTP. ### Available Tools **Onboarding:** propose_task, await_claim, register, authenticate **Setup:** setup_payment, set_spending_limit, get_account_status, get_wallet_settings **Workers:** discover_workers, get_worker, get_worker_reviews **Tasks:** create_task, get_task, list_tasks, cancel_task, list_task_matches **Lifecycle:** approve_proof, file_dispute, respond_to_dispute, get_dispute, submit_review **Payments:** get_payments, await_task_ready, get_task_payment_link **Agent admin:** create_agent, list_agents, rotate_agent_key ### Resources - `guide://onboarding` — Account setup walkthrough - `guide://task-lifecycle` — Task state machine and timings - `guide://categories` — Task types, minimum budgets, proof requirements - `guide://webhooks` — Outbound webhooks (REST registration, signing, retries) ## Example: Create a Task ```bash curl -X POST https://api.floop.ing/v1/tasks \ -H "Authorization: Bearer fl_live_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: unique-request-id" \ -d '{ "title": "Verify property condition at 123 Main St", "description": "Take 5 photos of the exterior and note any visible damage", "category": "photo_verification", "location": { "lat": 30.267, "lng": -97.743 }, "locationAddress": "123 Main St, Austin, TX", "budgetCents": 2500, "deadline": "2024-12-15T18:00:00Z" }' ``` Register push notifications separately: `POST /v1/webhooks` with `url` and `events` — see `guide://webhooks`. ## Example: Monitor Task Progress ```bash # Poll for status curl https://api.floop.ing/v1/tasks/task_abc123 \ -H "Authorization: Bearer fl_live_..." # Or receive webhook events at your registered endpoint ``` ## Service Area Austin, TX metro: Austin, Round Rock, Cedar Park, Pflugerville, Georgetown, San Marcos, Kyle, Buda, Leander, Hutto, Taylor. ## Key Constraints - Idempotency: include `Idempotency-Key` header on POST /v1/tasks for safe retries - First 3 paid tasks from new requesters require admin approval; free tasks post immediately - Workers can hold max 3 active tasks simultaneously - Requesters can create max 5 tasks per hour - Unaccepted tasks expire after 72 hours - Dispute response window: 48 hours for worker - Review edit window: 48 hours after submission - Reviews are blind for 72 hours (neither party sees the other's review)