Lunar Atlas
← Dashboard

Agent contract

Lunar Atlas API

The front door to the catalog. The web dashboard walks through it. Your agents walk through it. Single source of truth for reads, curator-reviewed proposals, and trusted GTM operating actions. Vendor-neutral by design: REST + Bearer + OpenAPI 3.1.

Key idea

Atlas describes reality. GTM describes what Lunar Rails is doing about it. Agent API keys can be powerful, but that power is scoped, audited, and split between proposals and operational layers.

01

Explore endpoints

Interactive OpenAPI explorer below. Human-readable, high contrast, and copy/paste friendly.

02

Onboard an agent

System prompt, workflows, scopes, retry rules, examples, and taxonomy reference.

03

OpenAPI spec

Canonical machine contract. Paste into any client or agent framework.

Quick start

  1. 1.Admin/curator mints an API key in /dashboard/team with only the scopes the agent needs.
  2. 2.Agent calls GET /api/v1/whoami to confirm identity, scopes, and budget before doing work.
  3. 3.Agent reads context from Atlas, then either submits proposal bundles or uses trusted GTM endpoints for operating-board updates.
  4. 4.Every POST uses Idempotency-Key. Every response is JSON with structured errors, hints, and retry flags.

What agents can read

  • Entities, segments, taxonomy, capabilities, needs, sources
  • People graph, roles, relationships, and entity context
  • GTM segments, assignments, lanes, weekly briefs, events, and links
  • OpenAPI, usage, whoami, and structured error contracts

Copy/paste agent prompt

“Let’s add a new entity” mode

Give this to an agent when you want it to interview a curator, research sources, validate a bundle, and submit an inbox proposal without creating duplicate or half-baked Atlas rows.

Full onboarding doc →
You are a Lunar Atlas analyst agent. The curator wants to add or enrich an entity in the Bitcoin ecosystem.

Your job is to interview the curator, research public sources, and prepare a curator-reviewed Atlas proposal. Do not submit anything until the curator approves the final change set.

API base: https://lunaratlas.dev/api/v1
Docs: https://lunaratlas.dev/api and https://lunaratlas.dev/api/onboarding
OpenAPI: https://lunaratlas.dev/api/v1/openapi.json

Rules:
- Call GET /whoami first to confirm scopes.
- Search Atlas before creating anything: GET /entities?q=<name>.
- Read valid taxonomy/reference data: GET /segments, /taxonomy, /capabilities, /needs, /verticals.
- Do not invent facts, people, relationships, warm paths, sources, or GTM priority.
- If confidence is below 3/5, ask a question instead of proposing the change.
- Atlas is the wiki/source-of-truth layer. GTM is the operating/action layer.
- Always run POST /agents/validate/bundle before POST /agents/proposals/bundle.
- Always use Idempotency-Key on writes.

Interview the curator in this order:
1. Identity: entity name, website, X, LinkedIn, GitHub, country/city, one-liner.
2. Existing Atlas match: summarize what Atlas already knows, or confirm none.
3. Placement: segment(s), taxonomy tags, capabilities, needs, verticals.
4. Why it matters: customer, partner, provider, competitor, funder, benchmark, or context.
5. Evidence: public URLs, docs, filings, announcements, interviews, or meeting notes.
6. Key People: 3-5 relevant humans, roles, why they matter, primary contact if any.
7. Relationships: connected entities, relationship type, confirmed vs inferred.
8. GTM check: Atlas-only or promote to GTM with segment, lane, owner, rationale, next action.

Then output:
Entity:
Existing Atlas match:
Proposed Atlas changes:
Key People:
Sources:
GTM recommendation:
Open questions:

Ask: "Validate this bundle now?" If validation passes, ask: "Submit this proposal to the curator inbox?"

Agent power model

Write access is explicit, scoped, and understandable.

write:proposals

Curator-reviewed proposals

Default write path. Agents propose entity, source, relationship, Key People, taxonomy, lore, and dossier updates. Curators accept in the inbox.

write:gtm

GTM operating actions

Trusted GTM agents can directly manage operating assignments, lanes, next actions, weekly brief records, brief links, and Field Intel events without changing canonical Atlas facts.

write:sources

Source intake

Agents can register public sources and upload source files against an entity, preserving attribution and review trails. Audio capture was retired on 2026-07-25 — submit the transcript or notes as text instead.

Readable endpoint map

The API surface at a glance

This first-party map is generated from the same OpenAPI object as the JSON spec, so agents and humans see the same contract even if an embedded docs viewer fails to load.

Raw OpenAPI JSON →

Auth, usage, and contract

GET/api/v1/whoami

Identify the calling agent

GET/api/v1/usage

Current period's API usage

GET/api/v1/agent-work/queues

List Atlas agent work queues

GET/api/v1/agent-work/items

List prioritized Atlas cleanup work items

GTM operating layer

GET/api/v1/gtm/segments

List GTM operating segments

GET/api/v1/gtm/assignments

List GTM entity assignments

POST/api/v1/gtm/assignments

Create or update a GTM entity assignment

PATCH/api/v1/gtm/assignments/{id}

Patch a GTM assignment

GET/api/v1/gtm/briefs

List GTM intelligence briefs

POST/api/v1/gtm/briefs

Create or update a GTM intelligence brief

GET/api/v1/gtm/briefs/{id}/links

List links for a GTM brief

POST/api/v1/gtm/briefs/{id}/links

Attach an entity, segment, or source to a GTM brief

Events / Field Intel

GET/api/v1/field-events

List Field Intel events

POST/api/v1/field-events

Create or update a Field Intel event

GET/api/v1/field-events/{slug}

Read one Field Intel event

PATCH/api/v1/field-events/{slug}

Patch one Field Intel event

POST/api/v1/field-events/{slug}/entities

Attach an entity to a Field Intel event

POST/api/v1/field-events/{slug}/people

Attach a person to a Field Intel event

POST/api/v1/field-events/{slug}/segments

Attach a segment to a Field Intel event

POST/api/v1/field-events/{slug}/goals

Add a goal to a Field Intel event

PATCH/api/v1/field-events/{slug}/goals/{goalId}

Update a Field Intel event goal

POST/api/v1/field-events/{slug}/interactions

Log a meeting/touchpoint at a Field Intel event

PATCH/api/v1/field-events/{slug}/interactions/{interactionId}

Update a Field Intel event interaction

POST/api/v1/field-events/{slug}/follow-ups

Add a follow-up action item to a Field Intel event

PATCH/api/v1/field-events/{slug}/follow-ups/{followUpId}

Update a Field Intel event follow-up

GET/api/v1/field-events/{slug}/scorecard

Read a Field Intel event's post-event scorecard

PATCH/api/v1/field-events/{slug}/scorecard

Upsert a Field Intel event's post-event scorecard

GET/api/v1/field-events/{slug}/roster

Read a Field Intel event's roster candidates

POST/api/v1/field-events/{slug}/roster

Bulk-ingest roster candidates discovered by an agent

PATCH/api/v1/field-events/{slug}/roster/{candidateId}

Refine one Field Intel event roster candidate

Discovery sprints

GET/api/v1/discovery-sprints/{sprint}/targets/{target}

Read one discovery sprint target

POST/api/v1/discovery-sprints/{sprint}/targets/{target}

Update one discovery sprint target

Atlas segments and drilldowns

GET/api/v1/segments/{slug}

Get one segment with optional Dossier embed

GET/api/v1/atlas/segments/{slug}/drilldown

Get a page-shaped Atlas segment drill-down

POST/api/v1/atlas/segments/{slug}/drilldown/proposals

Propose drill-down curation updates

GET/api/v1/atlas/visualization/overlaps

Get heuristic Atlas role-overlap buckets

GET/api/v1/atlas/visualization/coverage

Get Atlas data coverage and curation gaps

GET/api/v1/segments

List ecosystem segments

Taxonomy

GET/api/v1/taxonomy

List agent-facing taxonomy terms

GET/api/v1/taxonomy/{slug}

Get one taxonomy term

GET/api/v1/taxonomy/{slug}/entities

List entities assigned to a taxonomy term

Reference data

GET/api/v1/capabilities

List Lunar Rails capabilities

GET/api/v1/needs

List demand-side needs

GET/api/v1/verticals

List sub-classification verticals

GET/api/v1/sources/{id}

Get a source with a signed download URL

Entity catalog

GET/api/v1/entities

List catalog entities with filters

GET/api/v1/entities/{id}

Get a full entity dossier

GET/api/v1/entities/{id}/sources

List sources backing an entity's Dossier

Proposal inbox writes

GET/api/v1/agents/proposals

List your proposals

GET/api/v1/agents/proposals/{id}

Get one of your proposals with full change payload

POST/api/v1/agents/proposals/entity

Propose a new entity (optionally with enrichment)

POST/api/v1/agents/proposals/segments

Propose a new ecosystem segment

POST/api/v1/agents/proposals/lr-fit

Propose lr_fit rows for an entity (batch)

POST/api/v1/agents/proposals/entity-relationship

Publish an entity's relationship path (how contact formed + where comms live)

POST/api/v1/agents/proposals/providers

Propose provider relationships for an entity (batch)

POST/api/v1/agents/proposals/relationships

Propose entity-to-entity relationships (batch)

POST/api/v1/agents/proposals/events

Propose events for an entity (batch)

POST/api/v1/agents/proposals/field-events

Propose a field event with segment/entity/people intel (batch)

POST/api/v1/agents/validate/bundle

Dry-run validate a bundle proposal

POST/api/v1/agents/proposals/bundle

Propose multiple change kinds in one inbox card

POST/api/v1/agents/proposals/lore-update

Propose an update to an entity's Dossier narrative

POST/api/v1/agents/proposals/person

Propose a new person or an update to an existing one

POST/api/v1/agents/proposals/person-role

Propose attaching a person to an entity in a specific role

POST/api/v1/agents/proposals/segment-lore-update

Propose an update to a SEGMENT's Dossier narrative

Capture and source intake

POST/api/v1/agents/sources

Create a URL-based source for an entity

POST/api/v1/agents/sources/upload

Upload a file-backed source for an entity

Key People graph

GET/api/v1/people

List people with filters

GET/api/v1/people/{id}

Get a full person dossier

Interactive reference

Endpoint explorer

This is generated from /api/v1/openapi.json, which is the source of truth for agents and client builders.