beacn API
Access posts, embeddings, semantic search, and the goodness direction — a collective alignment signal derived from community votes on visions of positive futures.
All tiers are free during the open beta.
Contents
Authentication
Generate an API key from your account settings, then include it in every request as a Bearer token:
Authorization: Bearer beacn_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2Some endpoints (goodness direction, posts without embeddings, stats) are accessible without a key, subject to lower rate limits.
Rate Limits
| Tier | Requests/min | Price |
|---|---|---|
| No key (IP-based) | 30 | Free |
| Free | 60 | Free |
| Researcher | 120 | Free |
| Enterprise | 300 | Free |
Rate-limited responses return 429 with a Retry-After header.
Goodness Direction
The goodness direction is beacn's primary output: a 3072-dimensional vector in Gemini embedding space representing what the community collectively values. Derived from voting patterns via preference field analysis.
/api/v1/goodness-directionPublicReturns the current goodness direction vector. Recomputed every 5 minutes.
{
"data": {
"vector": [0.0123, -0.0456, ...],
"dimensions": 3072,
"total_posts_contributing": 847,
"total_votes_contributing": 12453,
"last_computed_at": "2026-03-29T12:00:00Z",
"computation_method": "preference_field_weighted"
}
}/api/v1/goodness-direction/historyAPI Key RequiredHistorical snapshots of the goodness direction over time.
Query params: from, to (ISO 8601), page, per_page
Future Compass Choices
An open dataset of pairwise human preferences over possible futures. In the Future Compass, people choose which of two visions they would rather live in. Pairs are scheduled so every vision gets judged, and left/right placement is randomized. Participants appear only as stable keyed pseudonyms. Join the post ids against /api/v1/posts (and its embeddings) to fit Bradley–Terry or reward models over futures.
/api/v1/compass/choicesPublicEvery choice, oldest first. A skipped pair has chosen_post_id null. Choices about removed posts are excluded.
Query params: page, per_page (max 1000), created_after, created_before (ISO 8601, for incremental exports)
{
"data": [
{
"id": "cm2…",
"participant": "3f9c0a7d51e2b864",
"left_post_id": "cm1…",
"right_post_id": "cm1…",
"chosen_post_id": "cm1…",
"latency_ms": 2140,
"created_at": "2026-10-09T12:00:00.000Z"
}
],
"meta": { "page": 1, "per_page": 1000, "total": 1, "has_more": false }
}Posts
/api/v1/postsKey OptionalPaginated list of posts. Embeddings require an API key.
Query params: page, per_page, sort (new|top|hot), period (today|week|month|all), include_embeddings, created_after, created_before
/api/v1/posts/:idKey OptionalSingle post with full details. Embedding requires an API key.
Query params: include_embedding
/api/v1/posts/:id/similarAPI Key RequiredPosts most similar by cosine similarity in embedding space.
Query params: limit (max 50), min_similarity, include_embeddings
Search
/api/v1/search/semanticAPI Key RequiredSemantic search — embed a text query and find the most similar posts.
{
"query": "renewable energy and sustainable cities",
"limit": 20,
"min_similarity": 0.3,
"include_embeddings": false
}/api/v1/search/vectorAPI Key RequiredVector search — provide a raw 3072-dimensional vector to find similar posts.
{
"vector": [0.0123, -0.0456, ...],
"limit": 20,
"min_similarity": 0.3
}Bulk Embeddings
/api/v1/embeddings/bulkAPI Key RequiredPaginated export of all post embeddings. Supports JSON and CSV.
Query params: page, per_page (max 500), format (json|csv), include_vote_counts, created_after, created_before
/api/v1/statsPublicAggregate platform statistics: total posts, votes, users, embeddings, and goodness direction last updated.
Code Examples
Fetch the Goodness Direction (Python)
import requests
import numpy as np
resp = requests.get("https://beacn.space/api/v1/goodness-direction")
data = resp.json()["data"]
goodness = np.array(data["vector"])
print(f"Dimensions: {data['dimensions']}")
print(f"Contributing posts: {data['total_posts_contributing']}")
print(f"Magnitude: {np.linalg.norm(goodness):.4f}")Semantic Search (JavaScript)
const response = await fetch("https://beacn.space/api/v1/search/semantic", {
method: "POST",
headers: {
"Authorization": "Bearer beacn_your_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "clean energy futures",
limit: 10,
}),
});
const { data } = await response.json();
for (const { post, similarity } of data.results) {
console.log(`[${similarity.toFixed(3)}] ${post.title}`);
}Cosine Similarity with the Goodness Direction (Python)
import requests
import numpy as np
API_KEY = "beacn_your_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}
# Get the goodness direction
gd = requests.get("https://beacn.space/api/v1/goodness-direction")
goodness = np.array(gd.json()["data"]["vector"])
# Get a post's embedding
post = requests.get(
"https://beacn.space/api/v1/posts/YOUR_POST_ID?include_embedding=true",
headers=headers,
)
embedding = np.array(post.json()["data"]["embedding"])
# Compute alignment
similarity = np.dot(goodness, embedding) / (
np.linalg.norm(goodness) * np.linalg.norm(embedding)
)
print(f"Alignment with goodness direction: {similarity:.4f}")Bulk Download Embeddings (Python)
import requests
API_KEY = "beacn_your_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}
page = 1
all_embeddings = []
while True:
resp = requests.get(
f"https://beacn.space/api/v1/embeddings/bulk?page={page}&per_page=500",
headers=headers,
)
data = resp.json()
all_embeddings.extend(data["data"]["embeddings"])
if not data["meta"]["has_more"]:
break
page += 1
print(f"Downloaded {len(all_embeddings)} embeddings")Questions or feedback? Open an issue on GitHub