OrbitLens API

Overview

The OrbitLens API lets the EIS CLI push locally-computed signals to your observatory, and lets anyone embed a signal badge.

EIS analyses your repository locally — git log and git blame, nothing else. The CLI uploads only the resulting signals (the 7-axis scores and archetypes), never source code. This is the path for teams who can't or won't let the SaaS clone their repos (GitHub Enterprise, air-gapped, strict policy).

Uploaded observations are CLI-sourced: the observatory can't re-derive them from git (it never sees the repo), so their credibility is surfaced through the Trust Signal rather than server-side reproducibility.

Authentication

All write endpoints take a Bearer token. Create one in Ace → Settings → API tokens (shown once). Tokens are prefixed eis_ and scoped to the galaxy that created them.

Authorization: Bearer eis_xxxxxxxxxxxxxxxxxxxx

The recommended path is the CLI, which sends the token for you:

# token via flag or $EIS_TOKEN
eis analyze --upload --token eis_xxxx

Rate limits

Requests are rate-limited per token/user, by plan. Every response carries the standard headers:

Header	Meaning
X-RateLimit-Limit	Requests allowed per minute for your plan
X-RateLimit-Remaining	Requests left in the current window
X-RateLimit-Reset	Unix time when the window resets

Over the limit returns 429 Too Many Requests. Uploads run once per analysis (e.g. per CI build), so the plan limits leave generous headroom.

Upload signals

POST/v1/signals/upload

Auth: Bearer eis_ token (or JWT)

Writes per-member signals for one domain as an observation, keyed on the analyzed commit. git_sha and sha_author_date are required — the observatory uses them to place the observation on the timeline (it can't derive them itself).

Request body

Field	Type
git_sha	string	HEAD commit of the analyzed repo (required)
sha_author_date	RFC3339	Author date of that commit (required)
analysis_time	RFC3339	When the analysis ran
domain	string	Logical domain (e.g. "backend")
signals[]	object	Per-member 7-axis scores + archetypes

Example

curl -X POST https://ace-api.orbitlens.io/v1/signals/upload \
  -H "Authorization: Bearer eis_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "git_sha": "a1b2c3d4...",
    "sha_author_date": "2026-06-15T09:00:00Z",
    "analysis_time": "2026-06-15T09:05:00Z",
    "domain": "backend",
    "signals": [
      { "author": "alice", "production": 100, "catalysis": 68,
        "survival": 40, "design": 20, "breadth": 55,
        "debt_cleanup": 30, "indispensability": 25, "total": 62.7,
        "role_archetype": "Anchor" }
    ]
  }'

Response `201`

{ "members": 1, "git_sha": "a1b2c3d4..." }

In practice you never hand-build this — run eis analyze --upload and the CLI assembles the payload (including git_sha) from your local analysis.

Signal badge

GET/badge/:account_login/:author

Public — no auth

Returns an SVG badge of a member's current Total + archetype, for embedding in a README.

<!-- Markdown -->
![EIS](https://ace-api.orbitlens.io/badge/your-org/alice)

Errors

Status	Meaning
400	Malformed body, or missing `git_sha` / `sha_author_date` (upgrade the CLI)
401	Missing or invalid / expired token
429	Rate limit exceeded — back off until `X-RateLimit-Reset`