Seats Aero

Search award flight availability across 24 mileage programs, including business and first class, with detailed route and booking info via seats.aero API.

Security Scan

The skill's instructions match an award-flight lookup purpose, but the package is incomplete (references helper scripts and docs that are not included) and it instructs the agent to collect and retain an API key in conversation context without clear secret-handling guidance.

Purpose & Capability

SKILL.md clearly describes a seats.aero partner API client for searching award availability — that aligns with the skill name. The package metadata lacks a description, but the runtime instructions match the advertised purpose. Minor mismatch: SKILL.md references helper code (scripts/seats_api.py) and a reference file (references/api-spec.md) that are not present in the bundle, suggesting incomplete packaging or expectation of external code.

Instruction Scope

Instructions are narrowly scoped to calling seats.aero partner endpoints (search, availability, routes, trips) and prompt the user for an API key. Concerns: (1) the skill directs storing the API key in conversation context for subsequent requests — this can lead to the key persisting in chat logs unless the platform provides secure secret handling; (2) the instructions reference local helper scripts and docs that are not included, which could cause the agent to attempt to synthesize or fetch code from elsewhere or mislead the operator about available tooling.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest install risk. Nothing is downloaded or written to disk by an installer in the package itself.

Credentials

The skill requests an API key at runtime (Partner-Authorization header) which is proportionate to the declared API integration. However, the package declares no required environment variables or primary credential despite requiring an API key; combined with the instruction to store keys in conversation context, this raises a modest risk that secrets will be handled insecurely (logged, retained in transcripts, or reused without explicit consent).

Persistence & Privilege

always:false and no config paths or system modifications are requested. The skill can be invoked autonomously (platform default), but it does not ask for elevated persistence or system-level privileges.

What to consider before installing

This skill appears to be a straightforward seats.aero partner API client, but it has gaps you should understand before installing: (1) The SKILL.md references helper scripts (scripts/seats_api.py) and a local API spec (references/api-spec.md) that are not included in the package — ask the publisher whether those files are intentionally omitted or where they are hosted. (2) The skill asks you to provide your seats.aero API key and instructs the agent to 'store the key in conversation context' — verify how the platform stores and protects secrets (do not paste keys into public chat or logs). Prefer using the platform's secure secret/storage mechanism or declaring the key as a required secret in the skill manifest. (3) Confirm the exact endpoints and booking links returned by the API before following any links. If you proceed, supply the API key only after confirming secure handling, and request the missing helper code or implementation details from the publisher. If the publisher cannot justify the missing files or secret-handling approach, treat the skill as incomplete and avoid sharing credentials.

Seats.aero Award Flight Search

Search award flight availability across 24 mileage programs using the seats.aero partner API.

Setup

Before searching, you need a seats.aero API key:

1. If the user hasn't provided an API key, prompt them:
   • "Please provide your seats.aero API key. You can get one at https://seats.aero/partner"
2. Store the key in conversation context for subsequent requests
3. All requests require the header: Partner-Authorization: Bearer {api_key}

Core Capabilities

1. Search Routes (/search)

Search cached availability across all mileage programs for a specific origin-destination pair.

2. Bulk Availability (/availability)

Explore all availability from a single mileage program, optionally filtered by region.

3. Route Discovery (/routes)

Get all routes monitored for a specific mileage program.

4. Trip Details (/trips/{id})

Get detailed flight segments and booking links for a specific availability.

Quick Reference

Item	Value
Base URL	https://seats.aero/partnerapi/
Auth Header	Partner-Authorization: Bearer {key}
Date Format	YYYY-MM-DD

Cabin Codes

• Y = Economy
• W = Premium Economy
• J = Business
• F = First

Regions

North America, South America, Europe, Africa, Middle East, Asia, Oceania

Supported Programs

aeroplan, alaska, american, aeromexico, azul, copa, delta, emirates,
ethiopian, etihad, finnair, flyingblue, gol, jetblue, lufthansa,
qantas, qatar, sas, saudia, singapore, turkish, united,
virginatlantic, virginaustralia

Common Workflows

Find availability on a specific route

User: "Find business class SFO to Tokyo next month"

1. Use /search endpoint with:
   • origin_airport=SFO
   • destination_airport=NRT,HND (both Tokyo airports)
   • cabin=J
   • start_date and end_date for the date range

Explore program availability

User: "What United awards are available from Europe?"

1. Use /availability endpoint with:
   • source=united
   • origin_region=Europe

Get booking details

User: "Show me details for that flight"

1. Use /trips/{id} with the availability ID from previous search
2. Response includes flight segments, times, and booking links

Check what routes a program covers

User: "What routes does Aeroplan monitor?"

1. Use /routes endpoint with source=aeroplan

API Parameters Quick Guide

/search

Parameter	Required	Description
origin_airport	Yes	3-letter IATA code
destination_airport	Yes	3-letter IATA code(s), comma-separated
cabin	No	Y, W, J, or F (comma-separated for multiple)
start_date	No	YYYY-MM-DD
end_date	No	YYYY-MM-DD
sources	No	Program name(s), comma-separated
only_direct	No	true/false
take	No	Results per page (default 100)
cursor	No	Pagination cursor

/availability

Parameter	Required	Description
source	Yes	Single program name
cabin	No	Single cabin code
origin_region	No	Filter by origin region
destination_region	No	Filter by destination region
start_date	No	YYYY-MM-DD
end_date	No	YYYY-MM-DD
take	No	Results per page

Script Usage

For complex or repeated searches, use the Python helper:

from scripts.seats_api import search_availability, format_results

results = search_availability(
    api_key="your_key",
    origin="SFO",
    destination="NRT",
    start_date="2024-03-01",
    end_date="2024-03-31",
    cabins="J,F"
)
print(format_results(results["data"], cabin="J"))

See scripts/seats_api.py for full API client implementation.

Response Handling

Availability Object Fields

• ID - Use for /trips/{id} lookup
• Route - Origin-Destination pair
• Date - Flight date
• YAvailable, WAvailable, JAvailable, FAvailable - Boolean availability
• YMileageCost, etc. - Points required per cabin
• YDirects, etc. - Number of direct flights available
• Source - Program name
• ComputedLastSeen - Data freshness timestamp

Error Handling

• 401: Invalid or missing API key
• 429: Rate limited, wait and retry
• 404: No results or invalid availability ID

Tips

1. Date ranges: Keep to 30-60 days for faster results
2. Multiple cabins: Search J,F together for premium options
3. Direct flights: Use only_direct=true to filter connections
4. Pagination: Use cursor from response for more results
5. Data freshness: Check ComputedLastSeen - older data may be stale

Reference Documentation

For complete API specification including all fields and response schemas, see references/api-spec.md.