# Sorted Travel — Developers

> Developer portal for Sorted Travel: free-tier zero-auth REST, MCP connector, self-serve API keys, official SDKs, and sandbox discovery.

## Developer resources (search keywords)

- Sorted Travel API documentation: [Developers HTML](https://sorted.travel/developers)
- Sorted Travel OpenAPI spec: [OpenAPI 3.1](https://sorted.travel/openapi.json)
- Sorted Travel MCP server: [MCP connector](https://sorted.travel/mcp)
- Sorted Travel SDK documentation: [sdks.md](https://sorted.travel/sdks.md)
- Sorted Travel auth docs: [auth.md](https://sorted.travel/auth.md)

## Quick start

Free tier. No signup. Destination ranking, facts, weather, and visa tools need no API key.

1. Liveness: [GET /api/v1/status](https://sorted.travel/api/v1/status) — no `Authorization` header.
2. Optional sandbox key: [POST /api/v1/api-keys](https://sorted.travel/api/v1/api-keys).
3. MCP tools: connect [https://sorted.travel/mcp](https://sorted.travel/mcp).
4. Structured homepage: [/?mode=agent](https://sorted.travel/?mode=agent) (`Accept: application/json` for JSON).

## REST API

- [OpenAPI 3.1](https://sorted.travel/openapi.json): machine-readable contract
- [GET /api/v1/status](https://sorted.travel/api/v1/status): liveness and rate-limit headers
- [GET /api/v1/destinations](https://sorted.travel/api/v1/destinations): cursor-paginated destination catalog
- [POST /api/v1/jobs](https://sorted.travel/api/v1/jobs): async work (`202 Accepted`, poll `GET /api/v1/jobs/{job_id}`)
- [Sandbox discovery](https://sorted.travel/sandbox): test environment entry points

## MCP and agents

- [MCP connector](https://sorted.travel/mcp): Streamable HTTP at `/mcp` (no `/v1/` prefix). Contract version `1.2.0` in `API-Version` header.
- [MCP server card](https://sorted.travel/.well-known/mcp/server-card.json): connection metadata and MCP Apps UI resources
- [NLWeb /ask](https://sorted.travel/ask): NLWeb v0.55 natural-language endpoint for public pages and destination lookup (`POST` JSON with `query.text`; `prefer.streaming: true` for SSE)
- [Schema Map](https://sorted.travel/schemamap.xml): NLWeb Schema Feeds index advertised from [robots.txt](https://sorted.travel/robots.txt)
- [Destinations JSONL](https://sorted.travel/feeds/destinations.jsonl): schema.org TouristDestination catalog
- [Site JSONL](https://sorted.travel/feeds/site.jsonl): Organization, WebSite, FAQ, and developer schema.org entities
- [A2A agent card](https://sorted.travel/.well-known/agent-card.json): JSON-RPC at `https://sorted.travel/a2a`
- [ARD catalog](https://sorted.travel/.well-known/ard.json): machine-readable tool list
- [Agent Skills index](https://sorted.travel/.well-known/agent-skills/index.json): onboarding skill
- [Agent Plugin package](https://github.com/a-l-e-x-k/sorted-travel-sdk/blob/main/plugin.json): `plugin.json`, `skills/`, and `mcp.json` in the public SDK repo
- [Web Bot Auth directory](https://sorted.travel/.well-known/http-message-signatures-directory): Ed25519 public keys for HTTP Message Signatures (RFC 9421)
- [Smithery listing](https://smithery.ai/servers/sorted-travel/destinations): registry alias `https://mcp.smithery.ai/sorted-travel`

Profile tools (`get_profile_preferences`, `update_profile_preferences`) use OAuth 2.0 scopes `profile.read` and `profile.write`. Destination tools need no token.

## SDKs and auth

- [sdks.md](https://sorted.travel/sdks.md): `pip install sorted-travel`, `npm install sorted-travel`, and CLI
- [auth.md](https://sorted.travel/auth.md): WorkOS agent-auth discovery walkthrough (`agent_auth` block, anonymous identity)
- [oauth-authorization-server](https://sorted.travel/.well-known/oauth-authorization-server): RFC 8414 metadata

## Markdown and HTML

- [Developers.md](https://sorted.travel/developers.md): markdown twin of this portal
- [Developers HTML](https://sorted.travel/developers): human-facing portal page
- [Root llms.txt](https://sorted.travel/llms.txt): full site index
- [API llms.txt](https://sorted.travel/api/llms.txt): REST-only scoped index
- [Discover](https://sorted.travel/discover/llms.txt): scoped index for the destination recommender

## Optional

- [Contact](https://sorted.travel/contact): support@sorted.travel for integration questions