{
 "openapi": "3.1.0",
 "info": {
  "title": "Rat Processing Unit",
  "version": "1.0.0",
  "description": "Fire 7,126 real recorded rat neurons (Horv\u00e1th et al. 2021, CC-BY) into a simulated rat cortex (Blue Brain SSCx toy circuit, Pokorny 2024, CC BY 4.0). Deterministic and verifiable. Please credit the data when publishing results."
 },
 "servers": [
  {
   "url": "https://ratprocessingunit.com"
  }
 ],
 "paths": {
  "/api/fire": {
   "get": {
    "operationId": "fireNeurons",
    "summary": "Fire real neurons into the rat cortex",
    "parameters": [
     {
      "name": "neurons",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "description": "Comma-separated neuron numbers (0-7125), each once",
       "example": "6107,3409"
      }
     },
     {
      "name": "ms",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 50,
       "maximum": 1000,
       "default": 300
      },
      "description": "Replay length in milliseconds"
     }
    ],
    "responses": {
     "200": {
      "description": "Cortex result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Fire"
        }
       }
      }
     },
     "400": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests (or 402 Payment Required when paid access is on)"
     }
    }
   }
  },
  "/api/neuron/{n}": {
   "get": {
    "operationId": "getNeuron",
    "summary": "A neuron's real traits and links",
    "parameters": [
     {
      "name": "n",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 7125
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Neuron",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Neuron"
        }
       }
      }
     },
     "404": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/neuron/{n}/music": {
   "get": {
    "operationId": "getNeuronMusic",
    "summary": "The neuron's whole recording as one minute of music (WAV)",
    "parameters": [
     {
      "name": "n",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 7125
      }
     }
    ],
    "responses": {
     "200": {
      "description": "WAV audio",
      "content": {
       "audio/wav": {}
      }
     },
     "404": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/neuron-of-the-day": {
   "get": {
    "operationId": "neuronOfTheDay",
    "summary": "Today's featured neuron",
    "responses": {
     "200": {
      "description": "Neuron",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Neuron"
        }
       }
      }
     }
    }
   }
  },
  "/api/top": {
   "get": {
    "operationId": "topResults",
    "summary": "This week's biggest recorded results that re-run identically",
    "responses": {
     "200": {
      "description": "Verified results",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "results": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     }
    }
   },
   "Fire": {
    "type": "object",
    "properties": {
     "neurons": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "ms": {
      "type": "integer"
     },
     "spikes": {
      "type": "integer",
      "description": "Model spikes"
     },
     "spikesByLayer": {
      "type": "object"
     },
     "firstSpikeMs": {
      "type": [
       "number",
       "null"
      ]
     },
     "inputDigest": {
      "type": "string"
     },
     "rasterDigest": {
      "type": "string",
      "description": "Fingerprint: re-run the same neurons and ms to get the same value"
     },
     "credit": {
      "type": "array",
      "items": {
       "type": "object"
      },
      "description": "Renters of the neurons used, if any"
     },
     "cellsThatFired": {
      "type": "integer",
      "description": "How many different model cells fired"
     },
     "spikesInSecondHalf": {
      "type": "integer",
      "description": "Model spikes in the second half of the replay"
     }
    }
   },
   "Neuron": {
    "type": "object",
    "properties": {
     "neuron": {
      "type": "integer"
     },
     "tier": {
      "type": "string"
     },
     "rarityRank": {
      "type": "integer"
     },
     "titles": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "firingStyle": {
      "type": "string"
     },
     "voice": {
      "type": "string"
     },
     "spikeShape": {
      "type": "string"
     },
     "area": {
      "type": "string"
     },
     "layer": {
      "type": "string"
     },
     "rat": {
      "type": "string"
     },
     "firingRateHz": {
      "type": "number"
     },
     "spikesRecorded": {
      "type": "integer"
     },
     "page": {
      "type": "string"
     },
     "image": {
      "type": "string"
     },
     "music": {
      "type": "string"
     },
     "credit": {
      "type": [
       "object",
       "null"
      ]
     }
    }
   }
  }
 }
}