Public API · v1

Your software can prepare a request for real people.

NearbyCrew API v1 lets your backend describe a task, how many people are needed, and who they should be. NearbyCrew returns a request, a quote when ready, and a request ID you can check later. The owner still approves and funds it before anyone is deployed.

See examples Make the first call

Free API v1 · 10 mission create calls per day per public workspace · the mission itself is funded separately.

Ground truth

What this API actually does

This page is written to stay inside what NearbyCrew API v1 can support today. Clear, useful, and factual.

It creates a request tied to a public workspace.

Your key belongs to a public NearbyCrew workspace. The request is created under that workspace.

It can include crew guidance.

You can send request by itself, or also include people and who to define the crew requirement more clearly.

It returns request and quote information.

When the request is ready, the API can return a request ID, status, quote information, and usage details.

It keeps a human approval step.

Creating the request does not automatically spend money or send people to work. The owner still reviews and funds it.

It lets you check status later.

Save the request ID and read the status endpoint to see whether the request is ready, funded, active, in review, or complete.

It is free at the API layer in v1.

The API itself is free in v1. The mission is separately funded if the owner approves it.

Examples

Where this fits inside a product

These examples are here to teach placement and use. Each one shows a realistic surface in a product, where a NearbyCrew action makes sense, and what that action is really doing.

Mobile bug report flow

Best placement: on the issue detail page, after the team already knows a human needs to try the problem on a real device.

Reproduce this on real phones

A bug tracker or QA tool could place NearbyCrew beside the issue once the team realizes the bug needs a few real people with the right device, region, or operating system.

BackCreate PostHelp

↑

100%

Upload failed. Please try again.

Android upload issue Pixel 8 · Android 14 · App 2.3.1

NearbyCrew action Verify with real Android users

The product can trigger a NearbyCrew request for a few Android users in the right region to try the same upload flow and report what happens.

What the request says

Target crew: 3 Android users in the US.
Task: Try the upload flow and report what happens.

Why it belongs here

This action is useful right where the team is already diagnosing the bug. They should not need to leave the issue to start the request.

Desktop landing page tool

Best placement: right after publish, or beside page analytics when the team wants fresh first impression feedback.

Ask first time visitors what they think this page does

A page builder, growth tool, or analytics product could offer NearbyCrew after a page goes live. It helps turn a vague question like “is this page clear?” into a real request for outside feedback.

focusflow.app

FocusFlow

Less distraction. More progress.

A calmer productivity tool for people who want to focus without the clutter.

12,480Page views

1,892Visitors

6.4%Signup rate

Good morning Deep work Read Exercise

Test with first time visitors

NearbyCrew action Test with first time visitors

The product can create a request for a few first time visitors to open the page, explain what they think it does, and try the signup flow.

What the request says

Target crew: 5 first time visitors.
Task: Open the page, say what you think it does, and try signing up.

Why it belongs here

The most natural moment is after publish, or next to conversion analytics, because that is when the owner wants a human explanation for what the numbers mean.

Game build dashboard

Best placement: on the build page, right where a producer or designer is deciding whether a build needs outside testing.

Run a playtest without leaving the build

A game studio tool could put NearbyCrew directly on the build page so the team can request players who match the genre or platform profile without creating a separate workflow outside the product.

Ashen Depths

Build 0.4.7

Ready for testing

▶

Run a playtest

Windows Steam Deck Roguelike

NearbyCrew action Run a playtest

The product can create a request for players who fit the target audience and ask them to play a defined slice of the game.

What the request says

Target crew: 10 roguelike players on PC.
Task: Play the first 20 minutes and report where you get confused or quit.

Why it belongs here

The build page is where the team already thinks about readiness, bugs, balance, and player friction. The action should live there.

Tablet or operations dashboard

Best placement: next to listing quality warnings, address mismatches, or storefront uncertainty.

Confirm what is happening in the real world

A listing product, map tool, or local operations platform could use NearbyCrew when the system cannot fully trust a listing and needs a current human check.

The Daily Grind

Coffee shop · Austin, TX

Hours Mon to Fri 6:30 AM to 6:00 PM Sat 7:00 AM to 6:00 PM Sun 7:00 AM to 4:00 PM

Address mismatch detected

Check in person

NearbyCrew action Check in person

The product can create a request for a couple of people near the location to confirm whether the storefront is open and send a current exterior photo.

What the request says

Target crew: 2 people near the location.
Task: Confirm whether the storefront is open and send a current exterior photo.

Why it belongs here

This action makes sense right where the system signals uncertainty. The owner sees the warning and can decide whether it is worth requesting a real world check.

Setup

Set up the project once

An API key belongs to a public NearbyCrew workspace. The workspace gives the key an owner and a project context.

Step 1

Create a Citizen

Your NearbyCrew identity owns the workspace and API access.

Step 2

Create a Mission workspace

Open Mission, choose New, and add the project that should own the API key.

Step 3

Finish the public page

Add the logo, cover, title, description, and a real product link.

Step 4

Publish and create a key

Open Publish, then Developer API, and create the key. The full secret is shown once.

Start here

Create Citizen ↗

Free account. Required for workspace ownership.

Current limits

Free API v1 limits

The quota belongs to the workspace, not the key. Rotating keys does not reset usage.

Mission creates 10/day per public workspace · UTC reset

Burst 3/min new mission requests

Status reads 60/min do not use create quota

Keys 3 active keys per workspace

API usage is free in v1. The human mission itself is not free. Creating a request produces a reviewable quote. No people are deployed until the owner approves and funds it.

Reference

One key. Three API actions.

No SDK required. Use any backend that can make HTTPS requests.

Store the key Verify access Create request Check status Errors Rules

1. Keep the key on your server

Create it from Mission HQ → Publish → Developer API. NearbyCrew stores only a hash, so the full secret cannot be shown again later.

Environment variable on your own server

NC_API_KEY=nc_live_...

2. Verify access

This confirms the key, workspace ownership, public status, and current quota.

GET /api/v1/me

curl https://nearbycrew.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Create a request

Tell NearbyCrew what needs to be done. Optional people and who fields help define the crew and participant profile.

POST /api/v1/requests

curl https://nearbycrew.com/api/v1/requests \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "people": 5,
    "who": "developers who use coding tools",
    "request": "Use our beta during a real workflow and report what works, what breaks, and whether you would keep using it."
  }'

201 response · shortened

{
  "success": true,
  "api_version": "v1",
  "request_id": "req_...",
  "status": "quote_ready",
  "workspace_id": "...",
  "quote_id": "QUOTE-...",
  "ready_for_checkout": true,
  "quote": {
    "people": 5,
    "customer_total": 132.96,
    "currency": "USD"
  },
  "usage": {
    "dailyRequestsUsed": 1,
    "dailyRequestLimit": 10,
    "dailyRequestsRemaining": 9
  }
}

You can send request by itself. people and who are optional but useful when you want to state the crew requirement directly.

4. Check status

Save the request ID. Status reads do not use the daily mission create allowance.

GET /api/v1/requests/:requestId

curl https://nearbycrew.com/api/v1/requests/req_... \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

400

Bad request

The body is missing a usable request or another required value.

401

Unauthorized

The API key is missing, invalid, disabled, or rotated.

403

Forbidden

The key does not own that workspace, or the workspace is no longer public.

429

Too many requests

You hit the daily or per minute limit. Respect Retry After before retrying.

Rules that matter

Workspace

Public workspace required

Your key is bound to the listed workspace. Making it private disables public API use.

Approval

Human approval stays

Creating a request creates a quote, not an automatic charge or labor deployment.

Usage

Quota belongs to the workspace

Multiple keys share the same daily create allowance, so key rotation cannot bypass limits.

Billing

API v1 is free

The API layer is free in v1. The mission itself is separately funded if approved.

Questions

Common questions

Does this API immediately send people to work?

No. API v1 prepares and prices the request. The owner still reviews and funds it before deployment.

Can I put the key in frontend JavaScript?

No. Keep it on your server. A browser, public repository, or shipped mobile app can expose the secret.

Why does the project need to be public?

The public workspace ties the API key to a real project and gives people context if the work is later approved and deployed.

Do status reads count against the 10 per day create limit?

No. Status reads have their own 60 per minute limit.

Can I create several keys to get more daily requests?

No. The quota belongs to the workspace, so all active keys share the same daily create allowance.

Setup help

Need help making the first API call?

We can help you get the workspace public, create the server key, and make the first request.

Book setup help Create Citizen