tenzro-xyz Fieldwork API

openapi: 3.2.0
info:
  title: Tenzro Labs Platform Fieldwork API
  version: 1.0.0
  description: Browse the curated catalogue; manage credits, billing, keys, plans and rentals; place and pay orders; run Datasets, Fieldwork, Voices and Forecasts. Chat, embeddings, images, speech and the model list keep the OpenAI-compatible /v1 paths.
servers:
- url: https://api.tenzro.xyz
security:
- apiKey: []
tags:
- name: Fieldwork
paths:
  /fieldwork/policy:
    get:
      tags:
      - Fieldwork
      summary: The rules every project is held to, the reason codes, and the acceptable use…
      description: No key needed.
      operationId: getFieldworkPolicy
      x-tenzro-scope: public
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/preview:
    post:
      tags:
      - Fieldwork
      summary: 'Check settings without saving: errors, warnings and the participant notice they…'
      description: No key needed.
      operationId: postFieldworkPreview
      x-tenzro-scope: public
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects:
    get:
      tags:
      - Fieldwork
      summary: List projects
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjects
      x-tenzro-scope: fieldwork:read
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Fieldwork
      summary: Create a draft project (settings as in the console)
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkProjects
      x-tenzro-scope: fieldwork:write
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}:
    get:
      tags:
      - Fieldwork
      summary: Get a project
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsById
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - Fieldwork
      summary: Change settings.
      description: Needs a key with the `fieldwork:write` permission.
      operationId: patchFieldworkProjectsById
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Fieldwork
      summary: Delete a project that was never published
      description: Needs a key with the `fieldwork:write` permission.
      operationId: deleteFieldworkProjectsById
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/publish:
    post:
      tags:
      - Fieldwork
      summary: Publishing is done by the account holder in the console, where they accept the…
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkProjectsByIdPublish
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/pause:
    post:
      tags:
      - Fieldwork
      summary: Stop taking recordings for now
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkProjectsByIdPause
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/resume:
    post:
      tags:
      - Fieldwork
      summary: Take recordings again
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkProjectsByIdResume
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/close:
    post:
      tags:
      - Fieldwork
      summary: Close for good
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkProjectsByIdClose
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/stats:
    get:
      tags:
      - Fieldwork
      summary: Items by status and participants
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdStats
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/coverage:
    get:
      tags:
      - Fieldwork
      summary: Accepted items against each quota
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdCoverage
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/items:
    get:
      tags:
      - Fieldwork
      summary: Items, newest first; ?status=pending|accepted|rejected|disputed|auto_rejected|wi…
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdItems
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/queue:
    get:
      tags:
      - Fieldwork
      summary: The next items for this key to review (items it already voted on are left out…
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdQueue
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/items/{id}/review:
    post:
      tags:
      - Fieldwork
      summary: 'Vote on an item: {decision: accept|reject, reason (required to reject), note}'
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkItemsByIdReview
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/items/{id}/gold:
    post:
      tags:
      - Fieldwork
      summary: Make a decided item a gold item with its known answer ({expect…
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkItemsByIdGold
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/items/{id}/audio:
    get:
      tags:
      - Fieldwork
      summary: The item's audio as WAV (byte ranges supported); ?copy=train for the 16 kHz copy
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkItemsByIdAudio
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            audio/wav:
              schema:
                type: string
                format: binary
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/items/{id}/file:
    get:
      tags:
      - Fieldwork
      summary: 'The item''s file as it was collected: audio, photo, video or readings (byte…'
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkItemsByIdFile
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/export:
    post:
      tags:
      - Fieldwork
      summary: 'Cut a dataset version of the accepted items: {dest_country, mechanism}; leaving…'
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkProjectsByIdExport
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/exports:
    get:
      tags:
      - Fieldwork
      summary: 'Export log: who, when, where, under which mechanism'
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdExports
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/withdrawals:
    get:
      tags:
      - Fieldwork
      summary: Withdrawn items to delete from your copies within 30 days and exclude from…
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdWithdrawals
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/ingest-keys:
    get:
      tags:
      - Fieldwork
      summary: Ingest keys for this project (browser-safe keys for the project's own page…
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdIngestKeys
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Fieldwork
      summary: 'Create an ingest key {name, allowed_origins}: bound to this project and those…'
      description: Needs a key with the `fieldwork:write` permission.
      operationId: postFieldworkProjectsByIdIngestKeys
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/ingest-keys/{keyId}:
    patch:
      tags:
      - Fieldwork
      summary: 'Change the origins a key works from: {allowed_origins}'
      description: Needs a key with the `fieldwork:write` permission.
      operationId: patchFieldworkProjectsByIdIngestKeysByKeyId
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Fieldwork
      summary: Revoke an ingest key; it stops on its next request
      description: Needs a key with the `fieldwork:write` permission.
      operationId: deleteFieldworkProjectsByIdIngestKeysByKeyId
      x-tenzro-scope: fieldwork:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: keyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/payouts:
    get:
      tags:
      - Fieldwork
      summary: Participant rewards (coming soon)
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdPayouts
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /fieldwork/projects/{id}/reviewers:
    get:
      tags:
      - Fieldwork
      summary: Votes and gold agreement per reviewer
      description: Needs a key with the `fieldwork:read` permission.
      operationId: getFieldworkProjectsByIdReviewers
      x-tenzro-scope: fieldwork:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json: {}
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            scope:
              type: string
              description: 'On a 403: the permission the key lacks.'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: A Tenzro Labs API key (tzl_…).
    ingestKey:
      type: http
      scheme: bearer
      description: 'A Fieldwork ingest key (tzi_…): bound to one project and the origins listed on it, able only to run the participant flow. Safe in a browser. Create it with POST /fieldwork/projects/{id}/ingest-keys.'
    serviceAssertion:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'A Tenzro Labs service''s ES256 assertion: header kid = the RFC 7638 thumbprint of a key in the service''s published JWKS; iss = sub = the service; aud = this endpoint; exp at most 60 s after iat; jti used once.'