Developer interface

The API contract for approved machine access.

This page documents how approved software reads Planetary Model records and their sources. The contract is verified in the repository. The public API target is not yet a generally available hosted service.

Response metadata

schemaVersionasOfinterfaceProvenanceprovenanceconfidenceuncertaintysourceRefsredactionentitlementsnextCursor

Source ref proof

sourceTypesourceIdoccurredAtpublishedAtprovenanceKeys

API families

What the contract covers.

Onboarding

Inspect approved access status, key policy, SDK env vars, OAuth posture, and sandbox blockers.

Capabilities

See the product surfaces available to an authorized client.

Schemas

Understand response envelopes, error models, redaction, and pagination conventions.

Entities and records

Search for canonical entities and read current records for approved domains.

Evidence and paths

Fetch evidence bundles and inspect why a recorded change matters.

Decision inputs

Read typed records designed for enterprise workflows and internal systems.

Updates

Consume cursor-based updates and inspect read-only webhook delivery state.

Quickstart

Start with the base URL from your handoff.

These calls are examples, not a live public quickstart. An approved client receives a base URL, token, and entity scope. The client reads its capabilities before requesting records or evidence.

Contract examples

if [ -z "$CROWDALPHA_API_BASE" ]; then
  echo "Use the base URL from your approved handoff" >&2
  exit 1
fi

curl "$CROWDALPHA_API_BASE/api/v1/onboarding" \
  -H "Authorization: Bearer $CROWDALPHA_API_TOKEN" \
  -H "Accept: application/json"

curl "$CROWDALPHA_API_BASE/api/v1/capabilities" \
  -H "Authorization: Bearer $CROWDALPHA_API_TOKEN" \
  -H "Accept: application/json"

CROWDALPHA_ENTITY_ID_URLENCODED="$(python - <<'PY'
import os
from urllib.parse import quote
print(quote(os.environ["CROWDALPHA_ENTITY_ID"], safe=""))
PY
)"

curl "$CROWDALPHA_API_BASE/api/v1/state/entities/$CROWDALPHA_ENTITY_ID_URLENCODED" \
  -H "Authorization: Bearer $CROWDALPHA_API_TOKEN" \
  -H "Accept: application/json"

Client snippets

Use any HTTP client. Keep the error model.

The examples below read the base URL from the environment. They illustrate the verified contract shape. Public SDK packages and install commands are not available yet.

Python

import os
from urllib.parse import quote

import requests

base_url = os.environ["CROWDALPHA_API_BASE"].rstrip("/")
entity_id = os.environ["CROWDALPHA_ENTITY_ID"]
headers = {
    "Authorization": f"Bearer {os.environ['CROWDALPHA_API_TOKEN']}",
    "Accept": "application/json",
}

def crowdalpha_error(payload):
    payload = payload if isinstance(payload, dict) else {}
    detail = payload.get("detail")
    error = detail.get("error") if isinstance(detail, dict) else None
    error = error or detail or payload.get("error", {})
    return {
        "code": error.get("code", "UNKNOWN_ERROR"),
        "message": error.get("message", "CrowdAlpha request failed"),
        "missingScopes": error.get("missingScopes", []),
    }

http_response = requests.get(
    f"{base_url}/api/v1/state/entities/{quote(entity_id, safe='')}",
    headers=headers,
    timeout=20,
)
response = http_response.json()

if not http_response.ok or not response.get("success"):
    raise RuntimeError(crowdalpha_error(response))

state = response["data"]
print(state["schemaVersion"], state["asOf"])
print(state["interfaceProvenance"]["authority"])
print(state["entity_id"])
print(state["confidence"], state["uncertainty"])

TypeScript

const entityId = process.env.CROWDALPHA_ENTITY_ID;
if (!entityId) {
  throw new Error("CROWDALPHA_ENTITY_ID is required");
}

const baseUrl = process.env.CROWDALPHA_API_BASE;
if (!baseUrl) {
  throw new Error("Use the base URL from your approved handoff");
}

const response = await fetch(
  `${baseUrl}/api/v1/state/entities/${encodeURIComponent(entityId)}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.CROWDALPHA_API_TOKEN}`,
      Accept: "application/json",
    },
  },
);

const body = await response.json();
const parseCrowdAlphaError = (payload: any) => {
  const error = payload?.detail?.error ?? payload?.detail ?? payload?.error;
  return {
    code: error?.code ?? "UNKNOWN_ERROR",
    message: error?.message ?? "CrowdAlpha request failed",
    missingScopes: error?.missingScopes ?? [],
  };
};

if (!response.ok || !body.success) {
  throw new Error(JSON.stringify(parseCrowdAlphaError(body)));
}

const state = body.data;
console.log(
  state.schemaVersion,
  state.asOf,
  state.interfaceProvenance.authority,
);

Error model

Failures stay machine-readable.

Agents need to know whether a request failed because of auth, access scope, validation, rate limits, or backend availability. Error details preserve machine-readable codes and missing scopes so callers can fail closed instead of inventing a result.

Capabilities advertise `agent_error_model_v1`; schemas expose `AgentErrorResponse`; verified OpenAPI operations carry `x-crowdalpha-error-schema`.

Auth envelope

{
  "detail": {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Missing or invalid token"
    }
  }
}

Scope guard

{
  "detail": {
    "code": "AGENT_SCOPE_DENIED",
    "message": "Agent interface scope denied",
    "missingScopes": [
      "evidence.read"
    ]
  }
}

Webhook entitlement guard

{
  "detail": {
    "code": "AGENT_WEBHOOK_ENTITLEMENT_REQUIRED",
    "message": "Webhook visibility requires an entitlement-bound AgentLayer client."
  }
}

Simulation quota guard

{
  "detail": {
    "code": "AGENT_SIMULATION_QUOTA_EXCEEDED",
    "message": "Agent simulation quota exceeded for this package."
  }
}

The contract keeps each record tied to its source and access rules.

Open JSON contract See examples