Fieldwork

How it works

• Create a project in the console or through the API, then set who can take part, the policy and consent, branding, the data type, prompts and rewards.
• The account holder publishes the project in the console, where they accept the acceptable use policy. The API and agents can prepare a project but not publish it.
• Participants open /f/<project>, confirm they are 18 or over, read the notice and give each consent separately, then record.
• Your team reviews each item. Accepted items go into a dataset in Datasets with their consent record and provenance.
• A participant can withdraw at any time; their items leave new versions and you see a delete-by date in the console and the API.

Keys and scopes

Calls use a Platform API key holding fieldwork:read or fieldwork:write. Add the scopes on the Keys page. The API lives on https://api.tenzro.xyz/fieldwork without a version prefix.

Create a project

curl https://api.tenzro.xyz/fieldwork/projects \
  -H "Authorization: Bearer $TENZRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kitchen commands"}'

Collect on your own page

A project can collect through your own web page or app instead of the hosted /f/<project> page. Create an ingest key (tzi_…) for the project in the console, or with fieldwork:write. It belongs to one project, works only from the origins you list (https, or http on localhost; no wildcards), and can only run the participant flow, so it is safe to put in the page. It cannot read recordings or change the project. Revoking it stops the next request.

curl -X POST https://api.tenzro.xyz/fieldwork/projects/fwproj_…/ingest-keys \
  -H "Authorization: Bearer $TENZRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sidekick web page", "allowed_origins": ["https://sidekick.example"]}'

Your page calls https://api.tenzro.xyz/ingest directly from the participant's browser, with Authorization: Bearer tzi_…. The same rules as the hosted page apply: the page check, the age and place gate, the consent text, the quality checks and withdrawal. Show the notice and consent options that /ingest/project returns, and send the participant's choices. Keep the participant token in the page; it is the participant's session. Send X-Device-Id (a random id the page keeps) so limits count the person's device, not your server.

const API = "https://api.tenzro.xyz/ingest";
const KEY = "tzi_…"; // the ingest key: safe in the page
const H = { Authorization: `Bearer ${KEY}` };

const project = await (await fetch(`${API}/project`, { headers: H })).json();

// 1. Page check: find a nonce so sha256(challenge + ":" + nonce) has `bits` leading zero bits.
const { challenge, bits } = await (await fetch(`${API}/challenge`, { headers: H })).json();
async function solve() {
  for (let n = 0; ; n++) {
    const h = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${challenge}:${n}`)));
    let zeros = 0;
    for (const b of h) { if (b === 0) { zeros += 8; continue; } zeros += Math.clz32(b) - 24; break; }
    if (zeros >= bits) return String(n);
  }
}

// 2. Start a participant (only after showing project.notice and project.consent).
const start = await fetch(`${API}/participants`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({ country: "SG", dob: "1990-04-02", challenge, nonce: await solve() }),
});
const { participant_token } = await start.json();
const P = { ...H, "X-Participant-Token": participant_token };

// 3. Consent, then one take per prompt (wav = a 16-bit mono PCM WAV as an ArrayBuffer).
await fetch(`${API}/participant/consent`, {
  method: "POST",
  headers: { ...P, "Content-Type": "application/json" },
  body: JSON.stringify({ given: { purpose: true, training: true } }),
});
const sha = [...new Uint8Array(await crypto.subtle.digest("SHA-256", wav))].map((b) => b.toString(16).padStart(2, "0")).join("");
const res = await fetch(`${API}/items?prompt=${project.prompts[0].id}`, {
  method: "POST",
  headers: { ...P, "Content-Type": "audio/wav", "X-Content-Sha256": sha },
  body: wav,
});
console.log(await res.json()); // { item_id, status, problems, qc }

Which law applies

A project is held to the law of the places involved: where its controller is and where participants can be. It is not assumed to be an EU project. A project run from Singapore for people in Singapore is under Singapore's PDPA; the participant notice names that regulator, and an export out of Singapore needs a contract or similar route that gives comparable protection. The EU transfer mechanisms (adequacy, Data Privacy Framework, standard contractual clauses, UK agreement) are asked for only when the EU/EEA, UK or Switzerland is involved. China is its own case: participants give a separate consent to a transfer out of China, and exports need the China standard contract, a security assessment or certification.

The editor lists the laws that apply to your choices and whether an export to the destination needs a mechanism. GET /fieldwork/policy lists the law and regulator per country. Every entry is pending legal review: have counsel check it for your project. The Platform stores recordings in the EU, and the notice says so; for participants elsewhere that is itself a transfer you are responsible for.

Review

curl "https://api.tenzro.xyz/fieldwork/projects/fwproj_…/queue" -H "Authorization: Bearer $TENZRO_API_KEY"

curl https://api.tenzro.xyz/fieldwork/items/fwi_…/review \
  -H "Authorization: Bearer $TENZRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision": "accept"}'

Export to a dataset

curl -X POST https://api.tenzro.xyz/fieldwork/projects/fwproj_…/export -H "Authorization: Bearer $TENZRO_API_KEY"

Endpoints

From agents

The same functions are tools on the MCP server. Publishing stays with the account holder.

Pricing

Amounts are in each row's unit. Included amounts are used first, then credits.