> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firedrill.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish synthetic Tool data

> Requires `services:publish`. Pins seed records to an exact project-owned build and optional managed starting time/provenance. Duplicate namespace/row identities are rejected. An omitted dataset is not a request for starter records.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/service-datasets
openapi: 3.1.0
info:
  title: Firedrill API
  version: '2026-10-14'
  description: >-
    Authenticated simulation coordination, retained evidence and controlled
    Tools. Your customer-owned runner executes the target. This reference covers
    the documented JSON workflows; Tool-native HTTP routes and MCP methods are
    discovered from the selected Tool. Structural schemas do not replace
    canonical validation or capability checks.
servers:
  - url: https://api.firedrill.run
security:
  - FiredrillCredential: []
tags:
  - name: discovery
    description: Capabilities, authority and structural authoring schemas.
  - name: projects
    description: Projects and their logical environment.
  - name: simulations
    description: Preparation, queued batches and cancellation.
  - name: runs
    description: Individual recorded executions.
  - name: reports
    description: Retained observations, distributions and descriptive comparisons.
  - name: assessment
    description: Optional semantic assessment and authored scenario ranking.
  - name: evidence
    description: Authenticated captured files.
  - name: runner-protocol
    description: Advanced customer-runner coordination; native SDKs manage this protocol.
  - name: scenarios
    description: Immutable retained versions of repository-authored scenarios.
  - name: credentials
    description: Expiring scoped CI credentials.
  - name: authentication
    description: Human-approved sign-in boundaries.
  - name: tools
    description: Tool releases, data, instances and observations.
  - name: tool-connections
    description: Bounded target/manual grants, separate from control authority.
  - name: tool-lifecycle
    description: Epoch-fenced reusable Tool actions and exact-key recovery.
paths:
  /v1/service-datasets:
    post:
      tags:
        - tools
      summary: Publish synthetic Tool data
      description: >-
        Requires `services:publish`. Pins seed records to an exact project-owned
        build and optional managed starting time/provenance. Duplicate
        namespace/row identities are rejected. An omitted dataset is not a
        request for starter records.
      operationId: tool_datasets_publish
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishDatasetInput'
      responses:
        '200':
          description: The retained resource or operation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDataset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/InvalidInput'
        '429':
          $ref: '#/components/responses/Capacity'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        Save a unique stable key for this exact logical action, at most 200
        characters. Reuse it with identical input after an uncertain response. A
        new key is new intent; it must not be used merely to recover an accepted
        action.
      schema:
        type: string
        minLength: 1
        maxLength: 200
  schemas:
    PublishDatasetInput:
      type: object
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 160
        environmentId:
          type: string
          minLength: 1
          maxLength: 160
        buildId:
          type: string
          minLength: 1
          maxLength: 160
        records:
          maxItems: 100000
          type: array
          items:
            $ref: '#/components/schemas/DatasetRecordInput'
        initialVirtualTimeUs:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        metadata:
          type: object
          properties:
            schemaVersion:
              type: string
              const: 2026-10-15-dataset-metadata.1
            provenance:
              type: object
              properties:
                kind:
                  type: string
                  enum:
                    - authored
                    - generated
                    - imported
                description:
                  type: string
                  maxLength: 512
                sensitive:
                  type: boolean
                authorizedImport:
                  type: boolean
                  const: true
              required:
                - kind
                - sensitive
              additionalProperties: false
            mappings:
              maxItems: 32
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    pattern: ^[a-z][a-z0-9_-]{0,63}$
                  namespace:
                    type: string
                    maxLength: 96
                    pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$
                  pointer:
                    type: string
                    maxLength: 512
                  optional:
                    type: boolean
                  target:
                    type: object
                    properties:
                      datasetId:
                        type: string
                        minLength: 1
                        maxLength: 160
                      version:
                        type: string
                        pattern: ^sha256:[a-f0-9]{64}$
                      namespace:
                        type: string
                        maxLength: 96
                        pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$
                      pointer:
                        type: string
                        maxLength: 512
                    required:
                      - datasetId
                      - version
                      - namespace
                    additionalProperties: false
                required:
                  - id
                  - namespace
                  - pointer
                  - target
                additionalProperties: false
          required:
            - schemaVersion
          additionalProperties: false
      required:
        - projectId
        - environmentId
        - buildId
        - records
      additionalProperties: false
    ServiceDataset:
      type: object
      properties:
        schemaVersion:
          type: string
          enum:
            - 2026-10-15-dataset.1
        id:
          type: string
        projectId:
          type: string
        buildId:
          type: string
        version:
          type: string
        records:
          type: number
        initialVirtualTimeUs:
          anyOf:
            - type: number
        metadata:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/DatasetMetadata'
        validation:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/DatasetValidationReceipt'
        validationStatus:
          type: string
          enum:
            - not_recorded
            - validated
        createdAt:
          type: string
      required:
        - id
        - projectId
        - buildId
        - version
        - records
        - createdAt
    DatasetRecordInput:
      type: object
      properties:
        namespace:
          type: string
          maxLength: 96
          pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$
        rowId:
          type: string
          minLength: 1
          maxLength: 512
        value:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            $ref: '#/components/schemas/SharedDefinitionsSchema0'
      required:
        - namespace
        - rowId
        - value
      additionalProperties: false
    DatasetMetadata:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-15-dataset-metadata.1
        provenance:
          anyOf:
            - $ref: '#/components/schemas/DatasetProvenance'
        mappings:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/DatasetMapping'
      required:
        - schemaVersion
    DatasetValidationReceipt:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-15-dataset-validation.1
        state:
          type: string
          const: validated
        manifestDigest:
          type: string
        recordsDigest:
          type: string
        metadataDigest:
          anyOf:
            - type: 'null'
            - type: string
        policyDigest:
          anyOf:
            - type: 'null'
            - type: string
        checkedRecords:
          type: number
        schema:
          type: string
          const: valid
        domain:
          type: object
          properties:
            state:
              type: string
              enum:
                - satisfied
                - not_declared
            constraintIds:
              type: array
              items:
                type: string
          required:
            - state
            - constraintIds
        mappings:
          type: object
          properties:
            state:
              type: string
              enum:
                - satisfied
                - not_declared
            checks:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  datasetId:
                    type: string
                  version:
                    type: string
                  recordsDigest:
                    type: string
                required:
                  - id
                  - datasetId
                  - version
                  - recordsDigest
          required:
            - state
            - checks
        provenance:
          type: object
          properties:
            state:
              type: string
              enum:
                - not_recorded
                - caller_declared
            kind:
              anyOf:
                - type: 'null'
                - type: string
                  const: authored
                - type: string
                  const: generated
                - type: string
                  const: imported
            sensitive:
              anyOf:
                - type: 'null'
                - type: boolean
                  const: false
                - type: boolean
                  const: true
            importAuthorization:
              type: string
              enum:
                - not_applicable
                - not_recorded
                - caller_asserted
          required:
            - state
            - kind
            - sensitive
            - importAuthorization
        fidelity:
          type: string
          const: not_established
        validatedAt:
          type: string
        digest:
          type: string
      required:
        - schemaVersion
        - state
        - manifestDigest
        - recordsDigest
        - metadataDigest
        - policyDigest
        - checkedRecords
        - schema
        - domain
        - mappings
        - provenance
        - fidelity
        - validatedAt
        - digest
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            repair:
              type: string
            requestId:
              type: string
            details:
              anyOf:
                - type: 'null'
                - type: string
                - type: number
                - type: boolean
                  const: false
                - type: boolean
                  const: true
                - type: array
                  items:
                    $ref: '#/components/schemas/JsonValue'
                - type: object
                  properties: {}
                  required: []
                  additionalProperties:
                    $ref: '#/components/schemas/JsonValue'
            validation:
              anyOf:
                - $ref: '#/components/schemas/ValidationDiagnostics'
          required:
            - code
            - message
            - repair
            - requestId
      required:
        - error
    SharedDefinitionsSchema0:
      description: >-
        Any JSON value: null, boolean, finite number, string, array or object.
        The request transport must contain valid JSON; canonical validation
        rejects nonfinite numbers.
    DatasetProvenance:
      type: object
      properties:
        kind:
          type: string
          enum:
            - authored
            - generated
            - imported
        sensitive:
          type: boolean
        description:
          anyOf:
            - type: string
        authorizedImport:
          anyOf:
            - type: boolean
              const: true
      required:
        - kind
        - sensitive
    DatasetMapping:
      type: object
      properties:
        id:
          type: string
        namespace:
          type: string
        pointer:
          type: string
        target:
          type: object
          properties:
            datasetId:
              type: string
            version:
              type: string
            namespace:
              type: string
            pointer:
              anyOf:
                - type: string
          required:
            - datasetId
            - version
            - namespace
        optional:
          anyOf:
            - type: boolean
              const: false
            - type: boolean
              const: true
      required:
        - id
        - namespace
        - pointer
        - target
    JsonValue:
      description: >-
        Any JSON value: null, boolean, finite number, string, array or object.
        The request transport must contain valid JSON; canonical validation
        rejects nonfinite numbers.
    ValidationDiagnostics:
      type: object
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        totalIssues:
          type: number
        omittedIssues:
          type: number
      required:
        - issues
        - totalIssues
        - omittedIssues
    ValidationIssue:
      type: object
      properties:
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: number
        code:
          type: string
        message:
          type: string
        pathTruncated:
          anyOf:
            - type: boolean
              const: true
      required:
        - path
        - code
        - message
  responses:
    BadRequest:
      description: >-
        Malformed request or missing operation key. Repair the input before
        retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: >-
        Missing, expired or revoked authority. Complete supported sign-in or use
        an authorized credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: >-
        The current capability, actor, audience or ownership grant does not
        allow this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: The exact resource is unavailable under the current authority and scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Conflict:
      description: >-
        Selected context, epoch, revision, lease or saved operation intent
        conflicts; inspect retained state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Gone:
      description: >-
        Retained content is expired, deleted or unavailable under its retention
        fence. Metadata is not a replacement payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    PayloadTooLarge:
      description: >-
        Request, response or retained-resource size exceeds this operation’s
        enforced bound.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    UnsupportedMediaType:
      description: Send the documented JSON or exact artifact media type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InvalidInput:
      description: >-
        Input failed canonical validation. Inspect error.validation and repair
        the indicated fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Capacity:
      description: >-
        Bounded capacity or resource admission rejected the operation. Inspect
        retained work before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Internal:
      description: >-
        The service could not complete the request. Inspect retained state
        before exact-key recovery.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unavailable:
      description: >-
        A required service, provider or authority check is unavailable. Existing
        evidence remains separate from this failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    FiredrillCredential:
      type: http
      scheme: bearer
      description: >-
        Opaque Firedrill interactive or scoped machine credential. The CLI
        handles human-approved login; CI stores its scoped credential as
        FIREDRILL_TOKEN. Capabilities and project/environment ownership are
        rechecked at use.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.