AIND Metadata Portal

metadata visualizations

Validation endpoints

The metadata portal hosts validation endpoints for the latest aind-data-schema release. You can hit these endpoints with:

Example

import requests
import json

with open("metadata.json", "r") as f:
    metadata = json.load(f)

response = requests.post(
    "https://metadata-portal.allenneuraldynamics-test.org/validate/metadata", 
    json=metadata
)

if response.status_code == 200:
    print("✅ Validation passed!")
else:
    print(f"❌ Validation failed: {response.json()}")

Files endpoint

You can also post a dictionary containing only the core files (i.e. not generated from a Metadata object). This can be useful when testing whether your metadata are valid prior to triggering the aind-data-transfer-service on a data asset.

import requests
import json

core_files = ["data_description", "acquisition", "instrument", "procedures", "subject"]

metadata = {}
for core_file in core_files:
    with open(f"{core_file}.json", "r") as f:
        metadata[core_file] = json.load(f)

response = requests.post(
    "https://metadata-portal.allenneuraldynamics-test.org/validate/files", 
    json=metadata
)

if response.status_code == 200:
    print("✅ Validation passed!")
else:
    print(f"❌ Validation failed: {response.json()}")

Individual validation endpoints

• /validate/subject - Subject metadata
• /validate/data_description - Data description metadata
• /validate/acquisition - Acquisition metadata
• /validate/instrument - Instrument metadata
• /validate/procedures - Procedures metadata
• /validate/processing - Processing metadata
• /validate/quality_control - Quality control metadata
• /validate/model - Model metadata

Example usage: requests.post("https://metadata-portal.allenneuraldynamics-test.org/validate/subject", json=subject_data)

Gather endpoint

Gathers and validates metadata from the metadata service for a given subject.

• GET /gather?subject_id=<id>&project_name=<name> — required parameters
• Optional: metadata_service_url, modalities (comma-separated), tags (comma-separated), group, restrictions, data_summary, acquisition_start_time

response = requests.get(
    "https://metadata-portal.allenneuraldynamics-test.org/gather",
    params={"subject_id": "123456", "project_name": "MyProject"},
)
print(response.json())

Query endpoints

• GET /upgrade-query — Build a query using the LLM query builder. Pass query string parameters as needed.
• POST /retrieve-records — Run a query. Accepts a JSON object as the request body.

Optional query parameters for /retrieve-records:

• names_only=true — return only asset names
• limit=<int> — limit number of results (default 0 = no limit)
• projection=<json> — JSON object specifying which fields to include/exclude (e.g. {"subject.subject_id": 1})

response = requests.post(
    "https://metadata-portal.allenneuraldynamics-test.org/retrieve-records",
    params={"limit": 10, "projection": '{"subject.subject_id": 1, "name": 1}'},
    json={"subject.subject_id": "123456"},
)
print(response.json())

Contributions endpoints

Stores and retrieves CRediT authorship contributions for a project, versioned via git.

Endpoint	Description
GET /contributions/get?project=<name>	Latest contribution data (JSON by default)
GET /contributions/get?project=<name>&format=yaml	Latest contribution data as YAML
GET /contributions/get?project=<name>&commit=<hash>	Contribution data at a specific commit
GET /contributions/get?project=<name>&history=true	List of all commits for the project
POST /contributions/post?project=<name>[&message=<msg>]	Store a new version; body is JSON or YAML

The ?history=true response is a list of commits, newest first, each with commit (SHA), timestamp (ISO-8601), and message. Use the returned hashes with ?commit=<hash> to retrieve any historical version.

Pull the seeded IBL example to see a complete payload with all fields:

import requests, json

r = requests.get(
    "https://metadata-portal.allenneuraldynamics-test.org/contributions/get",
    params={"project": "ibl-2025"},
)
print(json.dumps(r.json(), indent=2))

Fetch the full history for a project and then retrieve a specific past version:

import requests, json

history = requests.get(
    "https://metadata-portal.allenneuraldynamics-test.org/contributions/get",
    params={"project": "MyProject", "history": "true"},
).json()

oldest_commit = history[-1]["commit"]
old_version = requests.get(
    "https://metadata-portal.allenneuraldynamics-test.org/contributions/get",
    params={"project": "MyProject", "commit": oldest_commit},
).json()

Usage

Clone the repository and cd into the folder

Create a virtual environment and install the package, then launch panel.

python -m venv .venv
source .venv/bin/activate (or .venv/bin/Scripts/activate on Windows)
pip install -e .
panel serve ./src/aind_metadata_viz/app.py --show --autoreload

To launch the query and view apps replace the app.py with the appropriate launcher.

CI/CD

There is a Dockerfile which includes the entrypoint to launch the app.

Local dev

1. Build the Docker image locally and run a Docker container:

docker build -t aind-metadata-viz .
docker run -e ALLOW_WEBSOCKET_ORIGIN=localhost:8000 -p 8000:8000 aind-metadata-viz

2. Navigate to 'localhost:8000` to view the app.

AWS

1. On pushes to the dev or main branch, a GitHub Action will run to publish a Docker image to ghcr.io/allenneuraldynamics/aind-metadata-viz:dev or ghcr.io/allenneuraldynamics/aind-metadata-viz:latest.
2. The image can be used by a ECS Service in AWS to run a task container. Application Load Balancer can be used to serve the container from ECS. Please note that the task must be configured with the correct env variables (e.g. API_GATEWAY_HOST, ALLOW_WEBSOCKET_ORIGIN).