Resource-oriented REST
Projects, campaigns, runs, claims, datasets, and ledger entries are stable, addressable resources with predictable URL patterns—agents and services integrate without bespoke adapters.
HTTP API
REST API Reference
The AI-native HTTP interface for ARDA. Discover governing equations, causal structures, and conservation laws from scientific data through a predictable, resource-oriented API designed for both autonomous agents and human-driven integrations.
Dual authentication
Tenant-scoped API keys for machine clients and OAuth session tokens for human users—both produce the same authorization context and are fully auditable through the Evidence Ledger.
Typed claim payloads
Responses surface LawClaim, CausalClaim, and ConservationClaim types with confidence scores, scope boundaries, and ledger references so downstream consumers never re-infer semantics from prose.
Governance-aware errors
Policy violations return the exact constraint that blocked the operation—your integration knows whether to retry, adjust parameters, or escalate to a human reviewer.
Base URL and versioning
All API requests are made to the following base URL. The version prefix is part of the path and is required on every request.
https://api.arda.vareon.com/v1
Versioning policy
The API uses URL-path versioning. The current stable version is v1. Breaking changes are introduced only in new major versions. Additive changes (new fields, new endpoints) are made within the current version without a version bump.
Deprecation timeline
When a new major version is released, the previous version is supported for 12 months. Deprecated endpoints return a Sunset header with the retirement date and a Deprecation header linking to the migration guide.
Content type
All requests and responses use application/json unless otherwise noted. Dataset upload endpoints accept multipart/form-data. All timestamps are ISO 8601 in UTC.
Authentication
The API supports two authentication models. Both produce the same authorization context and are subject to the same governance policies. All credentials are passed in the Authorization header as Bearer tokens.
API keys for machine clients
Tenant-scoped API keys identify a service or automation pipeline. Keys are prefixed with arda_key_ and can be scoped to specific projects. Keys support rotation without disrupting active sessions. Generate keys from the ARDA dashboard under Settings → API Keys.
curl -X GET https://api.arda.vareon.com/v1/projects \ -H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..." \ -H "Content-Type: application/json"
Session tokens (OAuth flow)
Human users authenticate through an OAuth 2.0 authorization code flow. Session tokens are prefixed with arda_session_, expire after 24 hours, and can be refreshed. Actions performed with session tokens are attributed to the user in the Evidence Ledger.
# Step 1: Exchange authorization code for tokens
curl -X POST https://api.arda.vareon.com/v1/auth/token \
-d '{"grant_type":"authorization_code","code":"auth_code_...","redirect_uri":"https://yourapp.com/callback","client_id":"your_client_id"}'Token exchange response:
{
"access_token": "arda_session_eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "arda_refresh_mG3k8vQp...",
"scope": "projects:read projects:write runs:write claims:read",
"tenant_id": "ten_vareon_prod"
}Core endpoints
Projects
Projects are the top-level organizational boundary. They contain campaigns, datasets, and governance configuration.
POST /v1/projects
GET /v1/projects
GET /v1/projects/:project_id
PATCH /v1/projects/:project_id
Create a project
curl -X POST https://api.arda.vareon.com/v1/projects \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..." \
-H "Content-Type: application/json" \
-d '{
"name": "Turbulence Dynamics Study",
"description": "Discover governing equations for turbulent flow regimes",
"settings": {
"default_mode": "neuro_symbolic",
"governance": {
"promotion_ceiling": "validate",
"require_negative_controls": true,
"truth_dial_threshold": 0.85
}
}
}'Response 201 Created
{
"id": "proj_tds_8f2a1b",
"name": "Turbulence Dynamics Study",
"description": "Discover governing equations for turbulent flow regimes",
"status": "active",
"settings": {
"default_mode": "neuro_symbolic",
"governance": {
"promotion_ceiling": "validate",
"require_negative_controls": true,
"truth_dial_threshold": 0.85
}
},
"created_at": "2026-03-28T10:15:30Z",
"updated_at": "2026-03-28T10:15:30Z",
"created_by": "usr_faruk_01",
"tenant_id": "ten_vareon_prod"
}List projects (paginated)
GET /v1/projects?limit=2&status=active
{
"object": "list",
"data": [
{
"id": "proj_tds_8f2a1b",
"name": "Turbulence Dynamics Study",
"status": "active",
"created_at": "2026-03-28T10:15:30Z"
},
{
"id": "proj_mat_3c7d9e",
"name": "Material Fatigue Analysis",
"status": "active",
"created_at": "2026-03-25T14:22:00Z"
}
],
"has_more": true,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yNVQxNDoyMjowMFoifQ==",
"total_count": 12
}Campaigns
Campaigns group related runs under a shared hypothesis or operational objective. Each campaign has a compute budget and governance configuration that applies to all runs within it.
POST /v1/projects/:project_id/campaigns
GET /v1/projects/:project_id/campaigns
GET /v1/projects/:project_id/campaigns/:campaign_id
Create a campaign
curl -X POST https://api.arda.vareon.com/v1/projects/proj_tds_8f2a1b/campaigns \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..." \
-H "Content-Type: application/json" \
-d '{
"name": "Reynolds Number Sweep",
"description": "Systematic sweep across Re = 1000-10000",
"budget": {
"compute_units": 2500,
"max_runs": 50,
"expires_at": "2026-06-01T00:00:00Z"
},
"governance": {
"promotion_ceiling": "validate",
"require_negative_controls": true,
"auto_promote_to": "explore"
}
}'Response 201 Created
{
"id": "camp_rns_4e8f2a",
"project_id": "proj_tds_8f2a1b",
"name": "Reynolds Number Sweep",
"description": "Systematic sweep across Re = 1000-10000",
"status": "active",
"budget": {
"compute_units": 2500,
"compute_units_used": 0,
"max_runs": 50,
"runs_completed": 0,
"expires_at": "2026-06-01T00:00:00Z"
},
"governance": {
"promotion_ceiling": "validate",
"require_negative_controls": true,
"auto_promote_to": "explore"
},
"created_at": "2026-03-28T10:30:00Z",
"created_by": "usr_faruk_01"
}Runs
Submit discovery runs with mode selection (Symbolic, Neural, Neuro-Symbolic, CDE), poll for progress through pipeline stages, and retrieve results. Runs are immutable once submitted.
POST /v1/projects/:project_id/campaigns/:campaign_id/runs
GET /v1/projects/:project_id/campaigns/:campaign_id/runs
GET /v1/projects/:project_id/campaigns/:campaign_id/runs/:run_id
GET /v1/projects/:project_id/campaigns/:campaign_id/runs/:run_id/status
GET /v1/projects/:project_id/campaigns/:campaign_id/runs/:run_id/results
Submit a discovery run
curl -X POST https://api.arda.vareon.com/v1/projects/proj_tds_8f2a1b/campaigns/camp_rns_4e8f2a/runs \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..." \
-H "Content-Type: application/json" \
-d '{
"mode": "neuro_symbolic",
"dataset_id": "ds_turb_001",
"parameters": {
"target_variables": ["velocity_x", "velocity_y", "pressure"],
"constraints": ["conservation_of_energy", "navier_stokes"],
"max_complexity": 5,
"symbolic_prior": "polynomial",
"neural_backbone": "transformer",
"epochs": 200,
"cross_validate": true
},
"governance": {
"negative_controls": ["shuffle_test", "permutation_test"],
"evidence_threshold": 0.9
}
}'Response 201 Created
{
"id": "run_ns_7a3b2c",
"project_id": "proj_tds_8f2a1b",
"campaign_id": "camp_rns_4e8f2a",
"mode": "neuro_symbolic",
"dataset_id": "ds_turb_001",
"status": "queued",
"created_at": "2026-03-28T10:45:00Z",
"parameters": { "...": "as submitted" },
"compute_units_estimated": 45
}Poll run status
GET /v1/projects/proj_tds_8f2a1b/campaigns/camp_rns_4e8f2a/runs/run_ns_7a3b2c/status
{
"id": "run_ns_7a3b2c",
"status": "running",
"pipeline": {
"current_stage": "symbolic_regression",
"stages": [
{"name": "data_validation", "status": "completed", "duration_ms": 1200},
{"name": "feature_extraction", "status": "completed", "duration_ms": 8400},
{"name": "neural_pretraining", "status": "completed", "duration_ms": 45000},
{"name": "symbolic_regression", "status": "running", "progress": 0.67},
{"name": "negative_controls", "status": "pending"},
{"name": "claim_generation", "status": "pending"}
]
},
"compute_units_used": 32,
"started_at": "2026-03-28T10:45:05Z",
"estimated_completion": "2026-03-28T11:02:00Z"
}Get run results
GET /v1/projects/proj_tds_8f2a1b/campaigns/camp_rns_4e8f2a/runs/run_ns_7a3b2c/results
{
"run_id": "run_ns_7a3b2c",
"status": "completed",
"claims_count": 4,
"artifacts_count": 7,
"summary": {
"best_claim_id": "clm_law_9d4e5f",
"best_claim_type": "law",
"best_claim_score": 0.94,
"negative_controls_passed": true
},
"compute_units_used": 43,
"duration_ms": 1020000,
"completed_at": "2026-03-28T11:02:00Z"
}Claims
Claims are the typed outputs of discovery runs. Each claim carries its type, confidence qualifiers, scope boundaries, and references to the ledger entries that support it. Claims can be promoted through Truth Dial tiers.
GET /v1/projects/:project_id/claims
GET /v1/projects/:project_id/claims/:claim_id
POST /v1/projects/:project_id/claims/:claim_id/promote
List claims (typed structure)
GET /v1/projects/proj_tds_8f2a1b/claims?run_id=run_ns_7a3b2c&limit=2
{
"object": "list",
"data": [
{
"id": "clm_law_9d4e5f",
"type": "law",
"tier": "explore",
"summary": "∂u/∂t + (u·∇)u = -∇p/ρ + ν∇²u",
"expression": "du/dt = -grad(p)/rho + nu * laplacian(u) - (u . grad)(u)",
"score": 0.94,
"scope": {
"variables": ["velocity_x", "velocity_y", "pressure"],
"domain": "Re ∈ [1000, 10000]",
"constraints_satisfied": ["conservation_of_energy", "navier_stokes"]
},
"evidence": {
"r_squared": 0.97,
"negative_controls_passed": true,
"cross_validation_score": 0.93
},
"ledger_entry_id": "led_a1b2c3",
"run_id": "run_ns_7a3b2c",
"created_at": "2026-03-28T11:01:45Z"
},
{
"id": "clm_causal_2f8g3h",
"type": "causal",
"tier": "explore",
"summary": "Pressure gradient drives velocity field evolution",
"cause": "pressure_gradient",
"effect": "velocity_field",
"direction": "unidirectional",
"temporal_scope": "instantaneous",
"intervention_markers": ["pressure_boundary_perturbation"],
"score": 0.88,
"scope": {
"variables": ["pressure", "velocity_x", "velocity_y"],
"domain": "Re ∈ [1000, 10000]"
},
"evidence": {
"granger_score": 0.91,
"intervention_effect_size": 0.85,
"negative_controls_passed": true
},
"ledger_entry_id": "led_d4e5f6",
"run_id": "run_ns_7a3b2c",
"created_at": "2026-03-28T11:01:50Z"
}
],
"has_more": true,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yOFQxMTowMTo1MFoifQ=="
}Promote a claim
curl -X POST https://api.arda.vareon.com/v1/projects/proj_tds_8f2a1b/claims/clm_law_9d4e5f/promote \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..." \
-H "Content-Type: application/json" \
-d '{
"target_tier": "validate",
"rationale": "Passed all negative controls, cross-validated on held-out data, consistent with known Navier-Stokes formulation."
}'Response 200 OK
{
"id": "clm_law_9d4e5f",
"type": "law",
"tier": "validate",
"previous_tier": "explore",
"promoted_at": "2026-03-28T12:00:00Z",
"promoted_by": "usr_faruk_01",
"rationale": "Passed all negative controls, cross-validated on held-out data, consistent with known Navier-Stokes formulation.",
"ledger_entry_id": "led_g7h8i9",
"governance_checks": {
"truth_dial_score": 0.94,
"threshold_met": true,
"negative_controls": "passed",
"policy_ceiling": "validate",
"within_ceiling": true
}
}Datasets
Upload scientific datasets and retrieve automated profiling results. The platform validates data quality and generates statistical summaries before datasets become available for discovery runs.
POST /v1/projects/:project_id/datasets
GET /v1/projects/:project_id/datasets
GET /v1/projects/:project_id/datasets/:dataset_id
GET /v1/projects/:project_id/datasets/:dataset_id/profile
Upload a dataset
curl -X POST https://api.arda.vareon.com/v1/projects/proj_tds_8f2a1b/datasets \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..." \
-F "file=@turbulence_data.parquet" \
-F 'metadata={"name":"Turbulence Re=5000","format":"parquet","variables":["velocity_x","velocity_y","pressure","time"]}'Response 201 Created
{
"id": "ds_turb_001",
"name": "Turbulence Re=5000",
"format": "parquet",
"status": "profiling",
"size_bytes": 15728640,
"rows": 250000,
"variables": ["velocity_x", "velocity_y", "pressure", "time"],
"created_at": "2026-03-28T09:00:00Z",
"profile_ready": false
}Get dataset profile
GET /v1/projects/proj_tds_8f2a1b/datasets/ds_turb_001/profile
{
"dataset_id": "ds_turb_001",
"status": "ready",
"row_count": 250000,
"column_count": 4,
"columns": [
{"name": "velocity_x", "dtype": "float64", "mean": 2.34, "std": 0.89, "null_count": 0},
{"name": "velocity_y", "dtype": "float64", "mean": 0.12, "std": 1.45, "null_count": 0},
{"name": "pressure", "dtype": "float64", "mean": 101325.0, "std": 250.3, "null_count": 0},
{"name": "time", "dtype": "float64", "mean": 5.0, "std": 2.89, "null_count": 0}
],
"quality": {
"completeness": 1.0,
"duplicate_rows": 0,
"outlier_fraction": 0.002
},
"profiled_at": "2026-03-28T09:02:30Z"
}Evidence Ledger
The Evidence Ledger records every governance-relevant event: claim promotions, negative control results, policy evaluations, and Truth Dial score changes. Ledger entries are immutable and form the audit trail for all discovery activity.
GET /v1/projects/:project_id/ledger
GET /v1/projects/:project_id/ledger/:entry_id
List ledger entries
GET /v1/projects/proj_tds_8f2a1b/ledger?claim_id=clm_law_9d4e5f&limit=3
{
"object": "list",
"data": [
{
"id": "led_a1b2c3",
"event_type": "claim_created",
"claim_id": "clm_law_9d4e5f",
"run_id": "run_ns_7a3b2c",
"details": {
"claim_type": "law",
"initial_tier": "explore",
"truth_dial_score": 0.94,
"negative_controls": {
"shuffle_test": {"passed": true, "p_value": 0.001},
"permutation_test": {"passed": true, "p_value": 0.003}
}
},
"actor": "system",
"timestamp": "2026-03-28T11:01:45Z"
},
{
"id": "led_g7h8i9",
"event_type": "claim_promoted",
"claim_id": "clm_law_9d4e5f",
"details": {
"from_tier": "explore",
"to_tier": "validate",
"rationale": "Passed all negative controls, cross-validated on held-out data...",
"governance_evaluation": {
"policy_ceiling": "validate",
"within_ceiling": true,
"truth_dial_threshold_met": true
}
},
"actor": "usr_faruk_01",
"timestamp": "2026-03-28T12:00:00Z"
},
{
"id": "led_j1k2l3",
"event_type": "negative_control_evaluated",
"claim_id": "clm_law_9d4e5f",
"details": {
"control_type": "cross_dataset_validation",
"result": "passed",
"validation_dataset_id": "ds_turb_002",
"score": 0.91
},
"actor": "system",
"timestamp": "2026-03-28T12:05:00Z"
}
],
"has_more": false
}Resource model
Resources are organized hierarchically. A project contains campaigns and datasets. Campaigns contain runs. Runs produce claims and artifacts. This hierarchy is reflected in URL structure: /v1/projects/:id/campaigns/:id/runs/:id.
Cross-cutting resources like claims and ledger entries are accessible both through the hierarchy (scoped to a run) and through project-level endpoints (for cross-campaign queries). This dual access pattern supports both focused auditing and broad exploration.
Webhooks
Register webhook endpoints to receive real-time notifications for asynchronous events. Webhooks eliminate the need to poll for run completion or claim promotion—the platform pushes events to your endpoint as they occur.
Supported events
run.completed— A discovery run has finishedrun.failed— A run encountered an errorclaim.promoted— A claim advanced tiersclaim.created— New claims generateddataset.profiled— Dataset profiling completebudget.exhausted— Campaign budget depleted
Security
Every webhook request includes an X-Arda-Signature header containing an HMAC-SHA256 signature of the payload using your webhook secret. Verify this signature before processing events. Events are retried with exponential backoff for up to 72 hours if your endpoint returns a non-2xx response.
Register a webhook
curl -X POST https://api.arda.vareon.com/v1/webhooks \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/arda",
"events": ["run.completed", "claim.promoted"],
"project_id": "proj_tds_8f2a1b",
"secret": "whsec_your_signing_secret"
}'Webhook payload example
{
"id": "evt_4f5g6h",
"type": "run.completed",
"created_at": "2026-03-28T11:02:00Z",
"data": {
"run_id": "run_ns_7a3b2c",
"project_id": "proj_tds_8f2a1b",
"campaign_id": "camp_rns_4e8f2a",
"mode": "neuro_symbolic",
"status": "completed",
"claims_count": 4,
"duration_ms": 1020000
}
}Error handling
The API returns structured error responses with a consistent shape. Every error includes a machine-readable code, a human-readable message, and optional detail fields specific to the error type.
{
"error": {
"code": "governance_policy_violation",
"message": "Promotion to 'publish' tier is blocked by the active governance policy.",
"status": 403,
"details": {
"claim_id": "clm_law_9d4e5f",
"requested_tier": "publish",
"policy_ceiling": "validate",
"truth_dial_score": 0.94,
"constraint": "promotion_ceiling_exceeded"
},
"request_id": "req_8f3a2b1c",
"documentation_url": "https://www.vareon.com/arda/docs/api#errors"
}
}HTTP status codes
400 — Validation error (malformed request body, invalid parameters)
401 — Authentication failure (missing, expired, or invalid credentials)
403 — Policy violation (governance ceiling exceeded, insufficient scope)
404 — Resource not found
409 — Conflict (duplicate run submission, concurrent modification)
422 — Unprocessable entity (dataset format unsupported, constraint invalid)
429 — Rate limit exceeded
500 — Internal server error
503 — Service unavailable (platform maintenance or capacity)
Governance-specific errors
governance_policy_violation — Operation would exceed the governance ceiling
truth_dial_threshold_not_met — Claim score is below the required threshold
negative_controls_required — Promotion requires passing negative controls first
budget_exhausted — Campaign compute budget has been fully consumed
ledger_integrity_error — Ledger chain validation failed (contact support)
Rate limiting
Rate limits are communicated through response headers on every request. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.
Response headers
X-RateLimit-Limit — Maximum requests per window
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the window resets
Retry-After — Seconds to wait before retrying (on 429 only)
Tier-based limits
Free — 60 requests/minute, 10 concurrent runs
Team — 600 requests/minute, 50 concurrent runs
Enterprise — 6,000 requests/minute, 500 concurrent runs
Run submission endpoints have separate, lower limits to protect platform compute capacity.
Recommended backoff strategy
# Exponential backoff with jitter — pseudocode
base_delay = 1.0 # seconds
max_delay = 60.0
for attempt in range(max_retries):
response = make_request()
if response.status != 429:
break
retry_after = response.headers.get("Retry-After")
if retry_after:
sleep(float(retry_after))
else:
delay = min(base_delay * (2 ** attempt) + random(0, 1), max_delay)
sleep(delay)Cursor-based pagination
All list endpoints use cursor-based pagination, which is reliable even when the underlying dataset changes between requests—critical when discovery runs are producing new claims in real time.
Request parameters
limit — Number of items per page (default: 20, max: 100)
cursor — Opaque cursor from a previous response
sort — Field to sort by (e.g., created_at)
order — asc or desc
Response shape
data — Array of resource objects
has_more — Boolean indicating more pages exist
next_cursor — Opaque string for the next page (absent on last page)
total_count — Total matching resources (when available)
Full pagination example
# First page
curl -X GET "https://api.arda.vareon.com/v1/projects/proj_tds_8f2a1b/claims?type=causal&tier=validate&limit=2&sort=created_at&order=desc" \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..."
# Response
{
"object": "list",
"data": [
{"id": "clm_causal_2f8g3h", "type": "causal", "tier": "validate", "summary": "Pressure gradient drives velocity field evolution", "created_at": "2026-03-28T11:01:50Z"},
{"id": "clm_causal_5j6k7l", "type": "causal", "tier": "validate", "summary": "Viscosity modulates turbulent energy cascade rate", "created_at": "2026-03-27T15:30:00Z"}
],
"has_more": true,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yN1QxNTozMDowMFoifQ==",
"total_count": 8
}
# Next page — pass the cursor
curl -X GET "https://api.arda.vareon.com/v1/projects/proj_tds_8f2a1b/claims?type=causal&tier=validate&limit=2&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yN1QxNTozMDowMFoifQ==" \
-H "Authorization: Bearer arda_key_sk_live_7f3a9b2c..."
Prefer strongly typed clients? The Python SDK (arda-sdk) wraps these endpoints with models, automatic retries, and async support. For agent tool-use, the MCP server exposes the same resources as callable tools.
All three interfaces — REST, SDK, and MCP — share the same resource model, authentication, and governance stack.