401 auth envelope
Shared auth failures use the response-builder envelope shape.
{
"detail": {
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Missing or invalid token"
}
}
}Agent workflows
How agents should use CrowdAlpha before acting.
AgentLayer is designed for retrieval, inspection, and workflow grounding. The authorized agent asks for records, evidence, discovery leads, and decision context, then carries the returned metadata forward.
Example response shape
{
"success": true,
"data": {
"schemaVersion": "crowdalpha.agent.v1",
"asOf": "2026-05-04T20:00:00Z",
"version": "agent_world_context_v1",
"answerType": "grounded_world_context",
"entity": {
"entity_id": "CROWDALPHA_ENTITY_ID",
"name": "Approved entity",
"type": "world_entity"
},
"currentState": [
{
"key": "route_viability",
"value": 0.42,
"band": "CONSTRAINED",
"confidence": 0.77,
"uncertainty": 0.18
}
],
"latestTransitions": [
{
"key": "route_viability",
"from": 0.8,
"to": 0.42,
"delta": -0.38
}
],
"compositeScores": [
{
"profileKey": "maritime_route_pressure",
"score": 0.61,
"band": "ELEVATED",
"semantics": "pressure_high_is_risk",
"status": "READY"
}
],
"evidence": [
{
"evidenceId": "observation:CROWDALPHA_EVIDENCE_ID",
"observationId": "CROWDALPHA_EVIDENCE_ID",
"sourceLabel": "world_observation",
"collectedAt": "2026-05-04T19:54:00Z"
}
],
"contradictions": [
{
"id": "CROWDALPHA_CONTRADICTION_ID",
"status": "OPEN"
}
],
"blockers": [],
"status": "READY",
"confidence": 0.77,
"uncertainty": 0.18,
"sourceRefs": [
{
"refType": "observation",
"refId": "CROWDALPHA_EVIDENCE_ID",
"evidenceId": "observation:CROWDALPHA_EVIDENCE_ID",
"sourceType": "world_observation",
"sourceId": "CROWDALPHA_EVIDENCE_ID",
"sourceLabel": "world_observation",
"stateVariable": "route_viability",
"occurredAt": "2026-05-04T19:54:00Z",
"publishedAt": "2026-05-04T19:54:00Z",
"provenanceKeys": [
"world_observation",
"source_artifact"
]
}
],
"provenance": {
"interface": "crowdalpha_agent_interface_v1",
"truthLayer": "world_model",
"authority": "stored_state_transitions",
"llmGeneratedFactsAllowed": false
},
"redaction": {
"applied": false,
"rules": []
},
"entitlements": {
"mode": "role_derived_v1",
"actorRole": "USER",
"requiredScopes": [
"world.read",
"evidence.read"
],
"effectiveScopes": [
"world.read",
"evidence.read",
"decision.read",
"stream.read"
],
"missingScopes": []
}
}
}Recommended path
The agent should bring receipts with the answer.
01
Find the canonical entity or package.
02
Read the current record and recent changes.
03
Fetch evidence before citing or acting.
04
Label discovery leads and blockers instead of certainty.
05
Use decision inputs when the result enters a workflow.
06
Preserve provenance, confidence, uncertainty, and redaction metadata.
Minimal agent loop
Read the record first. Pull evidence before claims.
The agent should avoid inventing context. It reads the response envelope, checks redaction and access scope, then fetches evidence only when the response says evidence is available.
TypeScript agent helper
async function readCrowdAlphaState(entityId: string) {
const baseUrl = "https://api.crowdalpha.ai";
const headers = {
Authorization: `Bearer ${process.env.CROWDALPHA_API_TOKEN}`,
Accept: "application/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 ?? [],
};
};
const stateResponse = await fetch(
`${baseUrl}/api/v1/state/entities/${encodeURIComponent(entityId)}`,
{ headers },
);
const body = await stateResponse.json();
if (!stateResponse.ok || !body.success) {
return {
state: null,
evidence: null,
error: parseCrowdAlphaError(body),
};
}
const state = body.data;
if (state.redaction?.applied) {
return { state, evidence: null, note: state.redaction.rules?.join(", ") };
}
const evidenceRef =
state.evidence?.find(
(row: any) =>
typeof row?.evidenceId === "string" &&
row.evidenceId.startsWith("observation:"),
)?.evidenceId ??
state.sourceRefs?.find(
(ref: any) =>
typeof ref?.evidenceId === "string" &&
ref.evidenceId.startsWith("observation:"),
)?.evidenceId ??
state.sourceRefs?.find(
(ref: any) =>
ref?.refType === "observation" && typeof ref?.refId === "string",
)?.refId;
const evidenceResponse = evidenceRef
? await fetch(`${baseUrl}/api/v1/evidence/${encodeURIComponent(evidenceRef)}`, { headers })
: null;
return {
state,
evidence: evidenceResponse ? await evidenceResponse.json() : null,
};
}Error examples
Treat failures as contract data.
AgentLayer advertises `agent_error_model_v1` through capabilities, schemas, and OpenAPI. Clients should preserve codes, missing scopes, redaction, and retry policy instead of converting failures into unsupported answers.
403 scope guard
Direct AgentLayer guards preserve missing scopes for fail-closed clients.
{
"detail": {
"code": "AGENT_SCOPE_DENIED",
"message": "Agent interface scope denied",
"missingScopes": [
"evidence.read"
]
}
}403 entitlement guard
Entitlement misses return a code instead of substituting generated state.
{
"detail": {
"code": "AGENT_ENTITLEMENT_DENIED",
"message": "Agent entitlement denies this entity."
}
}403 package simulation guard
Scoped clients must treat hidden simulation result refs as a denial, not as visible branch data.
{
"detail": {
"code": "AGENT_ENTITLEMENT_DENIED",
"message": "Agent entitlement does not allow this state-package simulation result."
}
}429 rate limit guard
Rate limits remain parseable; callers should retry by policy.
{
"detail": {
"code": "AGENT_RATE_LIMITED",
"message": "Agent client is rate limited. Try again after 60 seconds."
}
}authorized discovery agent
Find costly blind spots
Scan approved Planetary Model and customer-private context for stale assumptions, missing evidence, hidden exposure, operational friction, and action blockers before they become losses.
approved builder or operator
Build an approved implementation agent
Use approved access and evidence-backed context packets so the agent can cite returned CrowdAlpha state before calling tools, updating workflows, or briefing a team.
routing or underwriting agent
Check a route or infrastructure state
Search the corridor, request the grounded context packet, inspect contradictions and evidence, then preserve the decision meaning downstream.
insurance or compliance agent
Read cover integrity context
Query the relevant entity, retrieve history and evidence, then return a review-ready package to a human operator.
critical-context agent
Explain the drivers
Start from a record, inspect the returned driver context, and cite the evidence instead of inventing a free-form explanation.
workflow automation
Monitor subscribed updates
Read entitled updates and request evidence before acting on sensitive movement.
scenario-planning agent
Run a bounded scenario
Run approved scenario analysis, label the result clearly, and keep it separate from observed records.