Fulcrum gRPC API Reference

Version: 2.0.0 Last Updated: January 6, 2026 Status: Production

Overview

Fulcrum exposes a comprehensive gRPC API for AI agent governance. All services use Protocol Buffers version 3 (proto3) and are designed for high-performance, low-latency operations.

Base Configuration

Parameter	Value
Protocol	gRPC (HTTP/2)
Default Port	50051
TLS	Required in production
Max Message Size	4MB (default)
Timeout	30 seconds (default)

Proto Package Structure

fulcrum/
  envelope/v1/    # Core envelope operations
  policy/v1/      # Policy management and evaluation
  cost/v1/        # Budget and cost tracking
  checkpoint/v1/  # State persistence
  tenant/v1/      # Tenant and API key management
  events/v1/      # Event definitions
  eventstore/v1/  # Event persistence and streaming
  brain/v1/       # Cognitive layer (Semantic Judge, Oracle, Immune System)
  bridge/v1/      # Python-Go bridge protocol

Connecting to Fulcrum

# grpcurl installation
brew install grpcurl

# List available services
grpcurl -plaintext localhost:50051 list

# Describe a service
grpcurl -plaintext localhost:50051 describe fulcrum.envelope.v1.EnvelopeService

Authentication

All API calls require authentication via metadata headers.

API Key Authentication

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  localhost:50051 fulcrum.envelope.v1.EnvelopeService/GetEnvelope

Tenant Context

Multi-tenant isolation is enforced automatically based on the API key's associated tenant.

Header	Description	Required
`Authorization`	Bearer token with API key	Yes
`x-tenant-id`	Explicit tenant override (admin only)	No
`x-request-id`	Correlation ID for tracing	No

Error Handling

Fulcrum uses standard gRPC status codes with detailed error messages.

Standard Error Codes

Code	Name	Description
0	OK	Success
1	CANCELLED	Operation cancelled
2	UNKNOWN	Unknown error
3	INVALID_ARGUMENT	Invalid request parameters
4	DEADLINE_EXCEEDED	Timeout
5	NOT_FOUND	Resource not found
6	ALREADY_EXISTS	Resource already exists
7	PERMISSION_DENIED	Insufficient permissions
8	RESOURCE_EXHAUSTED	Rate limit exceeded or budget exhausted
9	FAILED_PRECONDITION	Invalid state for operation
10	ABORTED	Operation aborted
11	OUT_OF_RANGE	Value out of valid range
12	UNIMPLEMENTED	Method not implemented
13	INTERNAL	Internal server error
14	UNAVAILABLE	Service unavailable
16	UNAUTHENTICATED	Missing or invalid authentication

Error Response Format

{
  "code": 3,
  "message": "tenant_id is required",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "field_violations": [
        {
          "field": "tenant_id",
          "description": "Field is required"
        }
      ]
    }
  ]
}

Services

EnvelopeService

Package: fulcrum.envelope.v1 Description: Manages execution envelopes - Fulcrum's core abstraction. Every agent execution is wrapped in an envelope for governance.

CreateEnvelope

Creates a new execution envelope with governance context.

Method: CreateEnvelope Request: CreateEnvelopeRequest Response: CreateEnvelopeResponse

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`budget_id`	string	No	Specific budget to use
`adapter_type`	string	Yes	Framework adapter (e.g., "custom", "langchain", "langgraph")
`metadata`	map	No	Key-value pairs for policy evaluation

Response Schema

Field	Type	Description
`envelope`	ExecutionEnvelope	The created envelope

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "budget_id": "budget-456",
    "adapter_type": "langgraph",
    "metadata": {
      "tool_name": "code_executor",
      "model_name": "gpt-4"
    }
  }' \
  localhost:50051 fulcrum.envelope.v1.EnvelopeService/CreateEnvelope

Response Example

{
  "envelope": {
    "envelope_id": "env-abc123",
    "tenant_id": "tenant-123",
    "execution_id": "exec-789",
    "status": "ENVELOPE_STATUS_PENDING",
    "governance": {
      "budget_id": "budget-456",
      "token_budget": 100000,
      "cost_limit_usd": 10.0,
      "timeout_seconds": 300
    },
    "created_at": "2026-01-06T10:00:00Z"
  }
}

GetEnvelope

Retrieves an envelope by ID.

Method: GetEnvelope Request: GetEnvelopeRequest Response: GetEnvelopeResponse

Request Schema

Field	Type	Required	Description
`envelope_id`	string	Yes	Envelope identifier

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"envelope_id": "env-abc123"}' \
  localhost:50051 fulcrum.envelope.v1.EnvelopeService/GetEnvelope

UpdateEnvelopeStatus

Updates the status of an envelope.

Method: UpdateEnvelopeStatus Request: UpdateEnvelopeStatusRequest Response: UpdateEnvelopeStatusResponse

Request Schema

Field	Type	Required	Description
`envelope_id`	string	Yes	Envelope identifier
`status`	EnvelopeStatus	Yes	New status
`reason`	string	No	Reason for status change

Valid Status Transitions

PENDING -> AUTHORIZED -> RUNNING -> COMPLETED
                     \-> PAUSED -> RUNNING
                     \-> FAILED
                     \-> TERMINATED
                     \-> BUDGET_EXCEEDED
                     \-> POLICY_VIOLATION
                     \-> TIMEOUT

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "envelope_id": "env-abc123",
    "status": "ENVELOPE_STATUS_RUNNING",
    "reason": "Policy checks passed"
  }' \
  localhost:50051 fulcrum.envelope.v1.EnvelopeService/UpdateEnvelopeStatus

PolicyService

Package: fulcrum.policy.v1 Description: Manages governance policies and evaluates rules against execution contexts.

CreatePolicy

Creates a new governance policy.

Method: CreatePolicy HTTP: POST /v1/policies Request: CreatePolicyRequest Response: CreatePolicyResponse

Request Schema

Field	Type	Required	Description
`policy`	Policy	Yes	Policy definition

Policy Schema

Field	Type	Required	Description
`policy_id`	string	No	Auto-generated if not provided
`tenant_id`	string	Yes	Owning tenant
`name`	string	Yes	Human-readable name
`description`	string	No	Policy description
`tags`	map	No	Metadata tags
`rules`	PolicyRule[]	Yes	List of policy rules
`scope`	PolicyScope	No	Where policy applies
`status`	PolicyStatus	No	Default: DRAFT
`enforcement`	EnforcementLevel	No	Default: AUDIT
`priority`	int32	No	Higher = evaluated first

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "policy": {
      "tenant_id": "tenant-123",
      "name": "Block Dangerous Tools",
      "description": "Prevents execution of shell commands",
      "rules": [
        {
          "rule_id": "rule-1",
          "name": "Block Shell",
          "conditions": [
            {
              "condition_type": "CONDITION_TYPE_IN_LIST",
              "field": "tool.name",
              "operator": "CONDITION_OPERATOR_IN",
              "values": ["shell_exec", "os_command", "subprocess"]
            }
          ],
          "actions": [
            {
              "action_type": "ACTION_TYPE_DENY",
              "message": "Shell execution is not permitted",
              "severity": "SEVERITY_LEVEL_HIGH"
            }
          ],
          "rule_type": "RULE_TYPE_TOOL_ALLOWLIST",
          "enabled": true
        }
      ],
      "status": "POLICY_STATUS_ACTIVE",
      "enforcement": "ENFORCEMENT_LEVEL_BLOCK",
      "priority": 100
    }
  }' \
  localhost:50051 fulcrum.policy.v1.PolicyService/CreatePolicy

GetPolicy

Retrieves a policy by ID.

Method: GetPolicy HTTP: GET /v1/policies/{policy_id}

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"policy_id": "pol-abc123"}' \
  localhost:50051 fulcrum.policy.v1.PolicyService/GetPolicy

UpdatePolicy

Updates an existing policy.

Method: UpdatePolicy HTTP: PATCH /v1/policies/{policy.policy_id}

Request Schema

Field	Type	Required	Description
`policy`	Policy	Yes	Updated policy (must include policy_id)
`update_mask`	string[]	No	Fields to update (empty = all)

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "policy": {
      "policy_id": "pol-abc123",
      "enforcement": "ENFORCEMENT_LEVEL_TERMINATE"
    },
    "update_mask": ["enforcement"]
  }' \
  localhost:50051 fulcrum.policy.v1.PolicyService/UpdatePolicy

DeletePolicy

Deletes a policy.

Method: DeletePolicy HTTP: DELETE /v1/policies/{policy_id}

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"policy_id": "pol-abc123"}' \
  localhost:50051 fulcrum.policy.v1.PolicyService/DeletePolicy

ListPolicies

Lists policies with filtering and pagination.

Method: ListPolicies HTTP: GET /v1/policies

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant
`status`	PolicyStatus	No	Filter by status
`rule_type`	RuleType	No	Filter by rule type
`page_size`	int32	No	Results per page (default: 20, max: 100)
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "status": "POLICY_STATUS_ACTIVE",
    "page_size": 50
  }' \
  localhost:50051 fulcrum.policy.v1.PolicyService/ListPolicies

EvaluatePolicy

Evaluates a single policy against an execution context.

Method: EvaluatePolicy HTTP: POST /v1/policies/evaluate

Request Schema

Field	Type	Required	Description
`policy_id`	string	Yes	Policy to evaluate
`context`	EvaluationContext	Yes	Execution context
`dry_run`	bool	No	If true, don't execute actions

EvaluationContext Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`workflow_id`	string	No	Workflow identifier
`envelope_id`	string	No	Envelope identifier
`user_id`	string	No	User identifier
`user_roles`	string[]	No	User roles for RBAC
`phase`	ExecutionPhase	Yes	Current execution phase
`model_id`	string	No	Model being used
`tool_names`	string[]	No	Tools being invoked
`input_text`	string	No	Input content to evaluate
`output_text`	string	No	Output content to evaluate
`attributes`	map	No	Additional context
`timestamp`	Timestamp	No	Evaluation time

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "policy_id": "pol-abc123",
    "context": {
      "tenant_id": "tenant-123",
      "envelope_id": "env-xyz789",
      "phase": "EXECUTION_PHASE_PRE_TOOL_CALL",
      "tool_names": ["shell_exec"],
      "user_id": "user-456",
      "user_roles": ["developer"]
    },
    "dry_run": false
  }' \
  localhost:50051 fulcrum.policy.v1.PolicyService/EvaluatePolicy

Response Schema

Field	Type	Description
`result`	EvaluationResult	Evaluation outcome

EvaluationResult Fields

Field	Type	Description
`policy_id`	string	Policy that was evaluated
`decision`	EvaluationDecision	ALLOW, DENY, WARN, or REQUIRE_APPROVAL
`matched_rules`	RuleMatch[]	Rules that matched
`actions`	PolicyAction[]	Actions to execute
`message`	string	Human-readable result
`evaluation_duration_ms`	int64	Processing time

EvaluatePolicies

Evaluates multiple policies in priority order.

Method: EvaluatePolicies HTTP: POST /v1/policies/batch-evaluate

Request Schema

Field	Type	Required	Description
`policy_ids`	string[]	No	Policies to evaluate (empty = all active)
`context`	EvaluationContext	Yes	Execution context
`stop_on_deny`	bool	No	Stop at first DENY decision
`dry_run`	bool	No	If true, don't execute actions

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "context": {
      "tenant_id": "tenant-123",
      "phase": "EXECUTION_PHASE_PRE_LLM_CALL",
      "model_id": "gpt-4",
      "input_text": "Delete all files in /var/log"
    },
    "stop_on_deny": true
  }' \
  localhost:50051 fulcrum.policy.v1.PolicyService/EvaluatePolicies

Response

{
  "results": [
    {
      "policy_id": "pol-content-filter",
      "decision": "EVALUATION_DECISION_DENY",
      "matched_rules": [
        {
          "rule_id": "rule-dangerous-content",
          "rule_name": "Block Dangerous Operations",
          "matched_conditions": ["content.contains_delete_command"]
        }
      ],
      "actions": [
        {
          "action_type": "ACTION_TYPE_DENY",
          "message": "Content contains potentially dangerous operations",
          "severity": "SEVERITY_LEVEL_HIGH"
        }
      ],
      "evaluation_duration_ms": 12
    }
  ],
  "final_decision": "EVALUATION_DECISION_DENY",
  "actions": [
    {
      "action_type": "ACTION_TYPE_DENY",
      "message": "Content contains potentially dangerous operations",
      "severity": "SEVERITY_LEVEL_HIGH"
    }
  ]
}

GetEvaluationHistory

Retrieves historical policy evaluations.

Method: GetEvaluationHistory HTTP: GET /v1/policies/{policy_id}/evaluations

Request Schema

Field	Type	Required	Description
`policy_id`	string	Yes	Policy identifier
`start_time`	Timestamp	No	Start of time range
`end_time`	Timestamp	No	End of time range
`decision`	EvaluationDecision	No	Filter by decision
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "policy_id": "pol-abc123",
    "decision": "EVALUATION_DECISION_DENY",
    "page_size": 100
  }' \
  localhost:50051 fulcrum.policy.v1.PolicyService/GetEvaluationHistory

ListApprovals

Lists pending approval requests.

Method: ListApprovals HTTP: GET /v1/approvals

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`status`	string	No	Filter by status (PENDING, APPROVED, REJECTED)

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"tenant_id": "tenant-123", "status": "PENDING"}' \
  localhost:50051 fulcrum.policy.v1.PolicyService/ListApprovals

UpdateApproval

Approves or rejects a pending approval request.

Method: UpdateApproval HTTP: PATCH /v1/approvals/{approval_id}

Request Schema

Field	Type	Required	Description
`approval_id`	string	Yes	Approval identifier
`status`	string	Yes	APPROVED or REJECTED
`review_note`	string	No	Reviewer notes
`reviewer_id`	string	Yes	Reviewer identifier

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "approval_id": "apr-abc123",
    "status": "APPROVED",
    "review_note": "Verified by security team",
    "reviewer_id": "user-admin"
  }' \
  localhost:50051 fulcrum.policy.v1.PolicyService/UpdateApproval

CostService

Package: fulcrum.cost.v1 Description: Manages budgets and tracks AI execution costs.

CreateBudget

Creates a new budget for cost control.

Method: CreateBudget HTTP: POST /v1/budgets

Request Schema

Field	Type	Required	Description
`budget`	Budget	Yes	Budget definition

Budget Schema

Field	Type	Required	Description
`budget_id`	string	No	Auto-generated if not provided
`tenant_id`	string	Yes	Owning tenant
`workflow_id`	string	No	Scope to specific workflow
`limits`	BudgetLimits	Yes	Spending limits
`thresholds`	NotificationThreshold[]	No	Alert thresholds
`period`	BudgetPeriod	No	Reset cycle
`name`	string	No	Human-readable name
`description`	string	No	Budget description
`tags`	map	No	Metadata tags

BudgetLimits Schema

Field	Type	Description
`max_tokens`	int64	Total token limit (input + output)
`max_input_tokens`	int64	Input token limit
`max_output_tokens`	int64	Output token limit
`max_cost_usd`	double	Cost limit in USD
`max_llm_calls`	int32	LLM call count limit
`max_tool_calls`	int32	Tool call count limit
`max_execution_time_seconds`	int64	Execution time limit

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "budget": {
      "tenant_id": "tenant-123",
      "name": "Development Budget",
      "limits": {
        "max_tokens": 1000000,
        "max_cost_usd": 100.00,
        "max_llm_calls": 1000,
        "max_tool_calls": 500
      },
      "thresholds": [
        {"threshold_percent": 50},
        {"threshold_percent": 80},
        {"threshold_percent": 95}
      ],
      "period": {
        "period_type": "BUDGET_PERIOD_TYPE_MONTHLY"
      }
    }
  }' \
  localhost:50051 fulcrum.cost.v1.CostService/CreateBudget

GetBudget

Retrieves a budget by ID.

Method: GetBudget HTTP: GET /v1/budgets/{budget_id}

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"budget_id": "bdg-abc123"}' \
  localhost:50051 fulcrum.cost.v1.CostService/GetBudget

UpdateBudget

Updates an existing budget.

Method: UpdateBudget HTTP: PATCH /v1/budgets/{budget.budget_id}

Request Schema

Field	Type	Required	Description
`budget`	Budget	Yes	Updated budget
`update_mask`	string[]	No	Fields to update

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "budget": {
      "budget_id": "bdg-abc123",
      "limits": {
        "max_cost_usd": 200.00
      }
    },
    "update_mask": ["limits.max_cost_usd"]
  }' \
  localhost:50051 fulcrum.cost.v1.CostService/UpdateBudget

DeleteBudget

Deletes a budget.

Method: DeleteBudget HTTP: DELETE /v1/budgets/{budget_id}

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"budget_id": "bdg-abc123"}' \
  localhost:50051 fulcrum.cost.v1.CostService/DeleteBudget

ListBudgets

Lists budgets with filtering.

Method: ListBudgets HTTP: GET /v1/budgets

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant
`workflow_id`	string	No	Filter by workflow
`status`	BudgetStatusType	No	Filter by status
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "status": "BUDGET_STATUS_TYPE_WARNING"
  }' \
  localhost:50051 fulcrum.cost.v1.CostService/ListBudgets

GetCostSummary

Gets cost summary for a specific envelope.

Method: GetCostSummary HTTP: GET /v1/costs/{envelope_id}

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"envelope_id": "env-abc123"}' \
  localhost:50051 fulcrum.cost.v1.CostService/GetCostSummary

Response

{
  "cost_summary": {
    "total_input_tokens": 15420,
    "total_output_tokens": 8932,
    "total_cost_usd": 0.48,
    "llm_call_count": 12,
    "tool_call_count": 5,
    "model_costs": [
      {
        "model_id": "gpt-4",
        "input_tokens": 12000,
        "output_tokens": 6000,
        "cost_usd": 0.42,
        "call_count": 8
      },
      {
        "model_id": "gpt-3.5-turbo",
        "input_tokens": 3420,
        "output_tokens": 2932,
        "cost_usd": 0.06,
        "call_count": 4
      }
    ]
  }
}

GetSpendSummary

Gets aggregated spend for a tenant or workflow.

Method: GetSpendSummary HTTP: GET /v1/spend

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`workflow_id`	string	No	Filter by workflow
`start_time`	Timestamp	No	Start of time range
`end_time`	Timestamp	No	End of time range
`group_by`	SpendGroupBy	No	Grouping dimension

SpendGroupBy Values

Value	Description
`SPEND_GROUP_BY_MODEL`	Group by model
`SPEND_GROUP_BY_DAY`	Group by day
`SPEND_GROUP_BY_WEEK`	Group by week
`SPEND_GROUP_BY_MONTH`	Group by month
`SPEND_GROUP_BY_WORKFLOW`	Group by workflow

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "start_time": "2026-01-01T00:00:00Z",
    "end_time": "2026-01-31T23:59:59Z",
    "group_by": "SPEND_GROUP_BY_DAY"
  }' \
  localhost:50051 fulcrum.cost.v1.CostService/GetSpendSummary

GetBudgetStatus

Gets current budget consumption status.

Method: GetBudgetStatus HTTP: GET /v1/budgets/{budget_id}/status

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"budget_id": "bdg-abc123"}' \
  localhost:50051 fulcrum.cost.v1.CostService/GetBudgetStatus

Response

{
  "status": {
    "budget_id": "bdg-abc123",
    "status": "BUDGET_STATUS_TYPE_WARNING",
    "token_usage_percent": 82.5,
    "cost_usage_percent": 78.2,
    "llm_call_usage_percent": 65.0,
    "tool_call_usage_percent": 45.0,
    "remaining": {
      "max_tokens": 175000,
      "max_cost_usd": 21.80
    },
    "current_spend": {
      "total_tokens": 825000,
      "total_cost_usd": 78.20,
      "total_llm_calls": 650,
      "total_tool_calls": 225
    },
    "next_threshold": {
      "threshold_percent": 95
    }
  }
}

PredictCost

Predicts cost for a planned execution.

Method: PredictCost HTTP: POST /v1/costs/predict

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`workflow_id`	string	No	Workflow for historical data
`input_text`	string	No	Input text for estimation
`estimated_input_tokens`	int64	No	Estimated input tokens
`model_ids`	string[]	No	Expected models
`use_historical_data`	bool	No	Use historical patterns
`lookback_days`	int32	No	Days of history to analyze

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "workflow_id": "wf-data-analysis",
    "estimated_input_tokens": 5000,
    "model_ids": ["gpt-4"],
    "use_historical_data": true,
    "lookback_days": 30
  }' \
  localhost:50051 fulcrum.cost.v1.CostService/PredictCost

Response

{
  "prediction": {
    "estimated_input_tokens": 5000,
    "estimated_output_tokens": 3200,
    "estimated_total_tokens": 8200,
    "estimated_cost_usd": 0.24,
    "estimated_cost_usd_min": 0.18,
    "estimated_cost_usd_max": 0.35,
    "confidence": 0.85,
    "confidence_level": "high",
    "estimated_duration_seconds": 12
  },
  "historical_based": true,
  "sample_size": 156
}

CheckpointService

Package: fulcrum.checkpoint.v1 Description: Manages execution state persistence for recovery and debugging.

SaveCheckpoint

Saves an execution checkpoint.

Method: SaveCheckpoint HTTP: POST /v1/checkpoints

Request Schema

Field	Type	Required	Description
`checkpoint`	Checkpoint	Yes	Checkpoint data
`auto_version`	bool	No	Auto-increment version
`max_versions`	int32	No	Max versions to keep (0 = unlimited)

Checkpoint Schema

Field	Type	Required	Description
`checkpoint_id`	string	No	Auto-generated if not provided
`envelope_id`	string	Yes	Associated envelope
`execution_id`	string	Yes	Execution identifier
`tenant_id`	string	Yes	Tenant identifier
`version`	int32	No	Version number
`metadata`	CheckpointMetadata	No	Indexable metadata
`data`	Struct	Yes	Checkpoint state data

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "checkpoint": {
      "envelope_id": "env-abc123",
      "execution_id": "exec-789",
      "tenant_id": "tenant-123",
      "metadata": {
        "type": "CHECKPOINT_TYPE_AUTO",
        "framework_type": "langgraph",
        "current_node": "analyze_step",
        "cost_snapshot_usd": 0.15
      },
      "data": {
        "state": {"messages": [], "context": {}}
      }
    },
    "auto_version": true,
    "max_versions": 10
  }' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/SaveCheckpoint

GetCheckpoint

Retrieves a checkpoint.

Method: GetCheckpoint HTTP: GET /v1/checkpoints/{checkpoint_id}

Request Schema

Field	Type	Required	Description
`checkpoint_id`	string	Yes	Checkpoint identifier
`version`	int32	No	Specific version (default: latest)

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"checkpoint_id": "chk-abc123"}' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/GetCheckpoint

ListCheckpoints

Lists checkpoints with filtering.

Method: ListCheckpoints HTTP: GET /v1/checkpoints

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant
`envelope_id`	string	No	Filter by envelope
`execution_id`	string	No	Filter by execution
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token
`order_by`	string	No	Sort order (e.g., "created_at desc")

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "execution_id": "exec-789",
    "page_size": 20,
    "order_by": "created_at desc"
  }' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/ListCheckpoints

DeleteCheckpoint

Deletes a checkpoint.

Method: DeleteCheckpoint HTTP: DELETE /v1/checkpoints/{checkpoint_id}

Request Schema

Field	Type	Required	Description
`checkpoint_id`	string	Yes	Checkpoint identifier
`soft_delete`	bool	No	Mark deleted but keep data
`delete_all_versions`	bool	No	Delete entire version chain

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"checkpoint_id": "chk-abc123", "delete_all_versions": true}' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/DeleteCheckpoint

ListCheckpointVersions

Lists all versions of a checkpoint.

Method: ListCheckpointVersions HTTP: GET /v1/checkpoints/{execution_id}/versions

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"execution_id": "exec-789"}' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/ListCheckpointVersions

GetCheckpointVersion

Gets a specific checkpoint version.

Method: GetCheckpointVersion HTTP: GET /v1/checkpoints/{execution_id}/versions/{version}

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"execution_id": "exec-789", "version": 3}' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/GetCheckpointVersion

QueryCheckpoints

Queries checkpoints with advanced filters.

Method: QueryCheckpoints HTTP: POST /v1/checkpoints:query

Request Schema

Field	Type	Required	Description
`query`	CheckpointQuery	Yes	Query filters
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token
`order_by`	string	No	Sort order

CheckpointQuery Schema

Field	Type	Description
`tenant_ids`	string[]	Filter by tenants
`envelope_ids`	string[]	Filter by envelopes
`execution_ids`	string[]	Filter by executions
`types`	CheckpointType[]	Filter by checkpoint type
`created_after`	Timestamp	Created after timestamp
`created_before`	Timestamp	Created before timestamp
`framework_types`	string[]	Filter by framework
`tags`	map	Filter by tags (AND logic)
`min_cost_usd`	double	Minimum cost
`max_cost_usd`	double	Maximum cost
`min_size_bytes`	int64	Minimum size
`max_size_bytes`	int64	Maximum size

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "query": {
      "tenant_ids": ["tenant-123"],
      "types": ["CHECKPOINT_TYPE_ERROR", "CHECKPOINT_TYPE_PRE_TERMINATE"],
      "created_after": "2026-01-01T00:00:00Z",
      "min_cost_usd": 1.00
    },
    "page_size": 50
  }' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/QueryCheckpoints

GetExecutionContext

Gets cross-execution shared state.

Method: GetExecutionContext HTTP: GET /v1/executions/{execution_id}/context

Request Schema

Field	Type	Required	Description
`execution_id`	string	Yes	Execution identifier
`keys`	string[]	No	Specific keys to retrieve
`include_inherited`	bool	No	Include inherited context

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "execution_id": "exec-789",
    "include_inherited": true
  }' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/GetExecutionContext

UpdateExecutionContext

Updates execution context with merge strategies.

Method: UpdateExecutionContext HTTP: PUT /v1/executions/{execution_id}/context

Request Schema

Field	Type	Required	Description
`execution_id`	string	Yes	Execution identifier
`updates`	Struct	Yes	Updates to apply
`delete_keys`	string[]	No	Keys to delete
`expected_version`	int64	No	For optimistic locking
`merge_strategy`	MergeStrategy	No	Conflict resolution

MergeStrategy Values

Value	Description
`MERGE_STRATEGY_LAST_WRITE_WINS`	Last write wins
`MERGE_STRATEGY_FAIL_ON_CONFLICT`	Fail if conflict detected
`MERGE_STRATEGY_MERGE_RECURSIVE`	Deep merge
`MERGE_STRATEGY_CUSTOM`	Custom handler

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "execution_id": "exec-789",
    "updates": {
      "user_preferences": {"theme": "dark"},
      "session_data": {"last_action": "analyze"}
    },
    "merge_strategy": "MERGE_STRATEGY_MERGE_RECURSIVE"
  }' \
  localhost:50051 fulcrum.checkpoint.v1.CheckpointService/UpdateExecutionContext

TenantService

Package: fulcrum.tenant.v1 Description: Manages tenant API keys and authentication.

CreateApiKey

Creates a new API key.

Method: CreateApiKey

Request Schema

Field	Type	Required	Description
`name`	string	Yes	Key name/description
`scopes`	string[]	No	Permission scopes
`expires_in_seconds`	int64	No	TTL (0 = never expires)

Available Scopes

Scope	Description
`envelopes:read`	Read envelope data
`envelopes:write`	Create/update envelopes
`policies:read`	Read policies
`policies:write`	Create/update policies
`budgets:read`	Read budget data
`budgets:write`	Create/update budgets
`checkpoints:read`	Read checkpoints
`checkpoints:write`	Create/update checkpoints
`events:read`	Read events
`admin`	Full administrative access

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_admin_..." \
  -d '{
    "name": "Production API Key",
    "scopes": ["envelopes:read", "envelopes:write", "policies:read"],
    "expires_in_seconds": 31536000
  }' \
  localhost:50051 fulcrum.tenant.v1.TenantService/CreateApiKey

Response

{
  "key": {
    "id": "key-abc123",
    "name": "Production API Key",
    "key_hint": "flcrm...x7k2",
    "scopes": ["envelopes:read", "envelopes:write", "policies:read"],
    "expires_at": "2027-01-06T10:00:00Z",
    "created_at": "2026-01-06T10:00:00Z"
  },
  "key_secret": "flcrm_sk_prod_abc123xyz789..."
}

Warning: The key_secret is only returned once. Store it securely.

ListApiKeys

Lists all API keys for the tenant.

Method: ListApiKeys

Request Schema

Field	Type	Required	Description
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"page_size": 50}' \
  localhost:50051 fulcrum.tenant.v1.TenantService/ListApiKeys

RevokeApiKey

Revokes an API key.

Method: RevokeApiKey

Request Schema

Field	Type	Required	Description
`key_id`	string	Yes	Key identifier

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"key_id": "key-abc123"}' \
  localhost:50051 fulcrum.tenant.v1.TenantService/RevokeApiKey

EventStoreService

Package: fulcrum.eventstore.v1 Description: Persists and queries execution events backed by NATS JetStream.

PublishEvent

Publishes a single event.

Method: PublishEvent

Request Schema

Field	Type	Required	Description
`event`	EventPayload	Yes	Event to publish

EventPayload Schema

Field	Type	Required	Description
`execution_id`	string	Yes	Execution identifier
`envelope_id`	string	Yes	Envelope identifier
`tenant_id`	string	Yes	Tenant identifier
`workflow_id`	string	No	Workflow identifier
`event_type`	string	Yes	Event type (see Event Types)
`timestamp`	Timestamp	Yes	Event timestamp
`payload`	Struct	Yes	Event-specific data
`trace_id`	string	No	W3C trace ID
`span_id`	string	No	W3C span ID
`labels`	map	No	Filtering labels

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "event": {
      "execution_id": "exec-789",
      "envelope_id": "env-abc123",
      "tenant_id": "tenant-123",
      "event_type": "llm_call_completed",
      "timestamp": "2026-01-06T10:05:00Z",
      "payload": {
        "model_id": "gpt-4",
        "input_tokens": 1500,
        "output_tokens": 800,
        "latency_ms": 2340
      },
      "labels": {
        "model": "gpt-4",
        "workflow": "analysis"
      }
    }
  }' \
  localhost:50051 fulcrum.eventstore.v1.EventStoreService/PublishEvent

PublishEventBatch

Publishes multiple events atomically.

Method: PublishEventBatch

Request Schema

Field	Type	Required	Description
`events`	EventPayload[]	Yes	Events to publish

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "events": [
      {"execution_id": "exec-789", "event_type": "tool_invoked", ...},
      {"execution_id": "exec-789", "event_type": "tool_completed", ...}
    ]
  }' \
  localhost:50051 fulcrum.eventstore.v1.EventStoreService/PublishEventBatch

QueryEvents

Queries events with filters.

Method: QueryEvents

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant
`execution_id`	string	No	Filter by execution
`workflow_id`	string	No	Filter by workflow
`event_type`	string	No	Filter by event type
`start_time`	Timestamp	No	Start of time range
`end_time`	Timestamp	No	End of time range
`labels`	map	No	Filter by labels
`limit`	int32	No	Max results (default: 100, max: 1000)
`page_token`	string	No	Pagination token
`order`	OrderDirection	No	ASCENDING or DESCENDING

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "event_type": "policy_violation",
    "start_time": "2026-01-01T00:00:00Z",
    "limit": 100,
    "order": "ORDER_DIRECTION_DESCENDING"
  }' \
  localhost:50051 fulcrum.eventstore.v1.EventStoreService/QueryEvents

GetExecutionEvents

Gets all events for a specific execution.

Method: GetExecutionEvents

Request Schema

Field	Type	Required	Description
`execution_id`	string	Yes	Execution identifier
`event_type`	string	No	Filter by type
`start_time`	Timestamp	No	Start time
`end_time`	Timestamp	No	End time
`limit`	int32	No	Max results
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"execution_id": "exec-789"}' \
  localhost:50051 fulcrum.eventstore.v1.EventStoreService/GetExecutionEvents

StreamEvents

Streams events in real-time.

Method: StreamEvents (Server Streaming)

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant
`execution_id`	string	No	Filter by execution
`workflow_id`	string	No	Filter by workflow
`event_type`	string	No	Filter by event type
`start_sequence`	int64	No	Start from sequence number
`start_time`	Timestamp	No	Start from timestamp
`labels`	map	No	Filter by labels

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"tenant_id": "tenant-123", "event_type": "budget_warning"}' \
  localhost:50051 fulcrum.eventstore.v1.EventStoreService/StreamEvents

GetEventStoreStats

Gets event store statistics.

Method: GetEventStoreStats

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"tenant_id": "tenant-123"}' \
  localhost:50051 fulcrum.eventstore.v1.EventStoreService/GetEventStoreStats

Response

{
  "total_events": 1548923,
  "events_by_type": {
    "llm_call_completed": 523421,
    "tool_invoked": 312456,
    "checkpoint_created": 89234
  },
  "storage_bytes": 2147483648,
  "oldest_event": "2025-06-01T00:00:00Z",
  "newest_event": "2026-01-06T10:00:00Z",
  "streams": [
    {
      "stream_name": "FULCRUM_EVENTS_tenant-123",
      "message_count": 1548923,
      "bytes": 2147483648
    }
  ]
}

SemanticJudgeService

Package: fulcrum.brain.v1 Description: LLM-based policy evaluation with intent detection. Target: <50ms P99 latency, >95% accuracy.

EvaluateCondition

Evaluates a policy condition using semantic analysis.

Method: EvaluateCondition HTTP: POST /v1/brain/semantic-judge/evaluate

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`condition`	PolicyCondition	Yes	Condition to evaluate
`context`	EvaluationContext	Yes	Execution context
`fallback_enabled`	bool	No	Use deterministic fallback on LLM failure

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "condition": {
      "condition_type": "CONDITION_TYPE_SEMANTIC",
      "semantic_intent": "User is attempting to access sensitive financial data",
      "semantic_model": "llama3.2",
      "semantic_confidence_threshold": 0.8
    },
    "context": {
      "tenant_id": "tenant-123",
      "input_text": "Show me all credit card numbers from the customer database"
    },
    "fallback_enabled": true
  }' \
  localhost:50051 fulcrum.brain.v1.SemanticJudgeService/EvaluateCondition

Response

{
  "matches": true,
  "reason": "Input requests access to sensitive financial data (credit card numbers)",
  "method": "EVALUATION_METHOD_LLM",
  "latency_ms": 42,
  "confidence": 0.94
}

ClassifyRisk

Classifies the risk level of an agent action.

Method: ClassifyRisk HTTP: POST /v1/brain/semantic-judge/classify-risk

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`tool_name`	string	Yes	Tool being invoked
`action`	string	Yes	Action being performed
`parameters`	map	No	Action parameters
`context_description`	string	No	Additional context

RiskLevel Values

Value	Description
`RISK_LEVEL_LOW`	Safe operation
`RISK_LEVEL_MEDIUM`	Caution advised
`RISK_LEVEL_HIGH`	Requires review
`RISK_LEVEL_CRITICAL`	Immediate escalation

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "tool_name": "file_system",
    "action": "delete",
    "parameters": {
      "path": "/var/log/*",
      "recursive": "true"
    }
  }' \
  localhost:50051 fulcrum.brain.v1.SemanticJudgeService/ClassifyRisk

Response

{
  "risk_level": "RISK_LEVEL_CRITICAL",
  "reasoning": "Recursive deletion of system log directory could cause data loss and compliance issues",
  "risk_factors": [
    "Recursive file deletion",
    "System directory target",
    "Wildcard pattern usage"
  ],
  "confidence": 0.97,
  "latency_ms": 38
}

DeriveIntent

Derives intent from a pattern signature (used by Immune System).

Method: DeriveIntent HTTP: POST /v1/brain/semantic-judge/derive-intent

Request Schema

Field	Type	Required	Description
`pattern_signature`	string	Yes	Attack pattern signature
`indicators`	string[]	Yes	Pattern indicators
`tenant_id`	string	No	Tenant context

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "pattern_signature": "RAPID_TOOL_EXEC_FILE_DELETE",
    "indicators": [
      "10+ file deletions in 60s",
      "System directory targets",
      "Escalating path depth"
    ]
  }' \
  localhost:50051 fulcrum.brain.v1.SemanticJudgeService/DeriveIntent

Response

{
  "intent": "Systematic file system cleanup or potential data destruction attack",
  "confidence": 0.89,
  "latency_ms": 45
}

OracleService

Package: fulcrum.brain.v1 Description: Predictive cost modeling - Fulcrum's unique differentiator. Predicts budget overruns before they happen.

PredictBudgetOverrun

Predicts probability of budget overrun.

Method: PredictBudgetOverrun HTTP: POST /v1/brain/oracle/predict-overrun

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`workflow_id`	string	Yes	Workflow identifier
`budget_id`	string	Yes	Budget identifier

RecommendedAction Values

Value	Description
`RECOMMENDED_ACTION_NONE`	No action needed
`RECOMMENDED_ACTION_WARN`	Issue warning
`RECOMMENDED_ACTION_REDUCE_RATE`	Slow down execution
`RECOMMENDED_ACTION_REQUEST_QUOTA`	Request additional budget
`RECOMMENDED_ACTION_HALT`	Stop execution

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "workflow_id": "wf-data-analysis",
    "budget_id": "bdg-monthly"
  }' \
  localhost:50051 fulcrum.brain.v1.OracleService/PredictBudgetOverrun

Response

{
  "budget_id": "bdg-monthly",
  "predicted_cost": 145.50,
  "remaining_budget": 54.50,
  "overrun_probability": 0.78,
  "recommended_action": "RECOMMENDED_ACTION_WARN",
  "confidence": 0.92,
  "model": {
    "tenant_id": "tenant-123",
    "workflow_id": "wf-data-analysis",
    "avg_cost_per_run": 2.35,
    "std_dev_cost_per_run": 0.85,
    "avg_tokens_per_run": 12500,
    "runs_per_hour": 4.2,
    "sample_size": 1245
  }
}

GetPredictionModel

Gets or builds a prediction model for a workflow.

Method: GetPredictionModel HTTP: GET /v1/brain/oracle/models/{tenant_id}/{workflow_id}

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`workflow_id`	string	Yes	Workflow identifier
`force_rebuild`	bool	No	Rebuild from fresh data

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "workflow_id": "wf-data-analysis"
  }' \
  localhost:50051 fulcrum.brain.v1.OracleService/GetPredictionModel

ListPredictionModels

Lists all prediction models for a tenant.

Method: ListPredictionModels HTTP: GET /v1/brain/oracle/models/{tenant_id}

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"tenant_id": "tenant-123", "page_size": 50}' \
  localhost:50051 fulcrum.brain.v1.OracleService/ListPredictionModels

ImmuneSystemService

Package: fulcrum.brain.v1 Description: Automated policy generation from incident patterns. Self-healing governance that learns from attacks.

ReportIncident

Reports an incident for the immune system to learn from.

Method: ReportIncident HTTP: POST /v1/brain/immune-system/incidents

Request Schema

Field	Type	Required	Description
`incident`	Incident	Yes	Incident details

Incident Schema

Field	Type	Required	Description
`incident_id`	string	No	Auto-generated if not provided
`tenant_id`	string	Yes	Tenant identifier
`timestamp`	Timestamp	Yes	When incident occurred
`severity`	IncidentSeverity	Yes	Incident severity
`category`	IncidentCategory	Yes	Incident category
`description`	string	Yes	Human-readable description
`details`	map	No	Additional details

IncidentSeverity Values

Value	Description
`INCIDENT_SEVERITY_LOW`	Minor issue
`INCIDENT_SEVERITY_MEDIUM`	Moderate concern
`INCIDENT_SEVERITY_HIGH`	Significant threat
`INCIDENT_SEVERITY_CRITICAL`	Immediate action required

IncidentCategory Values

Value	Description
`INCIDENT_CATEGORY_BUDGET_OVERRUN`	Budget exceeded
`INCIDENT_CATEGORY_POLICY_VIOLATION`	Policy rule triggered
`INCIDENT_CATEGORY_SECURITY_BREACH`	Security incident
`INCIDENT_CATEGORY_RATE_LIMIT_EXCEEDED`	Rate limit hit
`INCIDENT_CATEGORY_ANOMALY_DETECTED`	Unusual behavior

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "incident": {
      "tenant_id": "tenant-123",
      "timestamp": "2026-01-06T10:15:00Z",
      "severity": "INCIDENT_SEVERITY_HIGH",
      "category": "INCIDENT_CATEGORY_SECURITY_BREACH",
      "description": "Detected prompt injection attempt in user input",
      "details": {
        "envelope_id": "env-abc123",
        "input_pattern": "ignore previous instructions",
        "blocked_by": "policy-prompt-injection"
      }
    }
  }' \
  localhost:50051 fulcrum.brain.v1.ImmuneSystemService/ReportIncident

Response

{
  "incident_id": "inc-xyz789",
  "generated_policy": {
    "policy": {
      "name": "Auto-Block: Prompt Injection Pattern #47",
      "rules": [...],
      "enforcement": "ENFORCEMENT_LEVEL_BLOCK"
    },
    "source_pattern": {
      "pattern_id": "pat-injection-47",
      "signature": "PROMPT_INJECTION_IGNORE_INSTRUCTIONS",
      "frequency": 12
    },
    "reasoning": "Pattern detected 12 times across 3 tenants in past 24h",
    "approval_required": true,
    "status": "GENERATED_POLICY_STATUS_PENDING"
  },
  "pattern": {
    "pattern_id": "pat-injection-47",
    "signature": "PROMPT_INJECTION_IGNORE_INSTRUCTIONS",
    "frequency": 12,
    "indicators": ["ignore previous", "disregard instructions", "new persona"],
    "first_seen": "2026-01-05T08:00:00Z",
    "last_seen": "2026-01-06T10:15:00Z"
  }
}

GetAttackPatterns

Gets detected attack patterns.

Method: GetAttackPatterns HTTP: GET /v1/brain/immune-system/patterns

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant
`min_frequency`	int32	No	Minimum occurrence count
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"min_frequency": 5, "page_size": 20}' \
  localhost:50051 fulcrum.brain.v1.ImmuneSystemService/GetAttackPatterns

GetPendingPolicies

Gets auto-generated policies pending approval.

Method: GetPendingPolicies HTTP: GET /v1/brain/immune-system/policies/pending

Request Schema

Field	Type	Required	Description
`tenant_id`	string	No	Filter by tenant
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{"tenant_id": "tenant-123"}' \
  localhost:50051 fulcrum.brain.v1.ImmuneSystemService/GetPendingPolicies

ReviewGeneratedPolicy

Approves or rejects an auto-generated policy.

Method: ReviewGeneratedPolicy HTTP: POST /v1/brain/immune-system/policies/{policy_id}/review

Request Schema

Field	Type	Required	Description
`policy_id`	string	Yes	Policy identifier
`decision`	ReviewDecision	Yes	APPROVE, REJECT, or MODIFY
`reviewer_id`	string	Yes	Reviewer identifier
`review_notes`	string	No	Review comments

ReviewDecision Values

Value	Description
`REVIEW_DECISION_APPROVE`	Approve and activate
`REVIEW_DECISION_REJECT`	Reject policy
`REVIEW_DECISION_MODIFY`	Request modifications

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "policy_id": "pol-auto-abc123",
    "decision": "REVIEW_DECISION_APPROVE",
    "reviewer_id": "user-security-admin",
    "review_notes": "Verified pattern, approved for production"
  }' \
  localhost:50051 fulcrum.brain.v1.ImmuneSystemService/ReviewGeneratedPolicy

ListIncidents

Lists all incidents for a tenant.

Method: ListIncidents HTTP: GET /v1/brain/immune-system/incidents

Request Schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant identifier
`min_severity`	IncidentSeverity	No	Filter by minimum severity
`category`	IncidentCategory	No	Filter by category
`start_time`	Timestamp	No	Start of time range
`end_time`	Timestamp	No	End of time range
`page_size`	int32	No	Results per page
`page_token`	string	No	Pagination token

Example

grpcurl -plaintext \
  -H "Authorization: Bearer flcrm_sk_..." \
  -d '{
    "tenant_id": "tenant-123",
    "min_severity": "INCIDENT_SEVERITY_HIGH",
    "start_time": "2026-01-01T00:00:00Z"
  }' \
  localhost:50051 fulcrum.brain.v1.ImmuneSystemService/ListIncidents

Common Types

ExecutionEnvelope

The core abstraction - every agent execution is wrapped in an envelope.

Field	Type	Description
`envelope_id`	string	Unique identifier
`tenant_id`	string	Tenant isolation
`workflow_id`	string	Optional workflow grouping
`execution_id`	string	Unique per run
`governance`	GovernanceContext	Budget and policy constraints
`framework`	FrameworkContext	Framework-specific context
`status`	EnvelopeStatus	Lifecycle state
`events`	FulcrumEvent[]	Accumulated events
`cost`	CostSummary	Cost tracking
`created_at`	Timestamp	Creation time
`updated_at`	Timestamp	Last update time
`completed_at`	Timestamp	Completion time
`parent_envelope_id`	string	Parent for sub-executions
`metadata`	map	Extensible metadata
`trace_context`	map	W3C Trace Context

EnvelopeStatus

Value	Description
`ENVELOPE_STATUS_PENDING`	Created, not yet authorized
`ENVELOPE_STATUS_AUTHORIZED`	Passed policy check, ready to run
`ENVELOPE_STATUS_RUNNING`	Currently executing
`ENVELOPE_STATUS_PAUSED`	Suspended (human-in-the-loop)
`ENVELOPE_STATUS_COMPLETED`	Successfully finished
`ENVELOPE_STATUS_FAILED`	Error during execution
`ENVELOPE_STATUS_TERMINATED`	Forcefully stopped
`ENVELOPE_STATUS_BUDGET_EXCEEDED`	Killed due to budget
`ENVELOPE_STATUS_POLICY_VIOLATION`	Killed due to policy
`ENVELOPE_STATUS_TIMEOUT`	Killed due to timeout

GovernanceContext

Field	Type	Description
`budget_id`	string	Budget reference
`token_budget`	int64	Max tokens allowed
`cost_limit_usd`	double	Max cost in USD
`timeout_seconds`	int64	Max execution time
`policy_set_id`	string	Policy ruleset reference
`allowed_models`	string[]	Permitted models
`allowed_tools`	string[]	Permitted tools
`max_llm_calls`	int32	LLM call limit
`max_tool_calls`	int32	Tool call limit
`compliance_tags`	string[]	e.g., "pii-handling", "hipaa"

FrameworkType

Value	Description
`FRAMEWORK_TYPE_LANGGRAPH`	LangGraph/LangChain
`FRAMEWORK_TYPE_MICROSOFT`	Microsoft Semantic Kernel
`FRAMEWORK_TYPE_CREWAI`	CrewAI
`FRAMEWORK_TYPE_AUTOGEN`	AutoGen
`FRAMEWORK_TYPE_A2A_PROXY`	Agent-to-Agent Proxy
`FRAMEWORK_TYPE_CUSTOM`	Custom framework

PolicyStatus

Value	Description
`POLICY_STATUS_DRAFT`	Policy in draft
`POLICY_STATUS_ACTIVE`	Policy active
`POLICY_STATUS_INACTIVE`	Policy disabled
`POLICY_STATUS_ARCHIVED`	Policy archived

EnforcementLevel

Value	Description
`ENFORCEMENT_LEVEL_AUDIT`	Log only, don't block
`ENFORCEMENT_LEVEL_WARN`	Warn but allow
`ENFORCEMENT_LEVEL_BLOCK`	Block execution
`ENFORCEMENT_LEVEL_TERMINATE`	Terminate immediately

RuleType

Value	Description
`RULE_TYPE_RBAC`	Role-based access control
`RULE_TYPE_CONTENT_FILTER`	Content filtering
`RULE_TYPE_TOOL_ALLOWLIST`	Tool access control
`RULE_TYPE_MODEL_RESTRICTION`	Model usage restrictions
`RULE_TYPE_RATE_LIMIT`	Rate limiting
`RULE_TYPE_COST_CONTROL`	Cost-based controls
`RULE_TYPE_CUSTOM`	Custom rule type

ConditionType

Value	Description
`CONDITION_TYPE_FIELD_MATCH`	Simple field comparison
`CONDITION_TYPE_REGEX`	Regex pattern matching
`CONDITION_TYPE_RANGE`	Numeric range
`CONDITION_TYPE_IN_LIST`	Value in list
`CONDITION_TYPE_CONTAINS`	String contains
`CONDITION_TYPE_STARTS_WITH`	String starts with
`CONDITION_TYPE_ENDS_WITH`	String ends with
`CONDITION_TYPE_LOGICAL`	AND/OR of nested conditions
`CONDITION_TYPE_STATISTICAL_SPIKE`	Deviation from baseline
`CONDITION_TYPE_EXTERNAL_CALL`	External API/DB lookup
`CONDITION_TYPE_SEMANTIC`	LLM-based evaluation

ActionType

Value	Description
`ACTION_TYPE_ALLOW`	Allow execution
`ACTION_TYPE_DENY`	Block execution
`ACTION_TYPE_WARN`	Warn but allow
`ACTION_TYPE_MODIFY`	Modify request
`ACTION_TYPE_REDIRECT`	Redirect to different model/tool
`ACTION_TYPE_AUDIT`	Log for audit
`ACTION_TYPE_THROTTLE`	Rate limit
`ACTION_TYPE_REQUIRE_APPROVAL`	Require human approval
`ACTION_TYPE_NOTIFY`	Notify external service

ExecutionPhase

Value	Description
`EXECUTION_PHASE_PRE_EXECUTION`	Before execution starts
`EXECUTION_PHASE_PRE_LLM_CALL`	Before each LLM call
`EXECUTION_PHASE_POST_LLM_CALL`	After each LLM call
`EXECUTION_PHASE_PRE_TOOL_CALL`	Before each tool call
`EXECUTION_PHASE_POST_TOOL_CALL`	After each tool call
`EXECUTION_PHASE_POST_EXECUTION`	After execution completes

BudgetPeriodType

Value	Description
`BUDGET_PERIOD_TYPE_HOURLY`	Hourly reset
`BUDGET_PERIOD_TYPE_DAILY`	Daily reset
`BUDGET_PERIOD_TYPE_WEEKLY`	Weekly reset
`BUDGET_PERIOD_TYPE_MONTHLY`	Monthly reset
`BUDGET_PERIOD_TYPE_QUARTERLY`	Quarterly reset
`BUDGET_PERIOD_TYPE_YEARLY`	Yearly reset
`BUDGET_PERIOD_TYPE_CUSTOM`	Custom duration
`BUDGET_PERIOD_TYPE_INFINITE`	Never resets

CheckpointType

Value	Description
`CHECKPOINT_TYPE_MANUAL`	User-triggered
`CHECKPOINT_TYPE_AUTO`	Auto-save interval
`CHECKPOINT_TYPE_PRE_TERMINATE`	Before termination
`CHECKPOINT_TYPE_ERROR`	On error for debugging
`CHECKPOINT_TYPE_MILESTONE`	At important execution points

Event Types

Fulcrum normalizes all framework events into a standard schema.

EventType Enum

Value	Description
Execution Lifecycle
`EVENT_TYPE_EXECUTION_STARTED`	Execution began
`EVENT_TYPE_EXECUTION_COMPLETED`	Execution finished successfully
`EVENT_TYPE_EXECUTION_FAILED`	Execution failed
`EVENT_TYPE_EXECUTION_PAUSED`	Execution paused
`EVENT_TYPE_EXECUTION_RESUMED`	Execution resumed
`EVENT_TYPE_EXECUTION_TERMINATED`	Execution terminated
LLM Interactions
`EVENT_TYPE_LLM_CALL_STARTED`	LLM call initiated
`EVENT_TYPE_LLM_CALL_COMPLETED`	LLM call completed
`EVENT_TYPE_LLM_CALL_FAILED`	LLM call failed
`EVENT_TYPE_LLM_STREAMING_CHUNK`	Streaming token received
Tool Interactions
`EVENT_TYPE_TOOL_INVOKED`	Tool invoked
`EVENT_TYPE_TOOL_COMPLETED`	Tool completed
`EVENT_TYPE_TOOL_FAILED`	Tool failed
Checkpointing
`EVENT_TYPE_CHECKPOINT_CREATED`	Checkpoint saved
`EVENT_TYPE_CHECKPOINT_RESTORED`	Checkpoint restored
Budget Events
`EVENT_TYPE_BUDGET_WARNING`	80% threshold reached
`EVENT_TYPE_BUDGET_EXCEEDED`	Budget limit reached
`EVENT_TYPE_BUDGET_RESET`	Budget period reset
Policy Events
`EVENT_TYPE_POLICY_EVALUATED`	Policy evaluated
`EVENT_TYPE_POLICY_VIOLATION`	Policy violation
`EVENT_TYPE_POLICY_WARNING`	Policy warning
Multi-Agent
`EVENT_TYPE_AGENT_HANDOFF`	Agent handoff
`EVENT_TYPE_AGENT_SPAWN`	Sub-agent spawned
`EVENT_TYPE_AGENT_JOIN`	Agent joined
Custom
`EVENT_TYPE_CUSTOM`	Custom event type

EventSeverity

Value	Description
`EVENT_SEVERITY_DEBUG`	Debug information
`EVENT_SEVERITY_INFO`	Informational
`EVENT_SEVERITY_WARNING`	Warning
`EVENT_SEVERITY_ERROR`	Error
`EVENT_SEVERITY_CRITICAL`	Critical alert

Bridge Protocol

Package: fulcrum.bridge.v1 Description: Protocol for Python-Go communication (LangGraph adapter).

Message Types

The bridge uses protobuf for high-performance serialization between Python and Go.

ExecutionRequest

Initiates a LangGraph StateGraph execution.

Field	Type	Description
`envelope_id`	string	Execution envelope ID
`state_graph`	bytes	Pickled LangGraph StateGraph
`config`	map	Execution configuration
`enable_callbacks`	bool	Enable event streaming
`initial_state`	bytes	JSON-encoded initial state

CallbackEvent

Streams execution events from Python to Go.

Field	Type	Description
`envelope_id`	string	Envelope identifier
`timestamp_ns`	int64	Unix nanoseconds
`event`	oneof	Event payload (see below)

Event Types: - LLMStartEvent - LLM call initiated - LLMEndEvent - LLM call completed with tokens/cost - LLMErrorEvent - LLM call failed - ToolStartEvent - Tool invocation started - ToolEndEvent - Tool invocation completed - ToolErrorEvent - Tool invocation failed - ChainStartEvent - StateGraph node started - ChainEndEvent - StateGraph node completed - StreamingChunkEvent - Streaming token chunk - ErrorEvent - Execution error - CompleteEvent - Execution completed

TerminateRequest

Requests execution termination.

Field	Type	Description
`envelope_id`	string	Envelope to terminate
`reason`	string	Termination reason
`force`	bool	Force kill if graceful fails
`timeout_ms`	int64	Graceful shutdown timeout

CheckpointRequest

Requests current execution state.

Field	Type	Description
`envelope_id`	string	Envelope identifier
`include_state`	bool	Include full state

HealthCheckRequest/Response

Pings Python process health.

Field	Type	Description
`healthy`	bool	Process is healthy
`pid`	int32	Process ID
`uptime_seconds`	int64	Uptime
`memory_bytes`	int64	Memory usage

Appendix: Complete Type Reference

Proto File Locations

Package	File
fulcrum.envelope.v1	`proto/fulcrum/envelope/v1/envelope.proto`
fulcrum.envelope.v1	`proto/fulcrum/envelope/v1/envelope_service.proto`
fulcrum.policy.v1	`proto/fulcrum/policy/v1/policy_service.proto`
fulcrum.cost.v1	`proto/fulcrum/cost/v1/cost_service.proto`
fulcrum.checkpoint.v1	`proto/fulcrum/checkpoint/v1/checkpoint_service.proto`
fulcrum.tenant.v1	`proto/fulcrum/tenant/v1/tenant_service.proto`
fulcrum.events.v1	`proto/fulcrum/events/v1/events.proto`
fulcrum.eventstore.v1	`proto/fulcrum/eventstore/v1/eventstore.proto`
fulcrum.brain.v1	`proto/fulcrum/brain/v1/brain_service.proto`
fulcrum.bridge.v1	`proto/fulcrum/bridge/v1/bridge.proto`

Generating Client Code

# Go
buf generate

# Python
python -m grpc_tools.protoc \
  -I proto \
  --python_out=. \
  --grpc_python_out=. \
  proto/fulcrum/**/*.proto

# TypeScript
npx grpc_tools_node_protoc \
  --ts_out=grpc_js:. \
  --grpc_out=grpc_js:. \
  -I proto \
  proto/fulcrum/**/*.proto

Performance Targets

Operation	Target	P99
Policy Evaluation	<10ms	<15ms
Semantic Judge	<50ms	<75ms
Envelope Creation	<5ms	<10ms
Budget Check	<2ms	<5ms
Event Publish	<1ms	<3ms

Version History

Version	Date	Changes
2.0.0	2026-01-03	Brain services added, semantic conditions
1.0.0	2025-06-01	Initial stable release

Last Updated: January 6, 2026 API Version: 2.0.0 Status: Production

Fulcrum gRPC API Reference

Table of Contents

Overview

Base Configuration

Proto Package Structure

Connecting to Fulcrum

Authentication

API Key Authentication

Tenant Context

Error Handling

Standard Error Codes

Error Response Format

Services

EnvelopeService

CreateEnvelope

Request Schema

Response Schema

Example

Response Example

GetEnvelope

Request Schema

Example

UpdateEnvelopeStatus

Request Schema

Valid Status Transitions

Example

PolicyService

CreatePolicy

Request Schema

Policy Schema

Example

GetPolicy

Example

UpdatePolicy

Request Schema

Example

DeletePolicy

Example

ListPolicies

Request Schema

Example

EvaluatePolicy

Request Schema

EvaluationContext Schema

Example

Response Schema

EvaluationResult Fields

EvaluatePolicies

Request Schema

Example

Response

GetEvaluationHistory

Request Schema

Example

ListApprovals

Request Schema

Example

UpdateApproval

Request Schema

Example

CostService

CreateBudget

Request Schema

Budget Schema

BudgetLimits Schema

Example

GetBudget

Example

UpdateBudget

Request Schema

Example

DeleteBudget

Example

ListBudgets

Request Schema

Example

GetCostSummary

Example

Response

GetSpendSummary