API Documentation

Authentication

Include your API key in the Authorization header for every request:

Authorization: Bearer fsk_your_key

API keys start with fsk_. Keep your key secret — do not expose it in client-side code or public repositories.

Base URL

All API requests use the following base URL:

https://api.futuresignals.com/api/v1

Endpoints

GET/feed

Retrieve the homepage feed with date-grouped clusters.

Parameters

Name	Type	Required	Description
cursor	string	No	Date cursor (YYYY-MM-DD) for pagination.
limit	integer	No	Number of date groups (1-7, default 3).
locale	string	No	Response locale (en, lt).

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/feed?limit=3"

Response

{
  "data": [
    {
      "date": "2026-05-03",
      "clusters": [
        {
          "id": 42,
          "title": "GPT-5 Achieves PhD-Level Reasoning",
          "summary": "OpenAI's latest model demonstrates...",
          "source_name": "OpenAI Blog",
          "source_url": "https://openai.com/blog/gpt-5",
          "image_url": "https://...",
          "category": { "slug": "artificial-intelligence" },
          "score_tier": "hero",
          "published_at": "2026-05-03T08:00:00Z"
        }
      ],
      "total_for_date": 8
    }
  ],
  "meta": { "next_cursor": "2026-05-02", "has_more": true }
}

GET/feed/date/{date}

All clusters for a specific date with standard pagination.

Parameters

Name	Type	Required	Description
date	string	Yes	Date in YYYY-MM-DD format (path parameter).
page	integer	No	Page number (default 1).
per_page	integer	No	Items per page (1-50, default 30).

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/feed/date/2026-05-03"

Response

{
  "data": [{ "id": 42, "title": "...", "score_tier": "hero", ... }],
  "meta": { "current_page": 1, "per_page": 30, "total": 12, "last_page": 1 }
}

GET/feed/category/{slug}

Category-filtered feed with date-grouped clusters.

Parameters

Name	Type	Required	Description
slug	string	Yes	Category slug (e.g. artificial-intelligence).
cursor	string	No	Date cursor for pagination.
limit	integer	No	Date groups to return (1-7, default 3).

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/feed/category/artificial-intelligence"

Response

{
  "data": [{ "date": "2026-05-03", "clusters": [...] }],
  "meta": { "next_cursor": "2026-05-02", "has_more": true, "category": { "name": "AI", "slug": "artificial-intelligence" } }
}

GET/search

Full-text search across clusters ranked by relevance.

Parameters

Name	Type	Required	Description
q	string	Yes	Search query (min 2 characters).
category	string	No	Filter by category slug.
page	integer	No	Page number (default 1).
per_page	integer	No	Results per page (1-50, default 20).

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/search?q=fusion+energy"

Response

{
  "data": [{ "id": 87, "title": "Commonwealth Fusion Systems...", "score_tier": "prominent", ... }],
  "meta": { "query": "fusion energy", "current_page": 1, "total": 5 }
}

GET/categories

List all categories with nested subcategories.

Parameters

Name	Type	Required	Description
locale	string	No	Response locale.

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/categories"

Response

{
  "data": [
    {
      "id": 1,
      "name": "AI",
      "slug": "artificial-intelligence",
      "color": "#8B5CF6",
      "subcategories": [
        { "id": 1, "name": "Foundation Models", "slug": "foundation-models" }
      ]
    }
  ]
}

GET/entities

Browse entities (companies, people, technologies) mentioned in stories.

Parameters

Name	Type	Required	Description
type	string	No	Filter by entity type (company, person, technology, institution, product, government_body).
category	string	No	Filter by category slug.
q	string	No	Search by entity name.
sort	string	No	Sort order: mentions (default), recent, name.
page	integer	No	Page number.

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/entities?type=company&sort=mentions"

Response

{
  "data": [
    {
      "id": 1,
      "name": "OpenAI",
      "slug": "openai",
      "type": "company",
      "mention_count": 342,
      "first_seen_at": "2026-01-15",
      "last_seen_at": "2026-05-03"
    }
  ],
  "meta": { "current_page": 1, "total": 150 }
}

GET/entities/{slug}

Detailed entity profile with recent stories and related entities.

Parameters

Name	Type	Required	Description
slug	string	Yes	Entity slug (path parameter).
locale	string	No	Response locale.

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/entities/openai"

Response

{
  "data": {
    "id": 1,
    "name": "OpenAI",
    "slug": "openai",
    "type": "company",
    "description": "AI research and deployment company...",
    "mention_count": 342,
    "recent_clusters": [...],
    "related_entities": [...]
  }
}

GET/entities/{slug}/timeline

Paginated timeline of entity mentions across stories.

Parameters

Name	Type	Required	Description
slug	string	Yes	Entity slug (path parameter).
page	integer	No	Page number.
per_page	integer	No	Items per page (1-50, default 20).

Example

curl -H "Authorization: Bearer fsk_your_key" \
  "https://api.futuresignals.com/api/v1/entities/openai/timeline"

Response

{
  "data": [
    {
      "cluster_id": 42,
      "cluster_title": "GPT-5 Achieves PhD-Level Reasoning",
      "mention_type": "primary",
      "published_at": "2026-05-03T08:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "total": 85, "last_page": 5 }
}

Rate Limits

Rate limits are applied per API key and vary by tier:

Tier	Rate Limit	Monthly Quota
Free	10 req/min	100/day
Starter	30 req/min	10,000/month
Growth	60 req/min	50,000/month
Scale	120 req/min	Unlimited

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{ "error": "rate_limit_exceeded", "message": "Too many requests. Retry after 30 seconds." }

Errors

All errors follow a consistent JSON format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "errors": { "field": ["Validation message"] }  // only for 422
}

Status	Error Code	Description
400	bad_request	Malformed request or missing required parameters.
401	unauthorized	Missing or invalid API key.
403	forbidden	API key lacks permission for this endpoint or tier.
404	not_found	Resource not found.
422	validation_error	Request validation failed. Check the errors field.
429	rate_limit_exceeded	Rate or quota limit exceeded. See Retry-After header.
500	server_error	Internal server error. Retry with exponential backoff.