Partner API v1 · Draft, not yet live

Partner API v1: overview

Draft — not yet live. This describes the proposed v1 partner contract (version 1.0.0-rc.1). No endpoint on this page is deployed, and no API key can be issued yet.

Version 1 is the partner-facing layer over the Crown Intelligence data service. It adds API keys with scopes, metering, batch matching with a clear status for every query, webhooks, monitoring of public list entries and evidence packs. This page explains the rules that every operation follows.

Status of this API

The v1 contract is a draft, version 1.0.0-rc.1. It is not deployed, not published and not billed. The addresses below are proposed; they do not resolve to a running service yet.

API keys and scopes

Send the key in the X-Api-Key header on every request except GET /v1/status, which needs no key.

• Live keys start with ci_live_. Sandbox keys start with ci_test_. A sandbox key never reaches a live route and never creates a billable order.
• The secret is shown once, when the key is created. Crown Intelligence keeps only a hash and the visible prefix.
• Each key carries explicit scopes. A key without the scope a route needs gets 403 forbidden_scope.
• Revocation is immediate and final. A revoked key returns 401 key_revoked. Keys are retired, never deleted.
• A live key must name the subscription order it is billed under (order_id).

Try it: a keyed request

curl:

curl https://api.crownintelligence.net/v1/sources \
  -H "X-Api-Key: $CI_API_KEY"

Node (20 or later):

const res = await fetch("https://api.crownintelligence.net/v1/sources", {
  headers: { "X-Api-Key": process.env.CI_API_KEY }
});
if (!res.ok) throw new Error("HTTP " + res.status);
const body = await res.json();

Health check without a key:

curl https://api.crownintelligence.net/v1/status

Billing reference: internal calls only

Every cross-service call carries a billing reference, sent in the X-Billing-Ref header as compact ASCII JSON of at most 1,024 bytes. It records who the call is for, so that usage can be billed and cost recorded.

{"source_service":"partner-api","source_account":"acct_demo_bank",
 "order_id":"ord_2026_1041","type":"ORDER","parent_call":null,"invoice_line_id":null}

• Partner calls may leave the header out. The gateway fills source_service and source_account from the authenticated key, and takes the order from the key's order_id. A partner cannot set these itself. If a sent header disagrees with its key, the call is refused with 400 billing_ref_invalid.
• Internal calls must send it. A Crown service calling Crown Intelligence without the header is refused with 400 billing_ref_missing. The object passes down a chain unchanged, and each hop sets parent_call to the call that triggered it.
• type is ORDER when a customer pays for the call. It is OVERHEAD for system traffic, with no invoice and cost still recorded. An ORDER must carry order_id; an OVERHEAD carries order_id: null.
• No other fields are allowed. The API never shows money: usage is reported in units only, and prices are set on the invoice.

// Internal Crown service calling match: pass the caller's billing_ref unchanged in X-Billing-Ref.
const billingRef = {
  source_service: "your-registered-service-id",
  source_account: null,
  order_id: null,
  type: "OVERHEAD",
  parent_call: incomingBillingRefId,   // id of the call that triggered this one, or null at the top
  invoice_line_id: null
};
const res = await fetch("https://api.crownintelligence.net/v1/match", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.CI_INTERNAL_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
    "X-Billing-Ref": JSON.stringify(billingRef)
  },
  body: JSON.stringify({ queries: [{ query_ref: "svc-1", entity_type: "Company", name: "Northwind Trading LLC" }] })
});

Open items: the source identifier partner-api is not yet registered in the service catalogue, and the owner has not yet decided whether usage rows carry a price reference. See the contract, sections 4 and 16.

Match statuses: never clear by default

Every query in a match response has one of four statuses. The rule is simple: a query is reported as clear only when every register it should cover was searched and nothing matched. The word clear is not a value anywhere in the API.

A status of not_searched or error must never be shown as clear, stored as clear or passed on as clear. Build your decision logic so that only no_hit_searched can ever produce a negative result.

Match bands

Each match carries a band instead of a raw threshold. Bands are derived from the score (0 to 1) and the identifiers that agree.

Nothing below 0.60 is returned. The band floors are proposed, not yet calibrated against a labelled set of pairs, so do not build a fixed rule on them until calibration is published. Matcher versions will be exposed on each response.

Rate limits and quotas

These defaults are proposed. Plan limits are placeholders until the owner sets them.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Metered calls also carry X-Usage-Units. A 429 response carries Retry-After.

Idempotency and versions

Every POST accepts an Idempotency-Key of up to 255 characters. Repeating the same key with the same body within 24 hours returns the stored response with no second charge. Reusing the key with a different body returns 409 idempotency_mismatch.

The version is in the path (/v1). Changes within v1 are additive. A breaking change moves to /v2, with at least six months' notice of any deprecation.

Errors

Every error is application/problem+json (RFC 9457). Each error carries a stable code, a request_id to quote to support, and its message in English (messages.en) and French (messages.fr).

{"type":"https://api.crownintelligence.net/problems/invalid_request","title":"Invalid request",
 "status":400,"code":"invalid_request","detail":"queries[3].name must be at least 2 characters",
 "messages":{"en":"queries[3].name must be at least 2 characters",
   "fr":"queries[3].name doit comporter au moins 2 caractères"},
 "request_id":"req_01J9Z3K4M6","errors":[{"pointer":"/queries/3/name","code":"too_short",
   "message":{"en":"Use at least 2 characters.","fr":"Utilisez au moins 2 caractères."}}]}

In a batch, a single query can fail with an error status. The batch itself still returns 200, and that query is never reported as clear.

const res = await fetch(url, { headers: { "X-Api-Key": process.env.CI_API_KEY } });
if (!res.ok) {
  const problem = await res.json();              // application/problem+json
  console.error(problem.code, problem.request_id, problem.messages.en);
  if (res.status === 429 || res.status === 503) {
    const wait = Number(res.headers.get("Retry-After") ?? 5);   // back off, then retry the same request
  }
}

Pages in this section

• Matching: POST /v1/match, the request, the response and the statuses
• Webhooks: events, signatures and retries
• Monitoring, and why a monitor never holds a person
• Cases and evidence packs