openapi: 3.1.0
info:
  title: GoldRush Pipeline API
  description: >
    Managed pipeline that streams decoded blockchain data into customer
    destinations (ClickHouse, Kafka, S3/GCS/R2, Postgres, AWS SQS, Webhook).
    Pipelines configure source chains, ABI decoding for events and functions,
    SQL transforms, and destination connection settings. Service Keys are the
    credential type used for programmatic pipeline management.
  version: v1
  contact:
    name: GoldRush Support
    url: https://goldrush.dev/support/
servers:
  - url: https://pipeline.goldrush.dev
    description: Pipeline REST API
security:
  - ServiceKeyAuth: []
tags:
  - name: Pipelines
    description: Create, list, update, and delete data pipelines.
  - name: Destinations
    description: Manage destination connections (ClickHouse, Kafka, S3/GCS/R2, Postgres, SQS, Webhook).
  - name: ABI
    description: Manage ABI definitions used for log and function decoding.
  - name: Transforms
    description: Manage SQL transforms applied to decoded events before delivery.
paths:
  /v1/pipelines:
    get:
      summary: List Pipelines
      operationId: listPipelines
      tags: [Pipelines]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/PipelineList' } } } }
    post:
      summary: Create Pipeline
      operationId: createPipeline
      tags: [Pipelines]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Pipeline' }
      responses:
        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/Pipeline' } } } }
  /v1/pipelines/{pipelineId}:
    get:
      summary: Get Pipeline
      operationId: getPipeline
      tags: [Pipelines]
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Pipeline' } } } }
    patch:
      summary: Update Pipeline
      operationId: updatePipeline
      tags: [Pipelines]
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Pipeline' }
      responses:
        '200': { description: OK }
    delete:
      summary: Delete Pipeline
      operationId: deletePipeline
      tags: [Pipelines]
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      responses:
        '204': { description: No Content }
  /v1/pipelines/{pipelineId}/start:
    post:
      summary: Start Pipeline
      operationId: startPipeline
      tags: [Pipelines]
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      responses:
        '202': { description: Accepted }
  /v1/pipelines/{pipelineId}/pause:
    post:
      summary: Pause Pipeline
      operationId: pausePipeline
      tags: [Pipelines]
      parameters:
        - $ref: '#/components/parameters/PipelineId'
      responses:
        '202': { description: Accepted }
  /v1/destinations:
    get:
      summary: List Destinations
      operationId: listDestinations
      tags: [Destinations]
      responses:
        '200': { description: OK }
    post:
      summary: Create Destination
      operationId: createDestination
      tags: [Destinations]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Destination' }
      responses:
        '201': { description: Created }
  /v1/destinations/{destinationId}:
    get:
      summary: Get Destination
      operationId: getDestination
      tags: [Destinations]
      parameters:
        - $ref: '#/components/parameters/DestinationId'
      responses:
        '200': { description: OK }
    delete:
      summary: Delete Destination
      operationId: deleteDestination
      tags: [Destinations]
      parameters:
        - $ref: '#/components/parameters/DestinationId'
      responses:
        '204': { description: No Content }
  /v1/abis:
    get:
      summary: List ABIs
      operationId: listAbis
      tags: [ABI]
      responses:
        '200': { description: OK }
    post:
      summary: Upload ABI
      operationId: uploadAbi
      tags: [ABI]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Abi' }
      responses:
        '201': { description: Created }
  /v1/transforms:
    get:
      summary: List SQL Transforms
      operationId: listTransforms
      tags: [Transforms]
      responses:
        '200': { description: OK }
    post:
      summary: Create SQL Transform
      operationId: createTransform
      tags: [Transforms]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Transform' }
      responses:
        '201': { description: Created }
components:
  securitySchemes:
    ServiceKeyAuth:
      type: http
      scheme: bearer
      description: "Pipeline Service Key, sent as `Authorization: Bearer <service-key>`."
  parameters:
    PipelineId:
      name: pipelineId
      in: path
      required: true
      schema: { type: string }
    DestinationId:
      name: destinationId
      in: path
      required: true
      schema: { type: string }
  schemas:
    PipelineList:
      type: object
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/Pipeline' }
    Pipeline:
      type: object
      required: [name, source, destinationId]
      properties:
        id: { type: string, readOnly: true }
        name: { type: string }
        description: { type: string }
        source:
          type: object
          properties:
            chain: { type: string, description: Chain slug (e.g., eth-mainnet). }
            startBlock: { type: integer }
            endBlock: { type: integer, nullable: true }
            contractAddresses: { type: array, items: { type: string } }
            topics: { type: array, items: { type: string } }
        destinationId: { type: string }
        decoder:
          type: object
          properties:
            abiIds: { type: array, items: { type: string } }
            normalizer:
              type: string
              enum: [evm, solana, hypercore]
        transformIds:
          type: array
          items: { type: string }
        state:
          type: string
          enum: [draft, running, paused, errored]
          readOnly: true
        createdAt: { type: string, format: date-time, readOnly: true }
    Destination:
      type: object
      required: [type, name, config]
      properties:
        id: { type: string, readOnly: true }
        name: { type: string }
        type:
          type: string
          enum: [clickhouse, kafka, object_storage, postgres, sqs, webhook]
        config:
          type: object
          additionalProperties: true
          description: Connection config (host, bucket, topic, queue URL, webhook URL, credentials, format).
    Abi:
      type: object
      required: [name, abi]
      properties:
        id: { type: string, readOnly: true }
        name: { type: string }
        abi:
          type: array
          description: JSON ABI definition.
          items: { type: object, additionalProperties: true }
    Transform:
      type: object
      required: [name, sql]
      properties:
        id: { type: string, readOnly: true }
        name: { type: string }
        sql:
          type: string
          description: SQL applied to the decoded event stream before delivery.