Flow Logo

API Reference

REST API Reference

Flow's REST API provides comprehensive access to all platform features. This reference documents every available endpoint with examples, parameters, and responses.

Base URL

All REST API endpoints are available at:

https://api.flow.bio/

Authentication

REST API endpoints use JWT authentication. Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Obtain tokens through the authentication endpoints below.

Authentication & User Management

Sign Up

Create a new user account.

Endpoint: POST /signup

Request Body:

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "secure_password123",
  "first_name": "John",
  "last_name": "Doe"
}

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com"
  }
}

Login

Authenticate with username/email and password.

Endpoint: POST /login

Request Body:

{
  "username": "john_doe",
  "password": "secure_password123"
}

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com"
  }
}

OIDC Login

Authenticate using OpenID Connect.

Endpoint: POST /oidc-login

Request Body:

{
  "id_token": "<oidc_id_token>"
}

Logout

End the current session.

Endpoint: POST /logout

Get Current User

Retrieve information about the authenticated user.

Endpoint: GET /me

Response:

{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "groups": ["research-lab"],
  "can_run_pipelines": true
}

Get Access Token

Refresh or get a new access token.

Endpoint: GET /token

Request Password Reset

Endpoint: POST /password-reset/request

Request Body:

{
  "email": "john@example.com"
}

Reset Password

Endpoint: POST /password-reset

Request Body:

{
  "token": "reset_token_from_email",
  "password": "new_secure_password123"
}

Update User Settings

Endpoint: POST /settings/user

Request Body:

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com"
}

Update Password

Endpoint: POST /settings/password

Request Body:

{
  "current_password": "old_password",
  "new_password": "new_secure_password"
}

Update SSH Key

Endpoint: POST /settings/key

Request Body:

{
  "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EA..."
}

Data Management

List Owned Data

Endpoint: GET /data/owned

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset
  • filter - Text search

Response:

{
  "count": 250,
  "page": 1,
  "data": [
    {
      "id": 789,
      "filename": "sample_R1.fastq.gz",
      "size": 1073741824,
      "data_type": "FASTQ",
      "created": "2024-01-10T10:00:00Z",
      "sample": {
        "id": 123,
        "name": "Sample-001"
      }
    }
  ]
}

List Shared Data

Endpoint: GET /data/shared

Get Data Details

Endpoint: GET /data/<data_id>

Response:

{
  "id": 789,
  "filename": "sample_R1.fastq.gz",
  "size": 1073741824,
  "data_type": "FASTQ",
  "md5": "d41d8cd98f00b204e9800998ecf8427e",
  "created": "2024-01-10T10:00:00Z",
  "sample": {
    "id": 123,
    "name": "Sample-001"
  },
  "fileset": {
    "id": 45,
    "name": "Paired-end reads"
  },
  "permissions": {
    "can_edit": true,
    "can_share": true,
    "can_delete": true
  }
}

Get File Contents

Stream file contents for preview or download.

Endpoint: GET /data/<data_id>/contents

Query Parameters:

  • lines - Number of lines to return (for text preview)
  • download - Force download with Content-Disposition header

Response: File contents (text or binary)

Get Downstream Executions

Get all executions that used this data file.

Endpoint: GET /data/<data_id>/downstream

Response:

{
  "executions": [
    {
      "id": 456,
      "name": "RNA-seq analysis",
      "pipeline": "RNA-seq",
      "status": "completed"
    }
  ]
}

Import Data

Import data from external sources.

Endpoint: POST /data/import

Request Body:

{
  "source": "s3",
  "path": "s3://bucket/path/to/file.fastq.gz",
  "sample_id": 123,
  "data_type": "FASTQ"
}

Share Data

Endpoint: POST /data/<data_id>/share

Request Body:

{
  "users": ["user1"],
  "groups": ["lab-group"],
  "permission": 1
}

Transfer Data Ownership

Endpoint: POST /data/<data_id>/transfer

Request Body:

{
  "user": "new_owner_username"
}

Delete Data

Endpoint: POST /data/<data_id>/delete

Batch Delete Data

Endpoint: POST /data/delete

Request Body:

{
  "ids": [789, 790, 791]
}

Data Types Management

Endpoint: GET /data/types

Endpoint: POST /data/types/create

Endpoint: POST /data/types/<type_id>/edit

Endpoint: POST /data/types/<type_id>/delete

Endpoint: GET /data/types/available

Fileset Operations

Endpoint: GET /filesets/<fileset_id>

Response:

{
  "id": 45,
  "name": "Paired-end reads",
  "sample": {
    "id": 123,
    "name": "Sample-001"
  },
  "files": [
    {
      "id": 789,
      "filename": "sample_R1.fastq.gz",
      "read_number": 1
    },
    {
      "id": 790,
      "filename": "sample_R2.fastq.gz",
      "read_number": 2
    }
  ]
}

Endpoint: GET /filesets/<fileset_id>/executions

File Upload Endpoints

Upload Data File

Upload general data files in chunks.

Endpoint: POST /upload

Headers:

Content-Type: multipart/form-data
Authorization: Bearer <access_token>

Form Data:

  • file - File chunk (binary)
  • filename - Original filename
  • chunk - Chunk number (starting from 0)
  • total_chunks - Total number of chunks
  • file_id - Unique identifier for this upload session

Example:

curl -X POST https://api.flow.bio/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@chunk1.dat" \
  -F "filename=sample.fastq.gz" \
  -F "chunk=0" \
  -F "total_chunks=5" \
  -F "file_id=unique-upload-id"

Response:

{
  "status": "success",
  "chunk": 0,
  "total_chunks": 5,
  "file_id": "unique-upload-id"
}

Upload Sample Data

Upload sample data files with metadata.

Endpoint: POST /upload/sample

Form Data:

  • file - File data (binary)
  • sample_id - Sample ID to attach to
  • read_number - Read number (1 or 2 for paired-end)
  • lane - Sequencing lane (optional)

Example:

curl -X POST https://api.flow.bio/upload/sample \
  -H "Authorization: Bearer <token>" \
  -F "file=@reads_R1.fastq.gz" \
  -F "sample_id=12345" \
  -F "read_number=1"

File Download Endpoints

Download Data File

Download a specific data file.

Endpoint: GET /downloads/<data_id>/<filename>

Headers:

Authorization: Bearer <access_token>

Query Parameters:

  • format - (Optional) Request specific format conversion

Example:

curl -H "Authorization: Bearer <token>" \
  https://api.flow.bio/downloads/12345/output.fastq.gz \
  -o output.fastq.gz

Response: Binary file data

Download Execution Results

Download all results from an execution as a zip file.

Endpoint: GET /executions/<execution_id>/<filename>

Example:

curl -H "Authorization: Bearer <token>" \
  https://api.flow.bio/executions/12345/results.zip \
  -o results.zip

Bulk Download Status

Check the status of a bulk download job.

Endpoint: GET /downloads/status

Response:

{
  "id": "job-123",
  "status": "completed",
  "progress": 100,
  "download_url": "/downloads/123/",
  "expires_at": "2024-01-15T10:00:00Z"
}

Download Bulk Archive

Download the completed bulk archive.

Endpoint: GET /downloads/<job_id>

Example:

curl -H "Authorization: Bearer <token>" \
  https://api.flow.bio/downloads/123 \
  -o bulk_download.zip

Search Endpoints

Search across all resource types with a simple query.

Endpoint: GET /search

Query Parameters:

  • q - Search query (searches names and descriptions)
  • limit - Maximum results per type (default: 10)

Example:

curl -H "Authorization: Bearer <token>" \
  "https://api.flow.bio/search?q=rna-seq"

Response:

{
  "results": {
    "samples": [
      {
        "id": 123,
        "name": "RNA-seq Sample 1",
        "type": "sample",
        "url": "/samples/123/"
      }
    ],
    "projects": [],
    "executions": [],
    "data": []
  },
  "total_count": 1,
  "query": "rna-seq"
}

Search Info

Get metadata for advanced search filters.

Endpoint: GET /search/info

Response:

{
  "organisms": [
    {"id": "human", "name": "Homo sapiens"},
    {"id": "mouse", "name": "Mus musculus"}
  ],
  "pipelines": [
    {"id": 1, "name": "RNA-seq"},
    {"id": 2, "name": "ChIP-seq"}
  ],
  "sample_types": ["RNA", "DNA", "Protein"],
  "data_types": ["FASTQ", "BAM", "VCF"]
}

Search Users

Endpoint: GET /users/search

Query Parameters:

  • q - Search query (username, email, name)
  • limit - Maximum results (default: 20)

Search Groups

Endpoint: GET /groups/search

Query Parameters:

  • q - Search query (group name or slug)
  • limit - Maximum results (default: 20)

Endpoint: GET /samples/search

Query Parameters:

  • filter - General text search
  • organism - Filter by organism ID
  • sample_type - Filter by sample type
  • project - Filter by project ID
  • created_after - Filter by creation date
  • created_before - Filter by creation date
  • limit - Results per page
  • offset - Pagination offset

Example:

curl -H "Authorization: Bearer <token>" \
  "https://api.flow.bio/samples/search?organism=human&sample_type=RNA&limit=50"

Endpoint: GET /projects/search

Query Parameters:

  • filter - General text search
  • organism - Filter by organism ID
  • created_after - Filter by creation date
  • created_before - Filter by creation date
  • has_samples - Filter projects with/without samples
  • limit - Results per page
  • offset - Pagination offset

Endpoint: GET /data/search

Query Parameters:

  • filter - General text search
  • pattern - File name pattern (supports wildcards)
  • data_type - Filter by data type
  • size_min - Minimum file size in bytes
  • size_max - Maximum file size in bytes
  • limit - Results per page
  • offset - Pagination offset

Endpoint: GET /executions/search

Query Parameters:

  • filter - General text search
  • pipeline - Filter by pipeline ID
  • status - Filter by status (running, completed, failed)
  • created_after - Filter by creation date
  • created_before - Filter by creation date
  • limit - Results per page
  • offset - Pagination offset

Search Filesets

Endpoint: GET /filesets/search

Query Parameters:

  • filter - General text search
  • sample - Filter by sample ID
  • has_data - Filter filesets with/without data
  • limit - Results per page
  • offset - Pagination offset

Export Endpoints

Export Annotation Template

Export Excel template for bulk sample/data annotation.

Endpoint: GET /annotation/<type>

Path Parameters:

  • type - Template type (sample, data)

Example:

curl -H "Authorization: Bearer <token>" \
  "https://api.flow.bio/annotation/sample" \
  -o sample_annotation_template.xlsx

Response: Excel file with annotation template

Pipeline & Execution Management

List Pipelines

Get available pipeline categories and pipelines.

Endpoint: GET /pipelines

Response:

{
  "categories": [
    {
      "id": 1,
      "name": "RNA Analysis",
      "pipelines": [
        {
          "id": 1,
          "name": "RNA-seq",
          "description": "Quantify gene expression from RNA sequencing",
          "versions": [
            {"id": 10, "version": "3.14.0", "is_latest": true}
          ]
        }
      ]
    }
  ]
}

Get Pipeline Details

Endpoint: GET /pipelines/<pipeline_id>

Response:

{
  "id": 1,
  "name": "RNA-seq",
  "description": "Quantify gene expression from RNA sequencing",
  "category": "RNA Analysis",
  "upstream_pipelines": [],
  "versions": [
    {
      "id": 10,
      "version": "3.14.0",
      "is_latest": true,
      "parameters": []
    }
  ]
}

Get Pipeline Version

Endpoint: GET /pipelines/versions/<version_id>

Response:

{
  "id": 10,
  "pipeline": "RNA-seq",
  "version": "3.14.0",
  "is_latest": true,
  "parameters": [
    {
      "name": "strandedness",
      "type": "choice",
      "choices": ["auto", "forward", "reverse", "unstranded"],
      "default": "auto",
      "description": "Library strandedness"
    }
  ]
}

Run Pipeline

Endpoint: POST /pipelines/versions/<version_id>/run

Request Body:

{
  "name": "My RNA-seq run",
  "samples": [123, 124, 125],
  "filesets": [],
  "parameters": {
    "strandedness": "reverse",
    "aligner": "star"
  }
}

Response:

{
  "id": 456,
  "name": "My RNA-seq run",
  "status": "pending",
  "created": "2024-01-10T10:00:00Z"
}

Get Execution Details

Endpoint: GET /executions/<execution_id>

Response:

{
  "id": 456,
  "name": "My RNA-seq run",
  "status": "running",
  "progress": 45,
  "pipeline": "RNA-seq",
  "pipeline_version": "3.14.0",
  "created": "2024-01-10T10:00:00Z",
  "started": "2024-01-10T10:05:00Z",
  "logs": [
    {
      "timestamp": "2024-01-10T10:05:00Z",
      "process": "FASTQC",
      "message": "Running quality control"
    }
  ],
  "process_executions": [
    {
      "process": "FASTQC",
      "status": "completed",
      "duration": 300
    }
  ]
}

Cancel Execution

Endpoint: POST /executions/<execution_id>/cancel

Response:

{
  "success": true,
  "message": "Execution cancellation requested"
}

List User Executions

Endpoint: GET /executions/owned

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset
  • status - Filter by status
  • pipeline - Filter by pipeline ID

List Shared Executions

Endpoint: GET /executions/shared

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset

Share Execution

Endpoint: POST /executions/<execution_id>/share

Request Body:

{
  "users": ["user1", "user2"],
  "groups": ["research-lab"],
  "permission": 1
}

Transfer Execution Ownership

Endpoint: POST /executions/<execution_id>/transfer

Request Body:

{
  "user": "new_owner_username"
}

Delete Execution

Endpoint: POST /executions/<execution_id>/delete

Batch Delete Executions

Endpoint: POST /executions/delete

Request Body:

{
  "ids": [456, 457, 458]
}

Get Execution Queue Status

Endpoint: GET /queue

Response:

{
  "pending": 5,
  "running": 3,
  "completed_today": 25,
  "failed_today": 2,
  "queue": [
    {
      "id": 456,
      "name": "RNA-seq run",
      "status": "running",
      "position": 1,
      "submitted": "2024-01-10T10:00:00Z"
    }
  ]
}

Sample & Project Management

List Owned Samples

Endpoint: GET /samples/owned

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset
  • filter - Text search
  • organism - Filter by organism

Response:

{
  "count": 150,
  "page": 1,
  "samples": [
    {
      "id": 123,
      "name": "Sample-001",
      "organism": "human",
      "sample_type": "RNA",
      "created": "2024-01-10T10:00:00Z",
      "project": {
        "id": 10,
        "name": "RNA-seq Project"
      }
    }
  ]
}

List Shared Samples

Endpoint: GET /samples/shared

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset

Get Sample Details

Endpoint: GET /samples/<sample_id>

Response:

{
  "id": 123,
  "name": "Sample-001",
  "organism": "human",
  "sample_type": "RNA",
  "condition": "Control",
  "replicate_group": "Group A",
  "project": {
    "id": 10,
    "name": "RNA-seq Project"
  },
  "metadata": {
    "treatment": "none",
    "timepoint": "0h"
  },
  "permissions": {
    "can_edit": true,
    "can_share": true,
    "can_delete": true
  }
}

Get Sample Data

Endpoint: GET /samples/<sample_id>/data

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset

Get Sample Executions

Endpoint: GET /samples/<sample_id>/executions

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset

Share Sample

Endpoint: POST /samples/<sample_id>/share

Request Body:

{
  "users": ["user1", "user2"],
  "groups": ["research-lab"],
  "permission": 1
}

Transfer Sample Ownership

Endpoint: POST /samples/<sample_id>/transfer

Request Body:

{
  "user": "new_owner_username"
}

Delete Sample

Endpoint: POST /samples/<sample_id>/delete

Batch Delete Samples

Endpoint: POST /samples/delete

Request Body:

{
  "ids": [123, 124, 125]
}

List Projects

Endpoint: GET /projects

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset

List Owned Projects

Endpoint: GET /projects/owned

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset
  • filter - Text search

List Shared Projects

Endpoint: GET /projects/shared

List Public Projects

Endpoint: GET /projects/public

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset
  • organism - Filter by organism

Create Project

Endpoint: POST /projects/new

Request Body:

{
  "name": "New RNA-seq Project",
  "description": "Description of the project",
  "organism": "human",
  "is_public": false
}

Get Project Details

Endpoint: GET /projects/<project_id>

Response:

{
  "id": 10,
  "name": "RNA-seq Project",
  "description": "Gene expression analysis",
  "organism": "human",
  "is_public": false,
  "created": "2024-01-01T10:00:00Z",
  "sample_count": 25,
  "owner": {
    "id": 1,
    "username": "researcher"
  }
}

Get Project Samples

Endpoint: GET /projects/<project_id>/samples

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset

Get Project Executions

Endpoint: GET /projects/<project_id>/executions

Get Project Data

Endpoint: GET /projects/<project_id>/data

Update Project Metadata

Endpoint: POST /projects/<project_id>/metadata

Request Body:

{
  "samples": [
    {
      "id": 123,
      "metadata": {
        "treatment": "drug_A",
        "concentration": "10uM"
      }
    },
    {
      "id": 124,
      "metadata": {
        "treatment": "control",
        "concentration": "0uM"
      }
    }
  ]
}

Share Project

Endpoint: POST /projects/<project_id>/share

Request Body:

{
  "users": ["user1"],
  "groups": ["lab-group"],
  "permission": 1
}

Transfer Project Ownership

Endpoint: POST /projects/<project_id>/transfer

Request Body:

{
  "user": "new_owner_username"
}

Delete Project

Endpoint: POST /projects/<project_id>/delete

Sample Sources

Endpoint: GET /samples/sources

Response:

{
  "sources": [
    {"id": 1, "name": "Cell Line"},
    {"id": 2, "name": "Tissue"},
    {"id": 3, "name": "Blood"}
  ]
}

Purification Targets

Endpoint: GET /samples/purification_targets

Response:

{
  "targets": [
    {"id": 1, "name": "Total RNA"},
    {"id": 2, "name": "mRNA"},
    {"id": 3, "name": "Genomic DNA"}
  ]
}

Sample Types Management

Endpoint: GET /samples/types

Endpoint: POST /samples/types/create

Endpoint: POST /samples/types/<type_id>/edit

Endpoint: POST /samples/types/<type_id>/delete

Analytics & Monitoring

Get Usage Analytics

Retrieve platform usage statistics for the authenticated user.

Endpoint: GET /analytics

Response:

{
  "user_stats": {
    "total_samples": 150,
    "total_projects": 12,
    "total_executions": 45,
    "total_data_gb": 523.4,
    "executions_last_30_days": 15,
    "data_uploaded_last_30_days_gb": 102.3
  },
  "group_stats": {
    "research-lab": {
      "total_samples": 450,
      "total_executions": 120,
      "active_users": 8
    }
  },
  "recent_activity": [
    {
      "timestamp": "2024-01-10T10:00:00Z",
      "action": "execution_completed",
      "details": "RNA-seq pipeline completed successfully"
    }
  ]
}

Daily Active Users (Admin Only)

Get daily active user statistics.

Endpoint: GET /dau

Headers:

Authorization: Bearer <admin_token>

Response:

{
  "date": "2024-01-10",
  "daily_active_users": 45,
  "weekly_active_users": 120,
  "monthly_active_users": 350,
  "new_users_today": 3,
  "trends": {
    "dau_change_percent": 5.2,
    "wau_change_percent": 3.8,
    "mau_change_percent": 2.1
  }
}

Health Check

Simple health check endpoint.

Endpoint: GET /ping

Response:

pong

Full Health Status

Comprehensive health status including all services.

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-10T10:00:00Z",
  "version": "1.0.0",
  "services": {
    "database": {
      "status": "healthy",
      "latency_ms": 2.5
    },
    "rabbitmq": {
      "status": "healthy",
      "queue_depth": 15
    },
    "storage": {
      "status": "healthy",
      "available_gb": 500
    },
    "celery": {
      "status": "healthy",
      "active_workers": 8
    }
  }
}

PEKA App Endpoints

The PEKA (Positionally Enriched k-mer Analysis) app provides specialized bioinformatics endpoints for RNA-binding protein analysis.

List PEKA Entities

Endpoint: GET /peka/entities/

Query Parameters:

  • limit - Results per page
  • offset - Pagination offset

Response:

{
  "count": 50,
  "results": [
    {
      "id": 1,
      "name": "HuR",
      "type": "RBP",
      "species": "human"
    }
  ]
}

Get RNA Binding Protein Data

Endpoint: GET /peka/rbp

Query Parameters:

  • protein - RBP name or ID
  • species - Species filter

Response:

{
  "rbp": {
    "name": "HuR",
    "gene": "ELAVL1",
    "species": "human",
    "binding_sites": 1250,
    "known_motifs": ["UUUUUUU", "AUUUA"]
  }
}

Get Motif Data

Endpoint: GET /peka/motif

Query Parameters:

  • motif - Motif sequence
  • rbp - Associated RBP
  • pvalue - P-value threshold

Response:

{
  "motif": "UUUUUUU",
  "length": 7,
  "rbps": ["HuR", "TTP"],
  "enrichment_score": 3.45,
  "pvalue": 0.001
}

Get Motif Lines

Endpoint: GET /peka/motif/lines

Query Parameters:

  • dataset - Dataset ID
  • region - Genomic region
  • limit - Results per page

Response:

{
  "lines": [
    {
      "chromosome": "chr1",
      "start": 100000,
      "end": 100007,
      "motif": "UUUUUUU",
      "score": 0.95,
      "strand": "+"
    }
  ]
}

Error Responses

REST API errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid file format",
    "details": {
      "field": "file",
      "expected": ["fastq", "fastq.gz"],
      "received": "txt"
    }
  }
}

Common HTTP status codes:

  • 200 OK - Successful request
  • 201 Created - Resource created
  • 204 No Content - Successful request with no response body
  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict
  • 413 Payload Too Large - File too large
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

File Size Limits

  • Single file upload: 50GB maximum
  • Chunk size: 10MB recommended
  • Bulk download: 100GB maximum
  • Annotation template: 10MB maximum

CORS Configuration

The API supports CORS for browser-based applications:

Access-Control-Allow-Origin: https://app.flow.bio
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

For development, additional origins may be allowed.

Next Steps

Previous
Python CLI Commands
Next
GraphQL API