Worker API

The Cloudflare Worker API is the production-ready interface to ACP. It runs on the edge with Vectorize for axiom search and KV for semantic caching. Base URL: https://your-worker.workers.dev

Local development

Run the Worker locally with wrangler dev at http://localhost:8787. All endpoints behave identically.

Endpoint Overview

Method	Path	Description
`GET`	`/`	Welcome message
`GET`	`/health`	Health check and Vectorize status
`POST`	`/consensus-iterative`	Run iterative consensus with phi-spiral
`GET`	`/axioms/search?q=`	Search axioms by semantic similarity
`POST`	`/cache/check`	Check semantic cache for a query
`GET`	`/cache/stats`	Cache performance statistics
`GET`	`/similar?q=`	Find similar past queries
`POST`	`/embeddings`	Generate text embeddings
`GET`	`/metrics`	Prometheus-format metrics

GET / -- Welcome

Returns a simple welcome message confirming the service is reachable. No authentication required.

Request

curl https://your-worker.workers.dev/

GET /health -- Health Check

Returns the service status, version, and Vectorize availability. Use this endpoint for uptime monitoring.

Request

curl https://your-worker.workers.dev/health

Response 200

{
  "status": "healthy",
  "service": "ACP Consensus Worker",
  "version": "4.0.0",
  "vectorize": {
    "available": true,
    "ai_available": true,
    "axioms_seeded": true
  }
}

POST /consensus-iterative -- Iterative Consensus

The primary endpoint for running multi-model consensus. It uses the phi-spiral convergence algorithm: each iteration anchors on successively higher axiom levels, reducing the D-score by the golden ratio until consensus is reached or the maximum iterations are exhausted.

Headers

Header	Required	Description
`x-api-key`	Yes (if configured)	Your ACP API key
`x-openrouter-key`	Optional	Your own OpenRouter key for LLM calls
`Content-Type`	Yes	`application/json`

Request Body

Field	Type	Required	Description
`query`	`string`	Yes	The question or prompt to reach consensus on
`models`	`string[]`	No	OpenRouter model identifiers. Defaults to server-configured models.
`skip_cache`	`boolean`	No	Skip semantic cache lookup (default: false)

Request body example

{
  "query": "What is 2 + 2?",
  "models": ["anthropic/claude-haiku-4-5", "openai/gpt-5.4-mini"],
  "skip_cache": false
}

cURL example

curl -X POST https://your-worker.workers.dev/consensus-iterative \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_key" \
  -d '{
    "query": "What is 2 + 2?",
    "models": ["anthropic/claude-haiku-4-5", "openai/gpt-5.4-mini"],
    "skip_cache": false
  }'

Response

Field	Type	Description
`consensus_reached`	`boolean`	Whether models converged to consensus
`final_answer`	`string`	The synthesized consensus answer
`confidence`	`number`	Confidence score (0 to 1)
`iterations`	`number`	Number of phi-spiral iterations used
`metrics.initial_D`	`number`	Starting divergence score
`metrics.final_D`	`number`	Final divergence score after convergence
`metrics.H_total`	`number`	Total harmony score (H = 1 - D)
`cache_hit`	`boolean`	Whether the result came from the semantic cache
`relevant_axioms`	`array`	Axioms used to anchor consensus

Response 200

{
  "consensus_reached": true,
  "final_answer": "4",
  "confidence": 0.95,
  "iterations": 2,
  "metrics": {
    "initial_D": 0.15,
    "final_D": 0.02,
    "H_total": 0.98
  },
  "cache_hit": false,
  "relevant_axioms": [
    {
      "id": "axiom_L1_001",
      "axiom": "Addition is commutative: a + b = b + a",
      "level": 1,
      "relevance": 0.94
    }
  ]
}

GET /axioms/search -- Search Axioms

Search the axiom database by semantic similarity. Returns matching axioms ranked by relevance score.

Query Parameters

Parameter	Type	Default	Description
`q`	`string`	required	Search query text
`topK`	`integer`	5	Maximum number of results to return
`level`	`string`	all	Comma-separated axiom levels to filter (1-7)
`minScore`	`float`	0.7	Minimum relevance score threshold

Request

curl "https://your-worker.workers.dev/axioms/search?q=machine+learning&level=5,6,7&topK=5&minScore=0.7" \
  -H "x-api-key: your_key"

Response 200

{
  "query": "machine learning",
  "axioms": [
    {
      "id": "axiom_L5_001",
      "axiom": "Neural networks implement gradient descent",
      "level": 5,
      "levelName": "architectural",
      "domain": "ML",
      "description": "Neural network training fundamentally relies on gradient descent optimization.",
      "relevance": 0.89
    }
  ],
  "count": 1
}

POST /cache/check -- Semantic Cache Check

Check whether a semantically similar query has already been answered. ACP uses vector embeddings to match queries, so "What is two plus two?" will match a cached result for "What is 2+2?".

Request

curl -X POST https://your-worker.workers.dev/cache/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_key" \
  -d '{"query": "What is two plus two?"}'

Response 200 (cache hit)

{
  "hit": true,
  "similarity": 0.95,
  "cached_query": "What is 2+2?",
  "result": {
    "final_answer": "4",
    "confidence": 0.95
  }
}

Response 200 (cache miss)

{
  "hit": false
}

GET /cache/stats -- Cache Statistics

Returns aggregate cache performance metrics. Useful for monitoring and tuning your cache hit rate.

Request

curl https://your-worker.workers.dev/cache/stats \
  -H "x-api-key: your_key"

Response 200

{
  "total_queries": 1234,
  "cache_hits": 567,
  "hit_rate": 0.46,
  "avg_similarity": 0.92
}

GET /similar -- Find Similar Queries

Find past queries that are semantically similar to a given input. Returns results ranked by similarity score.

Parameter	Type	Default	Description
`q`	`string`	required	Query to compare against
`topK`	`integer`	5	Maximum number of results
`minScore`	`float`	0.7	Minimum similarity threshold

Request

curl "https://your-worker.workers.dev/similar?q=sum+of+2+and+2&topK=5&minScore=0.7" \
  -H "x-api-key: your_key"

Response 200

{
  "query": "sum of 2 and 2",
  "similar": [
    {
      "query": "What is 2+2?",
      "similarity": 0.91,
      "result_id": "res_abc123",
      "created_at": 1703500000
    }
  ],
  "count": 1
}

POST /embeddings -- Generate Embeddings

Generate 768-dimensional vector embeddings for one or more text inputs. Uses the same embedding model as the axiom search and semantic cache.

Request

curl -X POST https://your-worker.workers.dev/embeddings \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_key" \
  -d '{"text": "What is machine learning?"}'

Response 200

{
  "embedding": [0.0123, -0.0456, 0.0789, "... (768 dimensions)"],
  "model": "bge-base-en-v1.5",
  "dimensions": 768
}

GET /metrics -- Prometheus Metrics

Returns metrics in Prometheus exposition format. Use this for integration with Grafana, Datadog, or other monitoring systems.

Request

curl https://your-worker.workers.dev/metrics

Response 200

# HELP acp_requests_total Total requests
# TYPE acp_requests_total counter
acp_requests_total 12345

# HELP acp_consensus_duration_seconds Consensus duration
# TYPE acp_consensus_duration_seconds histogram
acp_consensus_duration_seconds_bucket{le="1"} 1000

Monitoring

The /metrics and /health endpoints do not require authentication, making them safe to expose to external monitoring tools.

API Reference

Python API