# ATLAS
> Verified route layer for the AI ecosystem.

ATLAS maps goals to evidence-backed routes, stacks, receipts, and outcomes for both humans and AI agents.

## Core contract
- Routes beat directories.
- Evidence beats hype.
- Paid placement never affects score.
- No verified path without exclusions.
- No score without freshness.

## Public endpoints
- GET /maintenance/public-status
- GET /health
- GET /ready
- GET /paths/deltas
- GET /paths/{pathId}/delta
- GET /entities
- GET /entities/batch
- GET /entities/{entityId}
- GET /entities/{entityId}/revisions
- GET /api/admin/status
- GET /api/runtime/status
- POST /api/obelisk-verify
- GET /verified-paths
- GET /verified-paths/{pathId}
- GET /verified-paths/{pathId}/evidence-frontier
- GET /evidence
- POST /evidence/submit
- GET /scoring/entity/{entityId}
- GET /scoring/path/{pathId}
- POST /routes/generate
- POST /receipts/generate
- GET /paths/{pathId}/receipt
- POST /mcp
- POST /receipts/verify
- GET/POST /outcomes
- GET /outcomes/aggregate/{pathId}
- GET /outcomes/aggregates
- GET /outcomes/summary
- GET /paths/compare
- GET /terrain/diff
- GET /api/contact/status
- POST /api/contact
- GET /api/popular-goals
- POST /api/subscription/challenge
- POST /api/subscription/verify
- POST /api/waitlist

## Receipt-capability endpoints (no credentials; the opaque receipt id is the capability)
- GET /evidence/submissions/{submissionId}/status
- GET /evidence/submissions/status

## Member endpoints (Authorization: Bearer <subscription session token>)
- POST /api/subscription/revoke
- GET/POST/DELETE /api/subscribe

## Maintenance endpoints (operator only; Cloudflare Worker runtime; Authorization: Bearer <ATLAS maintenance trigger token>)
- POST /maintenance/run
- GET /maintenance/status

## Admin-gated endpoints (X-Obelisk-Session or X-Admin-Token)
- POST /api/admin/review/{entityId}
- GET /api/admin/log
- GET/POST /api/admin/evidence-queue
- GET/POST /api/errors
- GET /api/admin/waitlist/insights

## Machine-readable API spec
- OpenAPI 3.1: /api-schema.json
- Manifest-derived route and smoke contract: /api-contract.json
- Runtime persistence status: /api/runtime/status

## Public terrain statistics
- Human analysis: /stats
- Machine twin: /stats.json
- Discovery bundle receipt: /stats-discovery-receipt.json
- Snapshot receipt: sha256:0c37aa36fbbf946eec8ef41d6adda5ebb0d545ce82cf1b5eaae5fe72de657458
- Computed at: 2026-10-02T00:00:00.000Z
- Scope: precomputed aggregate corpus structure, citation coverage, and evidence age. This is not route verification, a score refresh, usage telemetry, or launch approval.
- Unavailable values remain the string "unavailable" with available:false and a reason; never coerce them to zero.

## Write durability
Every route in /api-contract.json carries a `durability` field (durable-adapter | ephemeral-memory | stateless-derived)
so agents know whether a write survives a restart before making it. Verify live state via /api/runtime/status.

## Route generation (POST /routes/generate · atlas.generate_route)
Body: { goal: string, constraints?: string[], topN?: number, profile?: { experience, timeMinutes, existingTools, privacy, budget: { amount, period }, constraints } }. The response includes an atlas.guide@1.0 tailored instance; it does not inherit catalog verification.
constraints re-rank routes toward the ones that satisfy them; each rankedMatches entry reports constraintsMet/constraintsUnmet.
matchStrength { weakMatch, topScore, strength, advice } flags a weak-relevance match — when weakMatch is true, treat the top route as a guess, not a recommendation, and refine the goal or constraints.
budgetAssessment distinguishes within, over, and unknown cost evidence; unknown never means budget-compatible.
matchEvidence reports semantic evidence, satisfied constraint count, budget evidence status, and exclusion conflicts without requiring prose parsing.
interpretedGoal reports ambiguity, missingDimensions, clarification questions/answerSlots, and recommendedNextAction so an agent can ask before accepting an underspecified route.
decisionTrace binds those inputs to the selected row and alternatives. It is explicitly unsigned selection context, includes a deterministic integrity fingerprint, and points to the authoritative signed receipt/verification endpoints.
Recognized constraint/goal concepts: affordable, ai_image, ai_music, ai_video, ai_voice, animated, api, apiavailable, audio, avatar, beginner, beginner_to_intermediate, budget, business, cinematic, clip, commercial, commercial_rights, copy, developer, footage, illustration, image, music, narration, photo, production, professional, sound, soundtrack, text, trailer, tts, under, video, visual, voice, voiceover, writing.

## Terrain diff (GET /terrain/diff)
Response: { base: {id, routeConfidence: number|null, routeConfidenceWithheld: boolean}, compare: {id, routeConfidence: number|null, routeConfidenceWithheld: boolean}, diff: { added, removed, shared: [{id: string, name: string, category: string|null, verificationStatus: string}] }, confidenceDelta: number|null, confidenceDeltaWithheld: boolean, diffedAt: ISO8601 }
A withheld side publishes routeConfidence: null (no score without freshness); confidenceDelta is then null with confidenceDeltaWithheld: true — never a delta computed from a withheld digit. /paths/compare, /verified-paths and /scoring/path/:id carry the same routeConfidenceWithheld flag beside every nullable routeConfidence.
Note: diff items are objects — iterate item.name/item.category, NOT raw strings.

## Human pages
- / — Verified routes for artificial intelligence (AI) decisions: ATLAS maps a goal to evidence-backed routes through the artificial intelligence (AI) ecosystem. Every score carries a source and a freshness date.
- /routes — All routes: Every published ATLAS route, led by what it gets you: first step, tools, rejected alternatives, and whether its evidence is fresh enough to score.
- /map — Trust Map: Explore the ATLAS trust graph: how tools, evidence, and verified routes connect, with freshness and verification status on every node.
- /radar — Artificial intelligence (AI) Radar: Movement across the tracked artificial intelligence (AI) terrain — what changed, what went stale, and which verified routes it affects.
- /outcomes — Measured outcomes: What actually happened when people walked an ATLAS route: measured completion, contributed outcomes, and the routes whose evidence is drifting.
- /trust — Trust contract and methodology: How an ATLAS score is produced, what freshness blocks, why exclusions are part of a route, and why paid placement can never move a ranking.
- /about — About: Why ATLAS ranks routes instead of listing directories, and the evidence rules that decide what may appear in a verified path.
- /docs — Documentation for humans and agents: Read the ATLAS route contract, the representational state transfer (REST) endpoints, and the Model Context Protocol (MCP) tools agents can call.
- /stats — Terrain statistics: Corpus structure, citation coverage, and evidence age for the ATLAS route terrain, recomputed from source with a signed snapshot receipt.
- /changelog — Terrain log: What changed in ATLAS and its corpus, and when: product releases, human-reviewed claim revisions, evidence checks and verification dates.
- /contact — Contact: Reach the ATLAS team about verified routes, evidence corrections, or agent access.
- /privacy — Privacy policy: What ATLAS collects, what it does not, and how route and receipt data is handled.
- /terms — Terms of service: Terms governing use of the ATLAS website, application programming interface (API), and agent surfaces.
- /ip — Intellectual property and rights: Ownership, third-party boundaries, and permitted use of proprietary ATLAS materials and public information.

## Record permalinks (human page + machine twin, same record)
Index of every route, publishable first: /routes (machine twin /routes.json).
Every verified route and every tracked entity has its own URL. Append .json for the twin:
the twin carries the same freshness decision, the same exclusions, and the same receipt
pointers the page renders. A blocked confidence is serialized as null with an explicit
freshness.decision of "block" — never as a number and never as zero.
- /routes/ai-video-stack-under-50 (/routes/ai-video-stack-under-50.json) — AI Video Stack Under $50
- /routes/ai-image-generation-workflow (/routes/ai-image-generation-workflow.json) — AI Image Generation Workflow
- /routes/ai-music-production-under-50 (/routes/ai-music-production-under-50.json) — AI Music Production Under $50
- /routes/ai-coding-agent-setup (/routes/ai-coding-agent-setup.json) — AI Coding Agent Setup
- /routes/ai-voice-agent-mvp (/routes/ai-voice-agent-mvp.json) — AI Voice Agent MVP
- /routes/ai-research-workflow (/routes/ai-research-workflow.json) — AI Research Workflow
- /routes/ai-content-creation-pipeline (/routes/ai-content-creation-pipeline.json) — AI Content Creation Pipeline
- /routes/ai-presentation-from-brief (/routes/ai-presentation-from-brief.json) — AI Presentation from Brief
- 25 entity records follow the same shape at /entities/{id} and /entities/{id}.json

## Evidence frontier (where the corpus is blank)
- Machine: /evidence-frontier.json
- A ranked list of every published claim with no supporting source, the routes it blocks,
  and the source type that would settle it. Treat any field named in an open slot as
  asserted-without-support, not as decided. Nothing in that file is a claim ATLAS makes;
  it is a list of claims ATLAS has not yet earned.

## Trust contract
- Human: /trust · Machine twin: /trust-contract.json
- These are the rules a claim must satisfy before ATLAS may publish it. They are not a
  verification claim about any route or entity.

## Agent surfaces
- Progressive bootstrap: /agents.bootstrap.json (load before the full manifest for ordinary route work)
- agents.json: /agents.json
- MCP tools: atlas.search_entities, atlas.get_verified_path, atlas.get_evidence_frontier, atlas.generate_route, atlas.score_stack, atlas.generate_receipt, atlas.compare_paths, atlas.verify_receipt, atlas.get_runtime_status, atlas.get_route_for_goal, atlas.record_outcome, atlas.submit_evidence, atlas.get_evidence_status, atlas.get_outcome_record, atlas.get_confidence_delta
- Remote MCP, no install: POST https://atlas-api.founder-d73.workers.dev/mcp with one JSON-RPC 2.0 message (initialize, tools/list, tools/call). Remote tools: atlas.search_entities, atlas.get_verified_path, atlas.get_evidence_frontier, atlas.generate_route, atlas.score_stack, atlas.generate_receipt, atlas.compare_paths, atlas.verify_receipt, atlas.get_runtime_status, atlas.get_route_for_goal. Writes stay on REST.

## Token efficiency tips
- Use ?fields=id,name,confidence to project only needed fields
- Use /entities/batch?ids=a,b,c instead of N separate /entities/:id calls
- Use /paths/deltas?ids=a,b,c instead of N separate /paths/:id/delta calls
- Use atlas.get_route_for_goal (MCP) instead of generate_route plus get_verified_path plus generate_receipt
- Use atlas.get_runtime_status (MCP) or /api/runtime/status before writing mutable data so you know whether writes are durable
- Read /api-contract.json before probing: only cases with productionSafe=true are safe to call against a live origin
- Launch readiness is machine-readable at /release-gate.json; if launchReadyPredicate.rateLimiterConfigured is false, treat write endpoints as unprotected by a rate limiter

## Contact
- hello@atlasaipaths.com (human mailbox; the /contact form is the reliable channel)