# Promptbox Fly Brain API · documentation v1.4.0

Optional reduced-bandwidth activity protocol: deployed on worker v1.3.0. Inspect `/v1/model.activity_view.formats` for `section_top80_v1` before requesting it. With support, cache `/v1/activity-layout` by layout_id and use `activity_view: "section_top80_v1"`, `top_k: 0` on visible-display steps. The server selects the strongest 80% independently in each section and returns only selected nonzero counts using delta-varint encoding; the client uses a fixed logarithmic 0–500 Hz palette. Omit activity_view when collapsed. Existing inputs/readouts remain compatible with the current worker.

[Exact wire contract, rationale, and server-agent instructions](activity-protocol.md). This supersedes the unactivated v1.8.0 complete-snapshot proposal.

Run images, retinal brightness, or neuron currents through the complete fixed-weight male fruit-fly neural network. Responses report spike counts, firing rates, voltages, population activity, and optional fixed control readouts.

Endpoint: `https://www.promptbox.cn/api/doomfly.php`

Promptbox supplies the service credential automatically. Callers do not send an API key.

## What does it do?

The API simulates all 166,700 retained MaleCNS v1.0 neurons and 25,582,938 directed connections. It accepts visual or direct neural input and returns activity from the whole network. Independent requests begin from the same initial state; optional sessions preserve neural state across a sequence of inputs.

The model uses fixed synaptic weights. It does not learn, understand, or establish natural fly behavior. Biological wiring supplies the network structure, while neural dynamics, visual projection, and control mappings remain modeling assumptions.

## How to use it

Pass the desired route in the `path` query parameter. Use GET for service and model information, POST with JSON to run a simulation step or create a session, and DELETE to release a session.

```sh
curl 'https://www.promptbox.cn/api/doomfly.php?path=/v1/step' \
  -H 'Content-Type: application/json' \
  -d '{"luminance":0.5,"duration_ms":20,"top_k":10}'
```

`luminance` can be one brightness from 0–1 for every retinal cell, or exactly 3,335 values ordered by `/v1/retina`. Alternatively, send `image_base64` containing PNG, JPEG, or WebP bytes encoded as base64; a data URL is accepted. Images are resized to fit 1024 × 1024. URLs are not accepted as image inputs.

Direct stimulation uses decimal-string biological neuron IDs. Find them using `/v1/neurons` or `/v1/retina`, then send:

```json
{
  "stimuli": [{"neuron_id": "NEURON_ID_FROM_CATALOG", "current_mv": 25}],
  "readout_ids": ["NEURON_ID_FROM_CATALOG"],
  "duration_ms": 20,
  "top_k": 100
}
```

`current_mv` ranges from −30 to +30 and is held for the requested interval. Up to 512 distinct neurons may be stimulated per request. Direct stimulation can be combined with visual input. `lamina_bias_mv` can explicitly select a value from 0–12.

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| GET | `/health` | Read readiness, graph size, busy state, and completed calls |
| GET | `/v1/model` | Read the model, limits, graph and kernel hashes, and fixed readouts |
| GET | `/v1/neurons` | Browse neurons; supports `cell_type`, `superclass`, `offset`, and `limit` |
| GET | `/v1/retina` | Read all 3,335 retinal neuron IDs and inferred UV sample coordinates |
| POST | `/v1/step` | Apply an input and advance 0.1–100 simulated milliseconds |
| POST | `/v1/sessions` | Lease the brain with `{"ttl_seconds":900}`; accepted range is 30–900 |
| DELETE | `/v1/sessions/SESSION_ID` | Release a lease and reset its neural state |

## Neural outputs

`total_spikes` and `active_neurons` cover the complete network for the requested interval. `populations` summarizes all neurons by superclass. `top_spikes` contains the highest-spiking cells, controlled by `top_k` (default 100, maximum 1000), and `top_spikes_truncated` reports omitted active cells. `readouts` always includes requested neurons (maximum 256), even when they have no spikes.

Rates are calculated in Hz. Voltages are measured at the end of the interval. `spike_counts_sha256` hashes the full spike-count vector, and the response includes the exact graph hash.

## Independent calls and sessions

Without `session_id`, each valid call starts from the same initial neural state. Repeating the same input produces the same neural result, apart from measured processing time.

For a sequence, create a session and include its `session_id` plus a unique `request_id` in every step:

```json
{"session_id":"SESSION_ID_FROM_CREATE","request_id":"frame-001","luminance":0.5,"duration_ms":20}
```

A session preserves membrane voltages, delayed synaptic events, retinal filtering, and fixed-control smoothing. Only one session can be active at a time. Its fixed deadline is returned as `expires_at`, and it supports up to 512 unique steps. The default lease is 900 seconds (15 minutes) of wall-clock time, including pauses; it is not renewed by requests. Release sessions promptly.

Session creation returns `max_steps`, `steps_used`, and `steps_remaining`. Successful stateful steps include a `session` object with those fields plus `expires_at`. Step 512 succeeds with zero remaining; step 513 returns HTTP 409. Expired leases return HTTP 404. An identical retry still returns its cached result at the step cap, until the lease expires or is released.

The [Fly Brain Lab](https://promptbox.cn/logi/logi_code/fly-brain/) samples up to 512 frames across a video and requests a 15-minute lease. It stops and displays an in-app notice at the step limit or expiry, including while paused (or when a suspended tab resumes). Replay starts a fresh sequence; images and pulses remain independent inputs. Sessions are held in memory and do not survive service restarts.

Retrying an identical session `request_id` returns the original result without running another step. Reusing an ID with different input returns HTTP 409. Invalid input does not advance the simulation.

## Limits and errors

One request computes at a time. The shared rate limit is 120 HTTP requests per minute. Each step may advance 0.1–100 simulated milliseconds. JSON requests are limited to 3 MB, and `image_base64` is limited to 2.8 million characters.

Errors use JSON and the following status codes: 400 invalid request, 404 missing or expired session, 405 unsupported method or path, 409 session or idempotency conflict, 413 oversized body, 422 invalid input, 429 capacity or quota, and 503 temporary service unavailability. A 429 response may include `Retry-After`. Do not poll automatically.

## Scientific context

The simulation retains all MaleCNS v1.0 neurons and connections used by the fixed-weight baseline, including weak and self connections. The integration step is 0.1 ms. Numerical checks verify implementation consistency, not biological accuracy or useful behavior.

Sources: [DOOMFLY](https://github.com/nftechie/doomfly), [model review](https://github.com/nftechie/doomfly/blob/main/docs/doom-neuroscience-review.md), [MaleCNS dataset](https://male-cns.janelia.org/download/), and [neural model reference](https://www.nature.com/articles/s41586-024-07763-9).