Quickstart

Give your AI agent a way to ask the real world.

Create your first HUMINT request draft through the API. Your agent defines what it needs, and you review the details before funding and publishing the request to human contributors.

01 AI drafts02 You review03 Fund & publish

Before you begin

You need a HUMINT wallet account with the current terms accepted. Create a request-only API key from your profile in the workspace.

1Create an API key

Open Workspace → My profile, find AI Request API, and create a named key. Copy it once and store it as HUMINT_API_KEY in your agent’s server environment.

Environment

export HUMINT_API_KEY="hmt_req_your_request_key"

The key has the requests:create scope and expires after 90 days by default. You can revoke it from your profile.

2Make your first request

Send a title, description and target region. Add reward settings now or complete them later when you review the draft.

POSThttps://humint.club/api/v1/requests

curl https://humint.club/api/v1/requests \
  -H "Authorization: Bearer $HUMINT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: osaka-menu-001" \
  -d '{
  "title": "Check current menu prices in Osaka",
  "description": "Photograph the publicly displayed menu and report current prices, including the observation date.",
  "region": "Osaka, Japan",
  "category": "economy_supply_chains",
  "currency": "USDG",
  "reward": "10",
  "slots": 1
}'

3Read the response

A new draft returns 201 Created. An identical retry returns 200 OK with the original draft ID.

201 Created · Example response

{
  "id": "d2b7c0e6-521d-4b17-8581-d79d44a81d37",
  "status": "draft",
  "published": false,
  "requiresWalletPublication": true,
  "reviewUrl": "/platform/requests/new?draft=d2b7c0e6-521d-4b17-8581-d79d44a81d37",
  "createdAt": "2026-10-28T09:00:00.000Z"
}

Save id for your records and give the account owner the reviewUrl. The path is relative to https://humint.club.

4Review, fund and publish

Open the review link.Sign in with the wallet account that created the API key. Your draft fills the existing request form.
Confirm the request.Complete the collection scope, questions, acceptance criteria, submission requirements, reward, currency and deadline.
Fund and publish.Sign the funding transaction with your wallet. The request becomes available to contributors once the transaction is confirmed.

Drafts also appear in the draft picker on the new-request page. API draft creation does not transfer funds.

API REFERENCE

Request fields

Send a JSON object. Unknown top-level fields are rejected. All fields except the three marked required are optional when creating a draft.

Field	Description
`title`stringrequired	5–100 characters. A short, public-facing request title.
`description`stringrequired	20–10,000 characters. Describe the information you need.
`region`stringrequired	2–60 characters. The target country, city or area.
`category`string	Defaults to other. Use one of the category codes below.
`currency`string	HRS (default) or USDG. The owner confirms the reward before funding.
`reward`string	Optional decimal string, such as "10". Up to 7 whole digits and 6 decimal places.
`slots`integer \| null	Optional. Between 1 and 100 recipients; defaults to null in a draft.
`deadline`string	Optional ISO 8601 UTC timestamp. The owner must set a valid deadline before publishing.
`collection`object	Optional objective, scope, collectionPeriod, questions, acceptanceCriteria, exclusions, deliveryInstructions and language.
`delivery`object	Optional text/file submission requirements. See OpenAPI for formats and constraints.
`privateBrief`string	Optional additional brief, up to 10,000 characters. Review its access settings before publishing.
`minLevel / approvalRequired`integer / boolean	Optional publication access settings. Default to 0 and false.

Category codes

regional_affairseconomy_supply_chainsinfrastructure_disastershumanitarian_conditionsother

Explore the complete OpenAPI schema

Errors & retries

Check the HTTP status before using the response. Errors include a message; some also include a code or validation details.

401 Unauthorized

{
  "message": "A valid request API key is required.",
  "code": "INVALID_API_KEY"
}

Status	What to do
`400`Invalid input	Check required fields, lengths, JSON types and the Idempotency-Key header.
`401`Invalid API key	Check the Bearer token. Replace an expired or revoked key in your workspace.
`403`Terms acceptance required	The account owner must accept the current terms in HUMINT.
`409`Idempotency conflict	That key was used with different content. Use a new key for a different request.
`429`Rate limit reached	Wait before retrying. Reuse the original idempotency key and input.

If a connection times out, retry with the original idempotency key and input. An identical retry preserves the existing draft, including any edits the owner has made.

Rate limits

20 / hour

New drafts per account

100 / day

New drafts per account

5 active keys

Per wallet account

Draft quotas use rolling windows and apply across all keys on an account. Identical retries do not consume the creation quota. The request endpoint also applies a 60-request-per-minute IP limit.

WORKSPACECreate your request key

REFERENCEOpenAPI specification