Send a decision. Check a receipt. From any system.

What the API never does

• It never approves a decision. Every record arrives pending and waits for a person.
• It never lets a sender set its own score. North Star computes the score from the ratings.
• It never reads another account. A connection key writes into one inbox and can be revoked at any time.
• It never publishes more than the client consented to. A receipt carries only the publish level its owner chose.

1. Get a connection key

Keys are issued inside the client portal, one per system, and start with nsv_. Assign a decision template to a key and it fills the owner, due date and ratings for decisions that arrive without them.

How connections work →

2. Submit a decision

One request, one decision. Limit 60 an hour per sender and 8 KB per body.

POST https://northstarintel.ai/api/public/decisions
Authorization: Bearer nsv_<your-connection-key>
Content-Type: application/json

{
  "decision": "Add a second dispatcher before storm season",
  "owner": "Dispatch lead",
  "next_action": "Post the role and approve overtime until it is filled",
  "due_at": "2026-11-14",
  "opportunity": 3,
  "risk": 3,
  "effort": 2,
  "system": "Scheduling and dispatch",
  "external_ref": "dispatch-2026-11-07"
}

HTTP 201 Created

{
  "id": "a1b2c3d4-...",
  "score": 88,
  "status": "pending",
  "closing_state": "Follow-up owned"
}

Responses

• 201Saved. The record is pending until a person approves it.
• 200Same external_ref as before. The existing record is returned with duplicate: true.
• 401Missing, malformed or revoked key.
• 413Body over 8 KB.
• 422Invalid field, or a value outside the ranges the key's decision template allows. The response lists each issue.
• 429More than 60 requests in an hour from one sender.
• 500Not saved. Nothing was recorded, so retry later.

3. The score

((2 × opportunity) + risk of waiting − effort) ÷ 8 × 100, each input rated 1 to 3. The example above scores 88. It ranks one decision against others and is not a percentage of revenue.

How the score is calculated →

4. Verify a receipt

No key needed. Limit 120 lookups an hour. A receipt that its owner did not consent to publish returns 404.

GET https://northstarintel.ai/api/public/receipts?id=NSV-2026-7K3M9Q
GET https://northstarintel.ai/api/public/receipt-keys

{
  "id": "NSV-2026-7K3M9Q",
  "payload": "{\"decision\":...,\"id\":\"NSV-2026-7K3M9Q\",\"key_id\":\"k-2026-01\",\"standard\":\"North Star Verified\",...}",
  "payload_sha256": "9f2c...",
  "prev_sha256": "41ab...",
  "signature": "base64 Ed25519 signature",
  "key_id": "k-2026-01",
  "public_key": "base64 raw Ed25519 public key",
  "created_at": "2026-11-07T20:00:00Z"
}

Four checks, all on your side

• FingerprintSHA-256 of the payload text equals payload_sha256.
• IdentityThe payload, in canonical JSON with sorted keys, names this id, key_id and prev_sha256, and its standard is North Star Verified.
• SignatureThe Ed25519 signature verifies over the payload text with public_key.
• Registrypublic_key appears in /api/public/receipt-keys, retired keys included.

All four pass: the receipt is valid. Any one fails: it is broken, whatever our server says. The same checks run in the browser on the verify page.

Verify a receipt in the browser →

5. The MCP server

A Model Context Protocol server gives any AI agent four tools: score_decision, submit_decision, verify_receipt and list_receipt_keys, plus the scoring formula and the Evidence Contract as readable resources. It runs over stdio with Node 20 or newer.

{
  "mcpServers": {
    "north-star-intel": {
      "command": "node",
      "args": ["/path/to/north-star-mcp/dist/index.js"],
      "env": { "NORTH_STAR_API_KEY": "nsv_..." }
    }
  }
}

Write to admin@northstarintel.ai for the package and setup notes for Claude, Cursor and other MCP clients.

Questions

One person reads every message. Tell us which system you are connecting and what the decision looks like on your side.

Contact →