REST API Documentation

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer amt_your_api_key_here

There are three permission levels:

Keys are limited by the owner's current role and museum/country assignments. Disabled accounts cannot use keys. Admin and aircraft_admin have full catalog access; managers can edit assigned museums and their exhibit links. Only admin sessions can manage other users. Session writes require CSRF tokens; adding a Bearer header does not bypass CSRF for session-only endpoints.

To get an API key, log in and visit the API Keys page.

Complete route index

Generated from the running application's routes. PUT and PATCH apply partial updates. Session endpoints require login; users may access their own details and keys, while managing other users requires an admin session.

Query and import conventions

Aircraft and museum searches return results, total, page, and pages. per_page defaults to RESULTS_PER_PAGE (20) and is capped at 100; fetch subsequent pages to retrieve the full catalog. sort_by names a supported field and sort_dir is asc or desc.

Detail requests include all exhibits by default. Add visible_only=true to show only on_display exhibits, as the public UI does. Other valid statuses are in_storage and under_restoration. Statistics count only on_display exhibit links.

GET /api/v1/museums/globe returns coordinates and on-display aircraft counts. GET /api/v1/museums/nearby takes location, optional region, and limit (default 10, maximum 50); museums without coordinates are listed separately. GET /api/v1/museums/nearest takes lat and lon or location, optional radius in miles, and limit (default 10, maximum 50). GET /api/v1/contributors lists contributor rankings.

Aircraft and museum bulk_import endpoints require admin-level data access. POST a multipart file or a JSON object with format (csv, json, or auto), data (text), and dry_run (boolean). The limits are 5,000 rows, the configured request-size limit (1 MiB by default), and BULK_IMPORT_RATE_LIMIT (200 per hour by default). Validation includes duplicates already in the database; writes are atomic. Aircraft rows may supply museum_id or museum_name to create an exhibit link.

Templates require name, manufacturer, and model; optional type fields and aliases prefill new aircraft without changing existing airframes. API key creation accepts label and permissions. POST /api/v1/keys also accepts expires_in_days; raw keys are returned once. JSON flags such as is_active and dry_run must be booleans, not strings.

Histories, map, and trip planning

GET /api/v1/aircraft/{id}/history lists published milestones; /history/manage requires readwrite access and includes drafts. POST on /history creates a milestone; PUT/PATCH /api/v1/history/{event_id} edits one; DELETE requires admin data access. Entries require a title and source_name or source_url. Optional integer event_year, event_month, event_day preserve date precision; is_approximate and is_published are booleans. Histories belong to the individual aircraft ID and do not change current exhibit assignments.

GET /api/v1/museums/map accepts q, region, country and returns all matching museums in results and no_coordinates, with total and on-display aircraft_count. The museum map supports clusters and area search.

POST /api/v1/trips/plan accepts origin (location text, or latitude and longitude), targets (1–12 objects), radius_miles (1–5000, default 500), max_stops (1–8, default 5), and round_trip (boolean). Targets use kind=airframe plus aircraft_id, or kind=model plus manufacturer and model. The public endpoint requires a CSRF token and is limited to 30 requests per minute. It returns ordered stops, covered targets, unmatched reasons, and straight-line mileage. Suggestions use on_display exhibits only and do not calculate driving time or opening hours. Try the trip planner.

Endpoints