Public API

Local Compose base URL: http://localhost:8001. Native Python base URL: http://localhost:8000. Intended production API domain: https://api.open-sensations.com; availability depends on deployment.

Anonymous read-only access requires no key. There are no public canonical mutation endpoints. Future API keys, researcher/high-volume tiers and usage accounting are design possibilities; billing is not implemented.

First request

curl http://localhost:8001/v1/sensors/lidar
curl 'http://localhost:8001/v1/sensors?classification=artificial&page_size=5'

import json
from urllib.request import urlopen

with urlopen("http://localhost:8001/v1/sensors/lidar", timeout=10) as response:
    print(json.load(response)["data"]["name"])

const response = await fetch('http://localhost:8001/v1/sensors/lidar');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log((await response.json()).data.name);

Endpoints

GET /health checks database connectivity and imported-dataset readiness. GET /v1/meta exposes separate software, dataset and schema versions, source commit, content hash, import time and counts.

Every collection supports GET /v1/{collection} and GET /v1/{collection}/{slug}:

modalities, stimuli, sensors, receptors, transductions, signals, processing, sensations, thresholds, ranges, contexts, capabilities, limitations, failure-modes, percepts, sources, evidence, contributors, reviews.

Relationship endpoints return the same paginated entity envelope:

/v1/sensors/{slug}/stimuli
/v1/sensors/{slug}/sensations
/v1/sensors/{slug}/processing
/v1/sensors/{slug}/limitations
/v1/sensors/{slug}/failure-modes
/v1/sensations/{slug}/thresholds
/v1/sensations/{slug}/candidate-percepts
/v1/stimuli/{slug}/sensors

Query parameters

Parameter	Behavior
search	Case-insensitive substring of name, slug or definition; maximum 200 characters
classification	biological, artificial, hybrid, conceptual
modality	Associated modality slug; `vision` also expands to `machine-vision` for discovery
capability	Associated capability slug, such as `localize`
category	Stimulus/category slug, such as `electromagnetic`
sensor	Records connected from the named sensor, useful for limitations/failure modes
evidence_status	Records with at least one claim carrying that status
sort	name, -name, slug, -slug; stable ID is the tie-breaker
page	1-based, defaults to 1, maximum 10000
page_size	1–100, defaults to 24

Unknown parameters and invalid values produce 422. Search wildcards % and _ are literal. Filters combine with AND. Empty results return 200 with data: []; an unknown detail/relationship parent returns 404. Unknown filter slugs yield an empty list. Do not infer absent records mean an absent biological capability.

Response shape

{
  "meta": {
    "api_version": "v1",
    "software_version": "0.1.0",
    "dataset_version": "0.1.0",
    "schema_version": "0.1.0",
    "source_git_commit": "unknown",
    "content_hash": "release-specific SHA-256",
    "imported_at": "import-specific timestamp"
  },
  "data": [],
  "pagination": {"page": 1, "page_size": 24, "total": 0, "pages": 0}
}

Detail data is an entity object and has no pagination. Entities include strict typed fields, evidence claims, relationships and scoped unknowns. Null is not zero. Inspect individual claim status and source links rather than treating an entire record as verified.

Structured errors have api_version and error: {code, message, request_id}. Typical status codes are 404, 405, 422, 500 and 503. Request IDs also appear in X-Request-ID. Unexpected errors never return stack traces or database credentials. Health is a small operational response rather than an entity envelope.

Reference and exports

Interactive Swagger UI, ReDoc, and OpenAPI JSON are generated from route and response contracts. Dataset downloads provide YAML, JSON and CSV. CSV retains nested structures in record_json; API clients should prefer JSON. Graph concepts and synchronization are documented separately.

Fair use and stability

The application bounds pagination and query length. It does not implement distributed rate limiting or usage accounting. A public operator must configure edge limits appropriate to capacity and publish its policy; clients should cache by dataset version/content hash, download bulk data instead of scraping, and back off on 429/503. No uptime or unlimited-throughput promise is made. API version and dataset/schema versions are separate; see the stability policy before depending on this pre-1.0 contract.