API Reference

The Cypher AI REST API is intended for teams that want to integrate protocol creation, experiment data retrieval, or agent task execution into an existing analysis pipeline or lab automation workflow. Base URL: https://api.cypherbio.org/v1

Authentication

All API requests require a Bearer token in the Authorization header:

HEADER Authorization Required for all requests 
Authorization: Bearer <your-api-key>

Protocols

POST /protocols Create a new protocol

Creates a new protocol from a name and ordered step list. Returns the protocol object with a generated id.

Request body

{
  "name": "Western Blot — standard",
  "description": "SDS-PAGE western blot for protein detection",
  "steps": [
    {
      "order": 1,
      "name": "Sample Prep",
      "duration_min": 30,
      "parameters": { "buffer": "RIPA", "temperature_c": 4 }
    },
    {
      "order": 2,
      "name": "Gel Electrophoresis",
      "duration_min": 90,
      "parameters": { "gel_percent": 12, "voltage_v": 120 }
    }
  ]
}

Response 201 Created

{
  "id": "prot_01HX8TZQAB3NKFV9",
  "name": "Western Blot — standard",
  "version": "1.0",
  "created_at": "2025-11-14T09:22:31Z",
  "step_count": 2
}

Experiments

GET /experiments/{id} Fetch experiment details and results

Returns the full experiment record including protocol reference, run parameters, step logs, and linked instrument data.

Path parameter

id  string  required  Experiment ID (exp_...)

Response 200 OK

{
  "id": "exp_01HX9MZPAB2NKFV7",
  "name": "Western Blot Optimization Run 3",
  "protocol_id": "prot_01HX8TZQAB3NKFV9",
  "protocol_version": "1.3",
  "status": "in_progress",
  "steps_completed": 3,
  "steps_total": 5,
  "started_at": "2025-11-14T08:00:00Z",
  "instrument_data": [
    { "instrument": "plate_reader", "file": "pr_20251114_run3.csv" }
  ]
}

AI Agent

POST /agent/run Submit a task prompt to the AI agent

The agent writes analysis code, executes it in a sandboxed environment, and returns the result. Generated tools are automatically saved to your team library.

Request body

{
  "prompt": "Calculate fold-change for conditions A vs B from plate_reader_output.csv",
  "context_id": "exp_01HX9MZPAB2NKFV7",
  "output_format": "dataframe"
}

Response 200 OK

{
  "task_id": "task_01HXBQZRAM5NKFV2",
  "status": "complete",
  "tool_name": "calculate_fold_change",
  "tool_file": "analysis/fold_change_AB.py",
  "added_to_library": true,
  "result_summary": "Fold-change range: 1.2x – 3.8x across 24 wells"
}

Rate limits

During early access, all API tiers operate under the following limits. These will be adjusted based on usage patterns as we move toward general availability:

  • Protocol creation: 100 requests / hour
  • Experiment reads: 1,000 requests / hour
  • Agent tasks: 50 tasks / hour — agent execution runs in a sandboxed container and is resource-bound per task

Every response includes standard rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. If you need higher limits for a specific integration, contact [email protected].