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

# Run a tap

> Executes a saved tap. Optionally sends data to the configured pipeline.



## OpenAPI

````yaml /openapi.yaml post /api/v1/tap/run
openapi: 3.0.3
info:
  title: Datris API
  description: >
    REST API for the Datris AI Data Platform. Ingest, validate, transform,
    store, and retrieve data.


    For AI agent integration, use the [MCP
    Server](https://docs.datris.ai/mcp-server) instead.
  version: 1.0.0
  contact:
    name: Datris
    url: https://datris.ai
  license:
    name: Apache 2.0
servers:
  - url: http://localhost:8080
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /api/v1/tap/run:
    post:
      tags:
        - Taps
      summary: Run a tap
      description: Executes a saved tap. Optionally sends data to the configured pipeline.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                mode:
                  type: string
                  enum:
                    - run
                    - test
                  default: test
                  description: >-
                    'run' feeds records into the configured target pipeline;
                    'test' executes the script and returns results without
                    persisting
                params:
                  type: object
                  additionalProperties: true
                  description: >-
                    Optional per-run parameters. Each value is stringified and
                    exposed to the tap script as an environment variable (nested
                    objects/arrays are JSON-encoded so the script can
                    json.loads() them back). Use for date-windowed backfills,
                    e.g. {"since": "2026-05-01", "until": "2026-05-02"}. From
                    Airflow, pass Jinja-templated values like {"since": "{{ ds
                    }}"}.
                  example:
                    since: '2026-05-01'
                    until: '2026-05-02'
      responses:
        '200':
          description: Run result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TapRunResult'
components:
  schemas:
    TapRunResult:
      type: object
      properties:
        tap:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - success
            - failure
        mode:
          type: string
          enum:
            - run
            - test
          description: The mode this invocation ran in
        targetPipeline:
          type: string
          nullable: true
          description: >-
            The pipeline configured on the tap (null if none — records will not
            persist)
        persisted:
          type: boolean
          description: True iff records were fed into the target pipeline
        persistedReason:
          type: string
          enum:
            - test_mode
            - run_error
            - no_records
            - no_target_pipeline
          description: >-
            Present when persisted is false; explains why records did not land
            in a pipeline
        publisherToken:
          type: string
          description: >-
            UUID grouping every ingestion job this run submitted. Pass to GET
            /pipeline/status?publishertoken= to watch load progress. Only
            present on persisted runs.
        pipelineTokens:
          type: array
          items:
            type: string
          description: >-
            UUIDs for each StreamNotifier job submitted. Length 1 for structured
            taps, N for document taps (one per document). Only present on
            persisted runs.
        records:
          type: array
          items:
            type: object
        recordCount:
          type: integer
        dataType:
          type: string
        columns:
          type: array
          items:
            type: string
        logs:
          type: string
        error:
          type: string
        aiExplanation:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Optional API key for authentication (enabled via application.yaml)

````