# 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 /health
- GET /paths/deltas
- GET /paths/{pathId}/delta
- GET /entities
- GET /entities/batch
- GET /entities/{entityId}
- GET /api/admin/status
- GET /api/runtime/status
- POST /api/obelisk-verify
- GET /verified-paths
- GET /verified-paths/{pathId}
- GET /evidence
- POST /evidence/submit
- GET /scoring/entity/{entityId}
- GET /scoring/path/{pathId}
- POST /routes/generate
- POST /receipts/generate
- GET /paths/{pathId}/receipt
- 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

## Admin-gated endpoints
- POST /api/admin/review/{entityId}
- GET /api/admin/log
- GET/POST /api/admin/evidence-queue
- GET /evidence/submissions/{submissionId}/status
- GET/POST /api/errors
- POST /api/subscription/revoke
- GET/POST/DELETE /api/subscribe
- 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

## 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 }.
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, ai_writing, animated, api, apiavailable, audio, avatar, beginner, beginner_to_intermediate, budget, business, cinematic, clip, commercial, commercial_rights, copy, developer, footage, high_quality, 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}, compare: {id, routeConfidence}, diff: { added, removed, shared: [{id: string, name: string, category: string|null, verificationStatus: string}] }, confidenceDelta: number, diffedAt: ISO8601 }
Note: diff items are objects — iterate item.name/item.category, NOT raw strings.

## Agent surfaces
- agents.json: /agents.json
- MCP tools: atlas.search_entities, atlas.get_verified_path, atlas.generate_route, atlas.score_stack, atlas.generate_receipt, atlas.compare_paths, atlas.verify_receipt, atlas.get_runtime_status, atlas.get_route_for_goal

## 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 appropriate for staging or production smoke tests
- Read /release-gate.json before promotion: launchReadyPredicate.rateLimiterConfigured must be true; a fail-open RATE_LIMITER binding is launch-blocking
- Treat mobileParityEvidence.releaseApproved as the semantic mobile gate: structural automation never substitutes for artifact-aligned visual review and founder approval

## Contact
- hello@atlas.vaultsparkstudios.com