Skip to main content

Stream Operations

Streams are the top-level container for a data processing pipeline. This document outlines the API endpoints for managing streams.

List Streams​

Retrieves all streams.

GET /stream/streams

Response​

{
  "success": true,
  "streams": [
    {
      "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
      "meta": {
        "name": "Basic Processing Pipeline",
        "description": "Simple pipeline to demonstrate stream processing"
      }
    },
    {
      "id": "f2a5c8d1-b730-42e6-9582-93e8b3d867f5",
      "meta": {
        "name": "EEG Processing Stream",
        "description": "Pipeline for processing EEG signals"
      }
    }
  ]
}

Get Stream​

Retrieves a specific stream by its ID.

GET /stream/streams/{streamId}

Response​

{
  "success": true,
  "stream": {
    "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
    "meta": {
      "name": "Basic Processing Pipeline",
      "description": "Simple pipeline to demonstrate stream processing"
    },
    "nodes": [
      {
        "id": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
        "type": "EXECUTABLE",
        "meta": {
          "type": "SOURCE"
        },
        "executable": "/usr/share/instinct/signal-generator",
        "config": {
          "sampleRate": 250,
          "channels": 4
        }
      },
      {
        "id": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292",
        "type": "EXECUTABLE",
        "meta": {
          "type": "FILTER"
        },
        "executable": "/usr/share/instinct/signal-filter",
        "config": {
          "highpass": 1.0,
          "lowpass": 35
        }
      }
    ],
    "pipes": [
      {
        "id": "e93b59c0-4dbf-48c5-9db8-19a312fd4aed",
        "source": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
        "destination": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292"
      }
    ]
  }
}

Create Stream​

Creates a new stream with specified nodes and pipes.

POST /stream/streams

Request Body​

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "meta": {
    "name": "Basic Processing Pipeline",
    "description": "Simple pipeline to demonstrate stream processing"
  },
  "nodes": [
    {
      "id": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
      "type": "EXECUTABLE",
      "meta": {
        "type": "SOURCE"
      },
      "executable": "/usr/share/instinct/signal-generator",
      "config": {
        "sampleRate": 250,
        "channels": 4
      }
    },
    {
      "id": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292",
      "type": "EXECUTABLE",
      "meta": {
        "type": "FILTER"
      },
      "executable": "/usr/share/instinct/signal-filter",
      "config": {
        "highpass": 1.0,
        "lowpass": 35
      }
    }
  ],
  "pipes": [
    {
      "id": "e93b59c0-4dbf-48c5-9db8-19a312fd4aed",
      "source": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
      "destination": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292"
    }
  ]
}

Response​

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "success": true
}

Update Stream​

Updates an existing stream.

PUT /stream/streams/{streamId}

Request Body​

{
  "meta": {
    "name": "Updated Processing Pipeline",
    "description": "Updated pipeline description"
  },
  "nodes": [
    {
      "id": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
      "type": "EXECUTABLE",
      "meta": {
        "type": "SOURCE"
      },
      "executable": "/usr/share/instinct/signal-generator",
      "config": {
        "sampleRate": 500,
        "channels": 8
      }
    }
  ],
  "pipes": []
}

Response​

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "success": true
}

Delete Stream​

Deletes a stream.

DELETE /stream/streams/{streamId}

Response​

{
  "success": true
}

Stream Signal​

Sends a signal to control the stream (start, stop, pause, resume).

POST /stream/streams/{streamId}/signal

Request Body​

signal=start

Other valid signals: stop, pause, resume

Response​

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "success": true
}

Stream Status​

Gets the current status of a stream.

GET /stream/streams/{streamId}/status

Response​

{
  "success": true,
  "status": {
    "state": "running",
    "nodes": [
      {
        "id": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
        "state": "running",
        "metrics": {
          "itemsProcessed": 2500,
          "errorCount": 0
        }
      },
      {
        "id": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292",
        "state": "running",
        "metrics": {
          "itemsProcessed": 2450,
          "errorCount": 0
        }
      }
    ]
  }
}

Important Notes​

Stream IDs​

All stream IDs must be valid UUIDs. When creating a new stream, you must provide a valid UUID as the ID. For example:

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "meta": {
    "name": "Basic Processing Pipeline"
  }
}

Stream Metadata​

The meta object is optional but recommended to provide useful information about the stream:

  • name: Human-readable name for the stream
  • description: Detailed description of the stream's purpose
  • tags: Array of strings to categorize the stream
  • version: Version number for tracking changes
  • created: Creation timestamp (set automatically)
  • updated: Last updated timestamp (updated automatically)

Stream Lifecycle​

A stream goes through several states during its lifecycle:

  1. created: Initial state after creation
  2. starting: Transitioning to running state
  3. running: Stream is actively processing data
  4. pausing: Transitioning to paused state
  5. paused: Stream processing is temporarily suspended
  6. stopping: Transitioning to stopped state
  7. stopped: Stream is not processing data
  8. error: Stream encountered an error

Using the Instinct SDKs​

It is recommended to use one of the Instinct SDKs to create and manage your streams:

  • JavaScript/TypeScript SDK
  • Python SDK
  • C++ SDK
  • Rust SDK

These SDKs handle the correct formatting of UUIDs and provide a more convenient interface for working with the API.