Developer interface

A value-added Planetary Model API authorized agents and software systems can build against.

AgentLayer exposes the Planetary Model through documented contracts for authorized agents and software systems. It is for reading state, evidence, decision inputs, packages, and updates; it is not a shortcut around provenance.

Response metadata

schemaVersionasOfinterfaceProvenanceprovenanceconfidenceuncertaintysourceRefsredactionentitlementsnextCursor

Source ref proof

sourceTypesourceIdoccurredAtpublishedAtprovenanceKeys

API families

Simple categories. Stable contracts.

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

A builder should know the first call in seconds.

Production keys are issued through approved access. The interface is intentionally straightforward: discover capabilities, request records, then fetch evidence before citing or acting. Entity IDs come from the caller's approved entitlement manifest; public sample-data entitlements are not assumed.

Example calls

curl https://api.crowdalpha.ai/api/v1/onboarding \
  -H "Authorization: Bearer $CROWDALPHA_API_TOKEN" \
  -H "Accept: application/json"

curl https://api.crowdalpha.ai/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 "https://api.crowdalpha.ai/api/v1/state/entities/$CROWDALPHA_ENTITY_ID_URLENCODED" \
  -H "Authorization: Bearer $CROWDALPHA_API_TOKEN" \
  -H "Accept: application/json"

Client snippets

Make the first call, then fetch the evidence.

AgentLayer responses are plain JSON over HTTPS. Builders can start with curl, Python, TypeScript, or agent integrations. Approved customers receive the interface document, approved-access SDK samples, and package artifacts; public registry publishing remains an approved release step.

Python

import os
from urllib.parse import quote

import requests

base_url = "https://api.crowdalpha.ai"
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 response = await fetch(
  `https://api.crowdalpha.ai/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`; stable 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 API returns records with context, not disconnected rows.

Open JSON contractSee examples